Describe box.ctl.demote() function (#3162)

Author: xuniq

doc/reference/reference_lua/box_ctl.rst

@@ -53,6 +53,9 @@ Below is a list of all ``box.ctl`` functions.
         *  - :doc:`./box_ctl/promote`
            - Wait, then choose replication leader
 
+        *  - :doc:`./box_ctl/demote`
+           - Revoke the leader role from the instance
+
 ..  toctree::
     :hidden:
 
@@ -63,3 +66,4 @@ Below is a list of all ``box.ctl`` functions.
     box_ctl/set_on_shutdown_timeout
     box_ctl/is_recovery_finished
     box_ctl/promote
+    box_ctl/demote

doc/reference/reference_lua/box_ctl/demote.rst

@@ -0,0 +1,26 @@
+.. _box_ctl-demote:
+
+box.ctl.demote()
+=================
+
+..  function:: demote()
+
+    Since version :doc:`2.10.0 </release/2.10.0>`.
+
+    Revoke the leader role from the instance.
+
+    On :ref:`synchronous transaction queue owner <box_info_synchro>`, the function works in the following way:
+
+    *   If :ref:`box.cfg.election_mode <cfg_replication-election_mode>` is ``off``,
+        the function writes a ``DEMOTE`` request to WAL.
+        The ``DEMOTE`` request clears the ownership of the synchronous transaction queue,
+        while the ``PROMOTE`` request assigns it to a new instance.
+
+    *   If :ref:`box.cfg.election_mode <cfg_replication-election_mode>` is enabled in any mode, then the function
+        makes the instance start a new term and give up the leader role.
+
+    On instances that are not queue owners, the function does nothing and returns immediately.
+
+    Parameters: none
+
+    :return: nil

doc/reference/reference_lua/box_ctl/is_recovery_finished.rst

@@ -8,13 +8,13 @@ box.ctl.is_recovery_finished()
 
 .. function:: is_recovery_finished()
 
+     Since version :doc:`2.5.3 </release/2.5.3>`.
+
      Check whether the :ref:`recovery process <internals-recovery_process>` has finished.
      Until it has finished, space changes such as ``insert`` or ``update`` are not possible.
 
      :return: ``true`` if recovery has finished, otherwise ``false``
      :rtype: boolean
-     
-     Added in release :doc:`2.5.3 </release/2.5.3>`.
 
 
 

doc/reference/reference_lua/box_ctl/promote.rst

@@ -5,6 +5,9 @@ box.ctl.promote()
 
 .. function:: promote()
 
+    Since version :doc:`2.6.2 </release/2.6.2>`.
+    Renamed in release :doc:`2.6.3 </release/2.6.3>`.
+
     Wait, then choose new replication leader.
 
     For :ref:`synchronous transactions <how-to-repl_sync>` it is
@@ -20,5 +23,3 @@ box.ctl.promote()
     Parameters: none
 
     :return: nil or function pointer
-
-    Added in release :doc:`2.6.2 </release/2.6.2>`. Renamed in release :doc:`2.6.3 </release/2.6.3>`.

doc/reference/reference_lua/box_info/synchro.rst

@@ -9,6 +9,7 @@ box.info.synchro
 ..  data:: synchro
 
     Since version :doc:`2.8.1 </release/2.8.1>`.
+
     Show the current state of synchronous replication.
 
     In :ref:`synchronous replication <repl_sync>`, transaction is considered committed only after achieving
@@ -26,6 +27,7 @@ box.info.synchro
             To claim or reclaim the queue, use :ref:`box.ctl.promote() <box_ctl-promote>` on the instance that you want
             to promote.
             With elections enabled, an instance runs ``box.ctl.promote()`` command automatically after winning the elections.
+            To clear the ownership, call :ref:`box.ctl.demote() <box_ctl-demote>` on the synchronous queue owner.
 
         -   ``term`` (since version :doc:`2.10.0 </release/2.10.0>`) -- current queue term.
             It contains the term of the last ``PROMOTE`` request.