From bb29e162214263268b9753ceb56eb9b9a08338af Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Fri, 3 Jun 2022 17:34:58 +0700 Subject: [PATCH 1/8] Add IPROTO_TIMEOUT constant --- doc/dev_guide/internals/box_protocol.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/dev_guide/internals/box_protocol.rst b/doc/dev_guide/internals/box_protocol.rst index 409c05bd6d..ec733ce668 100644 --- a/doc/dev_guide/internals/box_protocol.rst +++ b/doc/dev_guide/internals/box_protocol.rst @@ -143,6 +143,7 @@ The IPROTO constants that appear within requests or responses that we will descr IPROTO_RAFT_VCLOCK=0x03 IPROTO_VERSION=0x54 IPROTO_FEATURES=0x55 + IPROTO_TIMEOUT=0x56 To denote message descriptions we will say ``msgpack(...)`` and within it we will use modified From 18699bf455762dca6a9ead4521ac993dac8da64a Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Mon, 6 Jun 2022 12:47:17 +0700 Subject: [PATCH 2/8] Add IPROTO_TIMEOUT explanation --- doc/dev_guide/internals/box_protocol.rst | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/doc/dev_guide/internals/box_protocol.rst b/doc/dev_guide/internals/box_protocol.rst index ec733ce668..48c3604339 100644 --- a/doc/dev_guide/internals/box_protocol.rst +++ b/doc/dev_guide/internals/box_protocol.rst @@ -1282,16 +1282,20 @@ each call to conn:new_stream() assigns a new number, starting with 1. .. _box_protocol-stream_transactions: The client makes stream transactions by sending, in order: -IPROTO_BEGIN, the transaction data-change and query requests, -IPROTO_COMMIT or IPROTO_ROLLBACK. -Each request must contain the same IPROTO_STREAM_ID value. -With streaming there is no need to add -:ref:`IPROTO_FLAGS ` and IPROTO_FLAG_COMMIT -in the header of the last request of a transaction. -Rollback will be automatic if disconnect occurs before commit is possible. + +1. IPROTO_BEGIN with an optional transaction timeout in the IPROTO_TIMEOUT field of the request body +2. the transaction data-change and query requests +3. IPROTO_COMMIT or IPROTO_ROLLBACK + +All these requests must contain the same IPROTO_STREAM_ID value. + +With streaming, there is no need to add +:ref:`IPROTO_FLAGS ` and IPROTO_FLAG_COMMIT in the header +of the last request of a transaction. A rollback will happen automatically if +a disconnect occurs or the transaction timeout expires before the commit is possible. Thus there are now multiple ways to do transactions: -with net_box and stream:begin() and stream:commit() or stream:rollback() +with ``net_box`` ``stream:begin()`` and ``stream:commit()`` or ``stream:rollback()`` which cause IPROTO_BEGIN and IPROTO_COMMIT or IPROTO_ROLLBACK with the current value of stream.stream_id; with :ref:`box.begin() ` and :ref:`box.commit() ` or :ref:`box.rollback() `; From b57c661b720a7a89b7900cc344008913baff2d4f Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Mon, 6 Jun 2022 16:25:21 +0700 Subject: [PATCH 3/8] Fix IPROTO_RAFT_* request names, remove confusing sentence. --- doc/dev_guide/internals/box_protocol.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/doc/dev_guide/internals/box_protocol.rst b/doc/dev_guide/internals/box_protocol.rst index 48c3604339..590a450fe8 100644 --- a/doc/dev_guide/internals/box_protocol.rst +++ b/doc/dev_guide/internals/box_protocol.rst @@ -749,7 +749,7 @@ regular connections. .. _box_protocol-confirm: -IPROTO_CONFIRM = 0x28 +IPROTO_RAFT_CONFIRM = 0x28 ~~~~~~~~~~~~~~~~~~~~~ This message confirms that the transactions originated from the instance @@ -778,7 +778,7 @@ The body is a 2-item map: .. _box_protocol-rollback: -IPROTO_ROLLBACK = 0x29 +IPROTO_RAFT_ROLLBACK = 0x29 ~~~~~~~~~~~~~~~~~~~~~~ This message says that the transactions originated from the instance @@ -1289,9 +1289,7 @@ The client makes stream transactions by sending, in order: All these requests must contain the same IPROTO_STREAM_ID value. -With streaming, there is no need to add -:ref:`IPROTO_FLAGS ` and IPROTO_FLAG_COMMIT in the header -of the last request of a transaction. A rollback will happen automatically if +A rollback will happen automatically if a disconnect occurs or the transaction timeout expires before the commit is possible. Thus there are now multiple ways to do transactions: From e28a9c64c237b5d5971a9fa8016d4d1342f1052f Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Mon, 6 Jun 2022 17:54:17 +0700 Subject: [PATCH 4/8] Add sections for stream transaction requests --- doc/dev_guide/internals/box_protocol.rst | 95 +++++++++++++++++++++++- 1 file changed, 93 insertions(+), 2 deletions(-) diff --git a/doc/dev_guide/internals/box_protocol.rst b/doc/dev_guide/internals/box_protocol.rst index 590a450fe8..7fdd01bdc7 100644 --- a/doc/dev_guide/internals/box_protocol.rst +++ b/doc/dev_guide/internals/box_protocol.rst @@ -144,6 +144,7 @@ The IPROTO constants that appear within requests or responses that we will descr IPROTO_VERSION=0x54 IPROTO_FEATURES=0x55 IPROTO_TIMEOUT=0x56 + IPROTO_TXN_ISOLATION = 0x59, To denote message descriptions we will say ``msgpack(...)`` and within it we will use modified @@ -707,6 +708,96 @@ IPROTO_SQL_TEXT (0x40) and statement-text (string) if executing an SQL string. Thus the IPROTO_PREPARE map item is the same as the first item of the :ref:`IPROTO_EXECUTE ` body. +.. _box_protocol-begin: + +IPROTO_BEGIN = 0x0e +~~~~~~~~~~~~~~~~~~~~~ + +Begin a transaction in the specified stream. +See :ref:`stream:begin() `. +The body is optional and can contain two items: + +.. cssclass:: highlight +.. parsed-literal:: + + # + msgpack(:samp:`{{MP_UINT unsigned integer = size(
) + size()}}`) + #
+ msgpack({ + IPROTO_REQUEST_TYPE: IPROTO_BEGIN, + IPROTO_SYNC: :samp:`{{MP_UINT unsigned integer}}` + IPROTO_STREAM_ID: :samp:`{{MP_UINT unsigned integer}}` + }) + # + msgpack({ + IPROTO_TIMEOUT: :samp:`{{MP_DOUBLE}}` + IPROTO_TXN_ISOLATION: :samp:`{{MP_UINT unsigned integer}}` + }) + +IPROTO_TIMEOUT is an optional timeout (in seconds). After it expires, +the transaction will be rolled back automatically. + +-- TODO: add link to transaction isolation docs once they're ready +IPROTO_TXN_ISOLATION is the transaction isolation level. It can take +the following values: + +-- TODO: provide links to level descriptions +- ``TXN_ISOLATION_DEFAULT = 0`` -- use the global default level +- ``TXN_ISOLATION_READ_COMMITTED = 1`` -- read committed, but not confirmed changes +- ``TXN_ISOLATION_READ_CONFIRMED = 2`` -- read only confirmed changes +- ``TXN_ISOLATION_BEST_EFFORD = 3`` -- determine isolation level automatically + +See :ref:`Binary protocol -- streams ` to learn more about +stream transactions in the binary protocol. + + +.. _box_protocol-commit: + +IPROTO_COMMIT = 0x0f +~~~~~~~~~~~~~~~~~~~~~ + +Commit the transaction in the specified stream. +See :ref:`stream:commit() `. + +.. cssclass:: highlight +.. parsed-literal:: + + # + msgpack(:samp:`{{MP_UINT unsigned integer = size(
) + size()}}`) + #
+ msgpack({ + IPROTO_REQUEST_TYPE: IPROTO_COMMIT, + IPROTO_SYNC: :samp:`{{MP_UINT unsigned integer}}` + IPROTO_STREAM_ID: :samp:`{{MP_UINT unsigned integer}}` + }) + +See :ref:`Binary protocol -- streams ` to learn more about +stream transactions in the binary protocol. + + +.. _box_protocol-rollback: + +IPROTO_ROLLBACK = 0x10 +~~~~~~~~~~~~~~~~~~~~~ + +Rollback the transaction in the specified stream. +See :ref:`stream:rollback() `. + +.. cssclass:: highlight +.. parsed-literal:: + + # + msgpack(:samp:`{{MP_UINT unsigned integer = size(
) + size()}}`) + #
+ msgpack({ + IPROTO_REQUEST_TYPE: IPROTO_ROLLBACK, + IPROTO_SYNC: :samp:`{{MP_UINT unsigned integer}}` + IPROTO_STREAM_ID: :samp:`{{MP_UINT unsigned integer}}` + }) + +See :ref:`Binary protocol -- streams ` to learn more about +stream transactions in the binary protocol. + .. _box_protocol-ping: @@ -747,7 +838,7 @@ Tarantool nodes in :ref:`synchronous replication `. The messages are not supposed to be used by any client applications in their regular connections. -.. _box_protocol-confirm: +.. _box_protocol-raft_confirm: IPROTO_RAFT_CONFIRM = 0x28 ~~~~~~~~~~~~~~~~~~~~~ @@ -776,7 +867,7 @@ The body is a 2-item map: }) -.. _box_protocol-rollback: +.. _box_protocol-raft_rollback: IPROTO_RAFT_ROLLBACK = 0x29 ~~~~~~~~~~~~~~~~~~~~~~ From 851f80430a6497bac327a210504a83689405ab5e Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Mon, 6 Jun 2022 18:22:17 +0700 Subject: [PATCH 5/8] Fix --- doc/dev_guide/internals/box_protocol.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/doc/dev_guide/internals/box_protocol.rst b/doc/dev_guide/internals/box_protocol.rst index 7fdd01bdc7..9e09b5ffe1 100644 --- a/doc/dev_guide/internals/box_protocol.rst +++ b/doc/dev_guide/internals/box_protocol.rst @@ -144,7 +144,7 @@ The IPROTO constants that appear within requests or responses that we will descr IPROTO_VERSION=0x54 IPROTO_FEATURES=0x55 IPROTO_TIMEOUT=0x56 - IPROTO_TXN_ISOLATION = 0x59, + IPROTO_TXN_ISOLATION = 0x59 To denote message descriptions we will say ``msgpack(...)`` and within it we will use modified @@ -725,23 +725,23 @@ The body is optional and can contain two items: #
msgpack({ IPROTO_REQUEST_TYPE: IPROTO_BEGIN, - IPROTO_SYNC: :samp:`{{MP_UINT unsigned integer}}` + IPROTO_SYNC: :samp:`{{MP_UINT unsigned integer}}`, IPROTO_STREAM_ID: :samp:`{{MP_UINT unsigned integer}}` }) # msgpack({ - IPROTO_TIMEOUT: :samp:`{{MP_DOUBLE}}` + IPROTO_TIMEOUT: :samp:`{{MP_DOUBLE}}`, IPROTO_TXN_ISOLATION: :samp:`{{MP_UINT unsigned integer}}` }) IPROTO_TIMEOUT is an optional timeout (in seconds). After it expires, the transaction will be rolled back automatically. --- TODO: add link to transaction isolation docs once they're ready +.. // TODO: add link to transaction isolation docs once they're ready IPROTO_TXN_ISOLATION is the transaction isolation level. It can take the following values: --- TODO: provide links to level descriptions +.. // TODO: provide links to level descriptions - ``TXN_ISOLATION_DEFAULT = 0`` -- use the global default level - ``TXN_ISOLATION_READ_COMMITTED = 1`` -- read committed, but not confirmed changes - ``TXN_ISOLATION_READ_CONFIRMED = 2`` -- read only confirmed changes @@ -763,11 +763,11 @@ See :ref:`stream:commit() `. .. parsed-literal:: # - msgpack(:samp:`{{MP_UINT unsigned integer = size(
) + size()}}`) + msgpack(7) #
msgpack({ IPROTO_REQUEST_TYPE: IPROTO_COMMIT, - IPROTO_SYNC: :samp:`{{MP_UINT unsigned integer}}` + IPROTO_SYNC: :samp:`{{MP_UINT unsigned integer}}`, IPROTO_STREAM_ID: :samp:`{{MP_UINT unsigned integer}}` }) @@ -787,11 +787,11 @@ See :ref:`stream:rollback() `. .. parsed-literal:: # - msgpack(:samp:`{{MP_UINT unsigned integer = size(
) + size()}}`) + msgpack(7) #
msgpack({ IPROTO_REQUEST_TYPE: IPROTO_ROLLBACK, - IPROTO_SYNC: :samp:`{{MP_UINT unsigned integer}}` + IPROTO_SYNC: :samp:`{{MP_UINT unsigned integer}}`, IPROTO_STREAM_ID: :samp:`{{MP_UINT unsigned integer}}` }) From bb2d5f30a1ab896ed021fa5049a3c9e45d12e629 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Mon, 6 Jun 2022 19:24:15 +0700 Subject: [PATCH 6/8] Fix typo --- doc/dev_guide/internals/box_protocol.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/dev_guide/internals/box_protocol.rst b/doc/dev_guide/internals/box_protocol.rst index 9e09b5ffe1..a436552e54 100644 --- a/doc/dev_guide/internals/box_protocol.rst +++ b/doc/dev_guide/internals/box_protocol.rst @@ -745,7 +745,7 @@ the following values: - ``TXN_ISOLATION_DEFAULT = 0`` -- use the global default level - ``TXN_ISOLATION_READ_COMMITTED = 1`` -- read committed, but not confirmed changes - ``TXN_ISOLATION_READ_CONFIRMED = 2`` -- read only confirmed changes -- ``TXN_ISOLATION_BEST_EFFORD = 3`` -- determine isolation level automatically +- ``TXN_ISOLATION_BEST_EFFORT = 3`` -- determine isolation level automatically See :ref:`Binary protocol -- streams ` to learn more about stream transactions in the binary protocol. From aa2c61257a36977e8a515e87373c4140dc5656ae Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Tue, 7 Jun 2022 12:31:04 +0700 Subject: [PATCH 7/8] Isolation levels --- doc/dev_guide/internals/box_protocol.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/dev_guide/internals/box_protocol.rst b/doc/dev_guide/internals/box_protocol.rst index a436552e54..b93a6db8ae 100644 --- a/doc/dev_guide/internals/box_protocol.rst +++ b/doc/dev_guide/internals/box_protocol.rst @@ -742,9 +742,9 @@ IPROTO_TXN_ISOLATION is the transaction isolation level. It can take the following values: .. // TODO: provide links to level descriptions -- ``TXN_ISOLATION_DEFAULT = 0`` -- use the global default level -- ``TXN_ISOLATION_READ_COMMITTED = 1`` -- read committed, but not confirmed changes -- ``TXN_ISOLATION_READ_CONFIRMED = 2`` -- read only confirmed changes +- ``TXN_ISOLATION_DEFAULT = 0`` -- use the global default level (default value) +- ``TXN_ISOLATION_READ_COMMITTED = 1`` -- read changes that are committed but not confirmed yet +- ``TXN_ISOLATION_READ_CONFIRMED = 2`` -- read confirmed changes - ``TXN_ISOLATION_BEST_EFFORT = 3`` -- determine isolation level automatically See :ref:`Binary protocol -- streams ` to learn more about From 68cac34af0a373820c5e10ea70160160464ac000 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Tue, 7 Jun 2022 13:44:57 +0700 Subject: [PATCH 8/8] Update doc/dev_guide/internals/box_protocol.rst Co-authored-by: Dia Patience Daur --- doc/dev_guide/internals/box_protocol.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/dev_guide/internals/box_protocol.rst b/doc/dev_guide/internals/box_protocol.rst index b93a6db8ae..5d0b49e42a 100644 --- a/doc/dev_guide/internals/box_protocol.rst +++ b/doc/dev_guide/internals/box_protocol.rst @@ -1374,9 +1374,9 @@ each call to conn:new_stream() assigns a new number, starting with 1. The client makes stream transactions by sending, in order: -1. IPROTO_BEGIN with an optional transaction timeout in the IPROTO_TIMEOUT field of the request body -2. the transaction data-change and query requests -3. IPROTO_COMMIT or IPROTO_ROLLBACK +1. IPROTO_BEGIN with an optional transaction timeout in the IPROTO_TIMEOUT field of the request body. +2. The transaction data-change and query requests. +3. IPROTO_COMMIT or IPROTO_ROLLBACK. All these requests must contain the same IPROTO_STREAM_ID value.