From 0fbf6524da7607aef87cb2963494ac7aff145f10 Mon Sep 17 00:00:00 2001 From: Kseniia Antonova Date: Mon, 12 Sep 2022 13:12:50 +0300 Subject: [PATCH 1/5] Add draft file --- doc/reference/reference_lua/box_info.rst | 5 +++ .../reference_lua/box_info/synchro.rst | 38 +++++++++++++++++++ 2 files changed, 43 insertions(+) create mode 100644 doc/reference/reference_lua/box_info/synchro.rst diff --git a/doc/reference/reference_lua/box_info.rst b/doc/reference/reference_lua/box_info.rst index 569862b54f..6f66507853 100644 --- a/doc/reference/reference_lua/box_info.rst +++ b/doc/reference/reference_lua/box_info.rst @@ -92,6 +92,10 @@ Below is a list of all ``box.info`` functions. - Show the current state of a replica set node in regards to leader election + * - :doc:`./box_info/synchro` + - Show the current state of synchronous replication + + .. toctree:: :hidden: @@ -102,3 +106,4 @@ Below is a list of all ``box.info`` functions. box_info/replication box_info/listen box_info/election + box_info/synchro diff --git a/doc/reference/reference_lua/box_info/synchro.rst b/doc/reference/reference_lua/box_info/synchro.rst new file mode 100644 index 0000000000..9b69679371 --- /dev/null +++ b/doc/reference/reference_lua/box_info/synchro.rst @@ -0,0 +1,38 @@ +.. _box_info_synchro: + +================================================================================ +box.info.synchro +================================================================================ + +.. module:: box.info + +.. data:: synchro + + Since version :doc:`2.8.1 `. + Show the current state of synchronous replication. + + In :ref:`synchronous replication `, a transaction is considered committed only after achieving + the required quorum number. + While the transactions are collecting confirmations from remote nodes, these transactions are waiting in the queue. + + The following information is provided: + + * ``queue``: + + - ``len`` -- current number of entries that are waiting in the queue. + + * ``quorum`` -- evaluated value of the + :ref:`replication_synchro_quorum ` configuration option. + Since version :doc:`2.5.3 `, the option can be set as a dynamic formula. + In this case, the value in the ``quorum`` member depends on the current number of replicas. + + **Example:** + + .. code-block:: tarantoolsession + + tarantool> box.info.synchro + --- + - queue: + len: 0 + quorum: 1 + ... \ No newline at end of file From 135702acf72b01747b89ea8da9924b12b5e5cc88 Mon Sep 17 00:00:00 2001 From: Kseniia Antonova Date: Thu, 15 Sep 2022 15:52:47 +0300 Subject: [PATCH 2/5] Add owner, busy, and term fields. --- .../reference_lua/box_info/synchro.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/doc/reference/reference_lua/box_info/synchro.rst b/doc/reference/reference_lua/box_info/synchro.rst index 9b69679371..8b0639983b 100644 --- a/doc/reference/reference_lua/box_info/synchro.rst +++ b/doc/reference/reference_lua/box_info/synchro.rst @@ -19,8 +19,27 @@ box.info.synchro * ``queue``: + - ``owner`` -- ID of the replica that owns the synchronous transaction queue. + Once the owner instance appears, all other instances become read-only. + If the ``owner`` field is ``0``, then every instance is writeable, + but it can't create any synchronous transactions. + To claim or re-claim the queue, use :ref:`box.ctl.promote() ` on the instance that you want + to promote. + Since version :doc:`2.10.0 `. + + - ``term`` -- current queue term. + It contains the term of the last ``PROMOTE``. + Usually it is equal to :ref:`box.info.election.term `. + However, the queue term value may be less than the corresponding one in election term. + It can happen when a new round of elections started, but no one has promoted yet. + Since version :doc:`2.10.0 `. + - ``len`` -- current number of entries that are waiting in the queue. + - ``busy`` -- the boolean value is set to ``true`` if there is a synchronous transaction in progress. + Until the active transaction is complete, any other incoming synchronous transactions will be delayed. + Since version :doc:`2.10.0 `. + * ``quorum`` -- evaluated value of the :ref:`replication_synchro_quorum ` configuration option. Since version :doc:`2.5.3 `, the option can be set as a dynamic formula. From 3af21e29b77080f694f0c833a66259f302f69e5f Mon Sep 17 00:00:00 2001 From: Kseniia Antonova Date: Fri, 16 Sep 2022 11:15:14 +0300 Subject: [PATCH 3/5] Add example --- .../reference_lua/box_info/synchro.rst | 95 ++++++++++++++++++- 1 file changed, 90 insertions(+), 5 deletions(-) diff --git a/doc/reference/reference_lua/box_info/synchro.rst b/doc/reference/reference_lua/box_info/synchro.rst index 8b0639983b..97a2192e1d 100644 --- a/doc/reference/reference_lua/box_info/synchro.rst +++ b/doc/reference/reference_lua/box_info/synchro.rst @@ -20,17 +20,18 @@ box.info.synchro * ``queue``: - ``owner`` -- ID of the replica that owns the synchronous transaction queue. - Once the owner instance appears, all other instances become read-only. + Once an owner instance appears, all other instances become read-only. If the ``owner`` field is ``0``, then every instance is writeable, - but it can't create any synchronous transactions. - To claim or re-claim the queue, use :ref:`box.ctl.promote() ` on the instance that you want + but they can't create any synchronous transactions. + To claim or reclaim the queue, use :ref:`box.ctl.promote() ` on the instance that you want to promote. + With elections enabled, the instance runs ``box.ctl.promote()`` automatically after winning the elections. Since version :doc:`2.10.0 `. - ``term`` -- current queue term. It contains the term of the last ``PROMOTE``. Usually it is equal to :ref:`box.info.election.term `. - However, the queue term value may be less than the corresponding one in election term. + However, the queue term value may be less than the corresponding one in the election term. It can happen when a new round of elections started, but no one has promoted yet. Since version :doc:`2.10.0 `. @@ -45,13 +46,97 @@ box.info.synchro Since version :doc:`2.5.3 `, the option can be set as a dynamic formula. In this case, the value in the ``quorum`` member depends on the current number of replicas. - **Example:** + **Example 1:** + + In this example, the ``quorum`` field is equal to ``1``. + This means that the synchronous transactions work like asynchronous. + `1` means that successful WAL write to the master is enough to commit. .. code-block:: tarantoolsession tarantool> box.info.synchro --- - queue: + owner: 1 + term: 2 len: 0 + busy: false quorum: 1 + ... + + **Example 2:** + + First, set a quorum number and a timeout for synchronous replication using the following command: + + .. code-block:: tarantoolsession + + tarantool> box.cfg{ + > replication_synchro_quorum=2, + > replication_synchro_timeout=1000 + > } + + Next, check the current state of synchronous replication: + + .. code-block:: tarantoolsession + + tarantool> box.info.synchro + --- + - queue: + owner: 1 + term: 2 + len: 0 + busy: false + quorum: 2 + ... + + Create a space called ``sync`` and enable synchronous replication on this space. + Then, create an index. + + .. code-block:: tarantoolsession + + tarantool> s = box.schema.space.create("sync", {is_sync=true}) + tarantool> _ = s:create_index('pk') + + After that, use ``box.ctl.promote`` function to claim the queue: + + .. code-block:: tarantoolsession + + tarantool> box.ctl.promote() + + Next, use the ``replace`` command: + + .. code-block:: tarantoolsession + + tarantool> require('fiber').new(function() box.space.sync:replace{1} end) + --- + - status: suspended + name: lua + id: 119 + ... + tarantool> require('fiber').new(function() box.space.sync:replace{1} end) + --- + - status: suspended + name: lua + id: 120 + ... + tarantool> require('fiber').new(function() box.space.sync:replace{1} end) + --- + - status: suspended + name: lua + id: 121 + ... + + If you use the ``box.info.synchro`` command again, + you will see that now there are 3 transactions waiting in the queue: + + .. code-block:: tarantoolsession + + tarantool> box.info.synchro + --- + - queue: + owner: 1 + term: 2 + len: 3 + busy: false + quorum: 2 ... \ No newline at end of file From 0f8a4dfc3fd9715b11bab2af41a2c6a32801073c Mon Sep 17 00:00:00 2001 From: Kseniia Antonova Date: Tue, 20 Sep 2022 12:11:52 +0300 Subject: [PATCH 4/5] Update text after review --- .../reference_lua/box_info/synchro.rst | 38 +++++++++---------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/doc/reference/reference_lua/box_info/synchro.rst b/doc/reference/reference_lua/box_info/synchro.rst index 97a2192e1d..787f2ad397 100644 --- a/doc/reference/reference_lua/box_info/synchro.rst +++ b/doc/reference/reference_lua/box_info/synchro.rst @@ -11,46 +11,46 @@ box.info.synchro Since version :doc:`2.8.1 `. Show the current state of synchronous replication. - In :ref:`synchronous replication `, a transaction is considered committed only after achieving + In :ref:`synchronous replication `, transaction is considered committed only after achieving the required quorum number. - While the transactions are collecting confirmations from remote nodes, these transactions are waiting in the queue. + While transactions are collecting confirmations from remote nodes, these transactions are waiting in the queue. The following information is provided: * ``queue``: - - ``owner`` -- ID of the replica that owns the synchronous transaction queue. - Once an owner instance appears, all other instances become read-only. - If the ``owner`` field is ``0``, then every instance is writeable, + - ``owner`` (since version :doc:`2.10.0 `) -- ID of the replica that owns the synchronous + transaction queue. Once an owner instance appears, all other instances become read-only. + If the ``owner`` field is ``0``, then every instance may be writable, but they can't create any synchronous transactions. To claim or reclaim the queue, use :ref:`box.ctl.promote() ` on the instance that you want to promote. - With elections enabled, the instance runs ``box.ctl.promote()`` automatically after winning the elections. - Since version :doc:`2.10.0 `. + With elections enabled, an instance runs ``box.ctl.promote()`` command automatically after winning the elections. - - ``term`` -- current queue term. - It contains the term of the last ``PROMOTE``. - Usually it is equal to :ref:`box.info.election.term `. + - ``term`` (since version :doc:`2.10.0 `) -- current queue term. + It contains the term of the last ``PROMOTE`` request. + Usually, it is equal to :ref:`box.info.election.term `. However, the queue term value may be less than the corresponding one in the election term. - It can happen when a new round of elections started, but no one has promoted yet. - Since version :doc:`2.10.0 `. + It can happen when a new round of elections started, but no instance has been promoted yet. - ``len`` -- current number of entries that are waiting in the queue. - - ``busy`` -- the boolean value is set to ``true`` if there is a synchronous transaction in progress. - Until the active transaction is complete, any other incoming synchronous transactions will be delayed. - Since version :doc:`2.10.0 `. + - ``busy`` (since version :doc:`2.10.0 `) -- the boolean value is ``true`` + when the instance is processing or writing some system request that modifies the queue + (for example, ``PROMOTE``, ``CONFIRM``, or ``ROLLBACK``). + Until the request is complete, any other incoming synchronous transactions and system requests + will be delayed. * ``quorum`` -- evaluated value of the :ref:`replication_synchro_quorum ` configuration option. Since version :doc:`2.5.3 `, the option can be set as a dynamic formula. - In this case, the value in the ``quorum`` member depends on the current number of replicas. + In this case, the value of the ``quorum`` member depends on the current number of replicas. **Example 1:** In this example, the ``quorum`` field is equal to ``1``. - This means that the synchronous transactions work like asynchronous. - `1` means that successful WAL write to the master is enough to commit. + That is, synchronous transactions work like asynchronous ones. + `1` means that a successful WAL writing to the master is enough to commit. .. code-block:: tarantoolsession @@ -97,7 +97,7 @@ box.info.synchro tarantool> s = box.schema.space.create("sync", {is_sync=true}) tarantool> _ = s:create_index('pk') - After that, use ``box.ctl.promote`` function to claim the queue: + After that, use ``box.ctl.promote()`` function to claim a queue: .. code-block:: tarantoolsession From 0164f6f2e4357796dfdeab701219981a4f056140 Mon Sep 17 00:00:00 2001 From: Kseniia Antonova Date: Thu, 22 Sep 2022 14:39:22 +0300 Subject: [PATCH 5/5] Update text after review --- doc/reference/reference_lua/box_info/synchro.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/reference/reference_lua/box_info/synchro.rst b/doc/reference/reference_lua/box_info/synchro.rst index 787f2ad397..e9b4d54ede 100644 --- a/doc/reference/reference_lua/box_info/synchro.rst +++ b/doc/reference/reference_lua/box_info/synchro.rst @@ -30,10 +30,10 @@ box.info.synchro - ``term`` (since version :doc:`2.10.0 `) -- current queue term. It contains the term of the last ``PROMOTE`` request. Usually, it is equal to :ref:`box.info.election.term `. - However, the queue term value may be less than the corresponding one in the election term. - It can happen when a new round of elections started, but no instance has been promoted yet. + However, the queue term value may be less than the election term. + It can happen when a new round of elections has started, but no instance has been promoted yet. - - ``len`` -- current number of entries that are waiting in the queue. + - ``len`` -- the number of entries that are currently waiting in the queue. - ``busy`` (since version :doc:`2.10.0 `) -- the boolean value is ``true`` when the instance is processing or writing some system request that modifies the queue @@ -41,7 +41,7 @@ box.info.synchro Until the request is complete, any other incoming synchronous transactions and system requests will be delayed. - * ``quorum`` -- evaluated value of the + * ``quorum`` -- the resulting value of the :ref:`replication_synchro_quorum ` configuration option. Since version :doc:`2.5.3 `, the option can be set as a dynamic formula. In this case, the value of the ``quorum`` member depends on the current number of replicas. @@ -103,7 +103,7 @@ box.info.synchro tarantool> box.ctl.promote() - Next, use the ``replace`` command: + Next, perform data manipulations: .. code-block:: tarantoolsession @@ -126,7 +126,7 @@ box.info.synchro id: 121 ... - If you use the ``box.info.synchro`` command again, + If you call the ``box.info.synchro`` command again, you will see that now there are 3 transactions waiting in the queue: .. code-block:: tarantoolsession