Update after the review

Author: xuniq

doc/reference/reference_lua/box.rst

@@ -38,6 +38,7 @@ with ``box``, with no arguments. The ``box`` module contains:
 
     box_txn_management
     box_sql
+    box_events
     box_once
     box_snapshot
 

doc/reference/reference_lua/box_watchers.rst renamed to doc/reference/reference_lua/box_events.rst

@@ -1,31 +1,34 @@
 .. _box-watchers:
 
 --------------------------------------------------------------------------------
-Functions for watchers
+Event watchers
 --------------------------------------------------------------------------------
 
 The ``box`` module contains some functions related to event subscriptions, also known as watchers.
 The subscriptions are used to inform a client about server-side events.
-To see the list of the built-in events in Tarantool,
-check the :doc:`pub/sub </reference/reference_lua/pub-sub>` section.
+To read more about the built-in events in Tarantool,
+check the :doc:`pub/sub </reference/reference_lua/box_events/pub-sub>` section.
 
 ..  glossary::
 
     Watcher
         A watcher is a :doc:`callback </book/box/triggers>` that is invoked when a state change occurs.
         To register a local watcher, use the ``box.watch()`` function.
         To create a remote watcher, user the ``conn:watch()`` function.
+        Note that it is possible to register more than one watcher for the same key.
 
     State
         A state is an internally stored key-value pair.
         The key is a string.
         The value is an arbitrary type that can be encoded as MsgPack.
         To update a state, use the ``box.broadcast()`` function.
 
-First, a watcher callback is invoked unconditionally after the watcher registration.
-Note that it is possible to register more than one watcher for the same key.
+First, a watcher callback is invoked after the watcher registration.
+In this case, the callback is triggered whether or not the key has already been broadcast.
 After that, :doc:`box.broadcast() </reference/reference_lua/box_watchers/broadcast>`  called on the remote host
 triggers all subsequent invocations.
+If a watcher is subscribed for a key that has not been broadcast yet, the callback is triggered only once,
+after the registration of the watcher.
 
 A watcher callback is passed the name of the key for which it was registered and the current key data.
 A watcher callback is always invoked in a new fiber. It means that is is okay to yield in it.
@@ -41,7 +44,7 @@ value as soon as it returns.
     In this case, the watcher remains registered.
     It is okay to discard the result of ``watch`` function if the watcher will never be unregistered.
 
-Below is a list of all functions related to watchers.
+Below is a list of all functions and members related to watchers or events.
 
 ..  container:: table
 
@@ -64,8 +67,12 @@ Below is a list of all functions related to watchers.
         *  - :doc:`./box_watchers/broadcast`
            - Update a state.
 
+        *  - :ref:`˜Built-in events <pubsub>`
+           - Pub/sub system and predefined events
+
 .. toctree::
     :hidden:
 
-    box_watchers/watch
-    box_watchers/broadcast
+    box_events/watch
+    box_events/broadcast
+    box_events/pub-sub

doc/reference/reference_lua/box_watchers/broadcast.rst renamed to doc/reference/reference_lua/box_events/broadcast.rst

@@ -30,15 +30,12 @@ In Tarantool, :term:`pub/sub <publisher/subscriber>` is a :term:`notification` s
 
 The pub/sub pattern is associated with subscriptions.
 Each subscription is defined by the certain key.
-The main feature of the subscriptions is a one-time action.
-It means that if the server generates too many events and a client is too slow,
-the server will not allocate additional memory.
 
 Built-in events for pub/sub
 ---------------------------
 
-Built-in events have a special naming schema -- theirs names always start with the ``box.`` prefix.
-This prefix is reserved for the built-in events. It means that you cannot create new events with it.
+Predefined events have a special naming schema -- theirs names always start with the reserved ``box.`` prefix.
+It means that you cannot create new events with it.
 
 The system processes the following events:
 
@@ -47,23 +44,34 @@ The system processes the following events:
 *   ``box.election``
 *   ``box.schema``
 
-In response to each event, the server sends back certain IPROTO fields.
+In response to each event, the server sends back certain ``IPROTO`` fields.
+
+The events are available from the beginning as non-:ref:`MP_NIL <box_protocol-notation>`.
+If the events are broadcast before :doc:`box.cfg{} </reference/reference_lua/box_cfg>`,
+then the events values are empty:
+
+..  code-block:: lua
+
+    box.id = {}
+    box.schema = {}
+    box.status = {}
+    box.election = {}
 
 box.id
 ~~~~~~
 
-Contains identification of the instance.
-Changes are particularly rare.
-Some values never change or change only once.
+Contains :ref:`identification <box_info_info>` of the instance.
+Value changes are rare.
 
-The numeric instance ID is known only after registration.
-For anonymous replicas, the value is ``0`` until they are officially registered.
+*   ``id``: the numeric instance ID is unknown before the registration.
+    For anonymous replicas, the value is ``0`` until they are officially registered.
 
-The UUID of the instance never changes after the first :doc:`box.cfg </reference/reference_lua/box_cfg>`.
-The value is unknown before the ``box.cfg`` call.
+*   ``instance_uuid``: the UUID of the instance never changes after the first
+    :doc:`box.cfg </reference/reference_lua/box_cfg>`.
+    The value is unknown before the ``box.cfg`` call.
 
-The replicaset UUID is unknown until the instance joins a replicaset or boots a new one.
-The events are supposed to start working before that -- right with the start of the listen.
+*   ``replicaset_uuid``: the value is unknown until the instance joins a replicaset or boots a new one.
+    The events start working before that -- right with the start of the listen.
 
 ..  code-block:: lua
 
@@ -78,8 +86,10 @@ box.status
 ~~~~~~~~~~
 
 Contains generic blob about the instance status.
-There are the most frequently used and not frequently changed
-:doc:`config options </reference/reference_lua/box_cfg>` and :doc:`box.info </reference/reference_lua/box_info>` fields.
+
+*   ``is_ro``: :ref:`indicates the read-only mode <box_introspection-box_info>` or the ``orphan`` status.
+*   ``is_ro_cfg``: indicates the :ref:`read_only <cfg_basic-read_only>` mode for the instance.
+*   ``status``: shows the status of an instance.
 
 ..  code-block:: lua
 
@@ -92,8 +102,13 @@ There are the most frequently used and not frequently changed
 box.election
 ~~~~~~~~~~~~
 
-Contains all the required parts of :doc:`box.info.election </reference/reference_lua/box_info/election>`
-that are necessary to find out who is the most recent writable leader.
+Contains fields of the :doc:`box.info.election </reference/reference_lua/box_info/election>`
+that are necessary to find out the most recent writable leader.
+
+*   ``term``: shows the current election term.
+*   ``role``: indicates the election state of the node -- ``leader``, ``follower``, or ``candidate``.
+*   ``is_ro``: :ref:`indicates the read-only mode <box_introspection-box_info>` or the ``orphan`` status.
+*   ``leader``: shows the leader node ID in the current term.
 
 ..  code-block:: lua
 
@@ -108,31 +123,15 @@ box.schema
 ~~~~~~~~~~
 
 Contains schema-related data.
-Currently, it contains only the version.
+
+*   ``version``: shows the schema version.
 
 ..  code-block:: lua
 
     {
     MP_STR “version”: MP_UINT schema_version,
     }
 
-The events are available from the beginning as non-:ref:`MP_NIL <box_protocol-notation>`.
-It is necessary for supported local subscriptions.
-Otherwise, there is no way to detect whether an event is supported at all by this Tarantool version.
-If the events are broadcast before :doc:`box.cfg{} </reference/reference_lua/box_cfg>`,
-then the following values are available:
-
-..  code-block:: lua
-
-    box.id = {}
-    box.schema = {}
-    box.status = {}
-    box.election = {}
-
-This way, users can distinguish if an event being not supported
-at all or if ``box.cfg{}`` has not been called yet.
-Otherwise, they would need to parse the ``_TARANTOOL`` version string locally and the ``peer_version`` in ``net.box``.
-
 Usage example
 -------------
 

doc/reference/reference_lua/pub-sub.rst renamed to doc/reference/reference_lua/box_events/pub-sub.rst

@@ -55,7 +55,6 @@ This reference covers Tarantool's built-in Lua modules.
     uri
     xlog
     yaml
-    pub-sub
     other
     errcodes
     debug_facilities