Skip to content

Commit 73b6f2f

Browse files
xuniqxuniq
authored
Describe box.info.synchro function (#3140)
* Add box.info.synchro interface. * Add owner, busy, and term fields. * Add examples Fixes #2044 Fixes #2741 Fixes #2277 Fixes #2831
1 parent 1284897 commit 73b6f2f

File tree

2 files changed

+147
-0
lines changed

2 files changed

+147
-0
lines changed

‎doc/reference/reference_lua/box_info.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,10 @@ Below is a list of all ``box.info`` functions.
9292
- Show the current state of a replica set node
9393
in regards to leader election
9494

95+
* - :doc:`./box_info/synchro`
96+
- Show the current state of synchronous replication
97+
98+
9599
.. toctree::
96100
:hidden:
97101

@@ -102,3 +106,4 @@ Below is a list of all ``box.info`` functions.
102106
box_info/replication
103107
box_info/listen
104108
box_info/election
109+
box_info/synchro

‎doc/reference/reference_lua/box_info/synchro.rst

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
.. _box_info_synchro:
2+
3+
================================================================================
4+
box.info.synchro
5+
================================================================================
6+
7+
.. module:: box.info
8+
9+
.. data:: synchro
10+
11+
Since version :doc:`2.8.1 </release/2.8.1>`.
12+
Show the current state of synchronous replication.
13+
14+
In :ref:`synchronous replication <repl_sync>`, transaction is considered committed only after achieving
15+
the required quorum number.
16+
While transactions are collecting confirmations from remote nodes, these transactions are waiting in the queue.
17+
18+
The following information is provided:
19+
20+
* ``queue``:
21+
22+
- ``owner`` (since version :doc:`2.10.0 </release/2.10.0>`) -- ID of the replica that owns the synchronous
23+
transaction queue. Once an owner instance appears, all other instances become read-only.
24+
If the ``owner`` field is ``0``, then every instance may be writable,
25+
but they can't create any synchronous transactions.
26+
To claim or reclaim the queue, use :ref:`box.ctl.promote() <box_ctl-promote>` on the instance that you want
27+
to promote.
28+
With elections enabled, an instance runs ``box.ctl.promote()`` command automatically after winning the elections.
29+
30+
- ``term`` (since version :doc:`2.10.0 </release/2.10.0>`) -- current queue term.
31+
It contains the term of the last ``PROMOTE`` request.
32+
Usually, it is equal to :ref:`box.info.election.term <box_info_election>`.
33+
However, the queue term value may be less than the election term.
34+
It can happen when a new round of elections has started, but no instance has been promoted yet.
35+
36+
- ``len`` -- the number of entries that are currently waiting in the queue.
37+
38+
- ``busy`` (since version :doc:`2.10.0 </release/2.10.0>`) -- the boolean value is ``true``
39+
when the instance is processing or writing some system request that modifies the queue
40+
(for example, ``PROMOTE``, ``CONFIRM``, or ``ROLLBACK``).
41+
Until the request is complete, any other incoming synchronous transactions and system requests
42+
will be delayed.
43+
44+
* ``quorum`` -- the resulting value of the
45+
:ref:`replication_synchro_quorum <cfg_replication-replication_synchro_quorum>` configuration option.
46+
Since version :doc:`2.5.3 </release/2.5.3>`, the option can be set as a dynamic formula.
47+
In this case, the value of the ``quorum`` member depends on the current number of replicas.
48+
49+
**Example 1:**
50+
51+
In this example, the ``quorum`` field is equal to ``1``.
52+
That is, synchronous transactions work like asynchronous ones.
53+
`1` means that a successful WAL writing to the master is enough to commit.
54+
55+
.. code-block:: tarantoolsession
56+
57+
tarantool> box.info.synchro
58+
---
59+
- queue:
60+
owner: 1
61+
term: 2
62+
len: 0
63+
busy: false
64+
quorum: 1
65+
...
66+
67+
**Example 2:**
68+
69+
First, set a quorum number and a timeout for synchronous replication using the following command:
70+
71+
.. code-block:: tarantoolsession
72+
73+
tarantool> box.cfg{
74+
> replication_synchro_quorum=2,
75+
> replication_synchro_timeout=1000
76+
> }
77+
78+
Next, check the current state of synchronous replication:
79+
80+
.. code-block:: tarantoolsession
81+
82+
tarantool> box.info.synchro
83+
---
84+
- queue:
85+
owner: 1
86+
term: 2
87+
len: 0
88+
busy: false
89+
quorum: 2
90+
...
91+
92+
Create a space called ``sync`` and enable synchronous replication on this space.
93+
Then, create an index.
94+
95+
.. code-block:: tarantoolsession
96+
97+
tarantool> s = box.schema.space.create("sync", {is_sync=true})
98+
tarantool> _ = s:create_index('pk')
99+
100+
After that, use ``box.ctl.promote()`` function to claim a queue:
101+
102+
.. code-block:: tarantoolsession
103+
104+
tarantool> box.ctl.promote()
105+
106+
Next, perform data manipulations:
107+
108+
.. code-block:: tarantoolsession
109+
110+
tarantool> require('fiber').new(function() box.space.sync:replace{1} end)
111+
---
112+
- status: suspended
113+
name: lua
114+
id: 119
115+
...
116+
tarantool> require('fiber').new(function() box.space.sync:replace{1} end)
117+
---
118+
- status: suspended
119+
name: lua
120+
id: 120
121+
...
122+
tarantool> require('fiber').new(function() box.space.sync:replace{1} end)
123+
---
124+
- status: suspended
125+
name: lua
126+
id: 121
127+
...
128+
129+
If you call the ``box.info.synchro`` command again,
130+
you will see that now there are 3 transactions waiting in the queue:
131+
132+
.. code-block:: tarantoolsession
133+
134+
tarantool> box.info.synchro
135+
---
136+
- queue:
137+
owner: 1
138+
term: 2
139+
len: 3
140+
busy: false
141+
quorum: 2
142+
...

0 commit comments

Comments
 (0)