diff --git a/doc/dev_guide/internals/box_protocol.rst b/doc/dev_guide/internals/box_protocol.rst index 409c05bd6d..5d0b49e42a 100644 --- a/doc/dev_guide/internals/box_protocol.rst +++ b/doc/dev_guide/internals/box_protocol.rst @@ -143,6 +143,8 @@ 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 + IPROTO_TXN_ISOLATION = 0x59 To denote message descriptions we will say ``msgpack(...)`` and within it we will use modified @@ -706,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 (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 +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(7) + #
+ 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(7) + #
+ 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: @@ -746,9 +838,9 @@ 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_CONFIRM = 0x28 +IPROTO_RAFT_CONFIRM = 0x28 ~~~~~~~~~~~~~~~~~~~~~ This message confirms that the transactions originated from the instance @@ -775,9 +867,9 @@ The body is a 2-item map: }) -.. _box_protocol-rollback: +.. _box_protocol-raft_rollback: -IPROTO_ROLLBACK = 0x29 +IPROTO_RAFT_ROLLBACK = 0x29 ~~~~~~~~~~~~~~~~~~~~~~ This message says that the transactions originated from the instance @@ -1281,16 +1373,18 @@ 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. + +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() `;