[3pt] Describe box.ctl.clear_synchro_queue() function

[veod32]

Describe box.ctl.clear_synchro_queue function

Product: Tarantool
Since: 2.7.1, 2.6.2
Audience/target:
Root document: https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_ctl/
SME: @sergepetrenko
Peer reviewer: @

Details

• box.ctl.clear_synchro_queue() was implemented earlier but it's not described in box.ctl reference. In 2.7.1 and 2.6.2, the function behavior was changed, and it makes sense to add the function description according to this new behavior. Also, we need to check if some extra description related to this function should be added in the articles on syncronious replication and automated leader election.
• Related development issue: Raft: box.ctl.clear_synchro_queue should commit everything. At least when used by Raft tarantool#5435

Definition of done

• Add description of box.ctl.clear_synchro_queue() as a child page of box.ctl reference
• Add a link to the function description in the table on the box.ctl reference page
• If necessary, describe use cases with the function usage in articles on on syncronious replication and automated leader election.

[NickVolynkin]

@pgulutzan would you like to take a task about synchronous replication?

[pgulutzan]

@veod32, @NickVolynkin, @sergepetrenko:
I don't quite agree. If you look at ctl.c you will see
"
static const struct luaL_Reg lbox_ctl_lib[] = {
...
{"promote", lbox_ctl_promote},
/* An old alias. */
{"clear_synchro_queue", lbox_ctl_promote},
};
"
That is, clear_synchro_queue() still works, but all it does
is call the same thing as promote(), and promote() is the
preferred name -- in fact our release note says
clear_synchro_queue() is deprecated.
Therefore I think the change should be:

Make a new file named promote.rst in directory
reference/reference_lua/box_ctl, containing:

box.ctl.promote()

Implementation version = 2.6.2 (with link to release/2.6.2)
For synchronous transactions (with :doc: reference) it is
possible that a new leader will be chosen but the transactions
of the old leader have not been completed. Therefore to
finalize the transaction, the function box.ctl.promote()
should be called. The old name for this function is
box.ctl.clear_synchro_queue().

The election state (:ref: to box_info/election.rst) should
change to leader.

Parameters: none

Returns: nil, or error may be thrown

Make a new item in the table in
https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_ctl/
box.ctl.promote() | finalize synchronous transaction

I will not change
https://www.tarantool.io/en/doc/latest/book/replication/repl_sync/
paragraph "Leader election" because this is not "automated leader election".

Make a change in
https://www.tarantool.io/en/doc/latest/book/replication/repl_leader_elect/
replacing "box.ctl.clear_synchro_queue() function" with
"box.ctl.promote() function" and a :ref: to the function in the new box_ctl page.

This usually (perhaps always?) should be done with a new election_mode value
https://www.tarantool.io/en/doc/latest/reference/configuration/#confval-election_mode
but I will not change that because there is a separate issue
issue#2088 describe election_mode='manual'.
By the way, in the description there,
"that it becomes a leaders" should be "it to become a leader".

There are additionally some things that I have noticed in
https://www.tarantool.io/en/doc/latest/book/replication/repl_sync/
"it does not mean" could be "that does not mean"
"responds success" could be "responds successfully"
"are not responded to a client" could be "the client does not get a response"
"there exist global" could be "there are global"
"accounts all replicas, including anonymous" could be "counts all replicas including anonymous ones"
"makes replace()" could be "does a replace()"
and so on -- I'm not saying the English is bad, just that it could be different.
I won't change this file unless Nick Volynkin says it's part of this issue.

[pgulutzan]

I made a pull request Issue#2120 and assigned to @NickVolynkin.
I expanded the above comments about repl_sync and put them in Iissue#2121.