Update the description of box.space._schema (#4570)

- Added `replicaset_name` description - Renamed `cluster` to `replicaset_uuid` - Added info about `max_id` deprecation - Updated `box.once()` description Fixes #3409 Fixes #3464 --------- Co-authored-by: Elena Shebunyaeva <[email protected]>
tarantool · Oct 11, 2024 · f58bb6f · f58bb6f
1 parent dca6d47
commit f58bb6f
Show file tree

Hide file tree

Showing 2 changed files with 79 additions and 40 deletions.
diff --git a/doc/reference/reference_lua/box_once.rst b/doc/reference/reference_lua/box_once.rst
@@ -1,8 +1,7 @@
 .. _box-once:
 
--------------------------------------------------------------------------------
-                             Function box.once
--------------------------------------------------------------------------------
+Function box.once
+=================
 
 .. function:: box.once(key, function[, ...])
 
@@ -18,40 +17,77 @@
     stopping the database. The solution is to delete the ``once`` object from
     the system space :ref:`_schema <box_space-schema>`.
     Say ``box.space._schema:select{}``, find your ``once`` object there and
-    delete it. For example, re-executing a block with ``key='hello'`` :
+    delete it.
 
     When ``box.once()`` is used for initialization, it may be useful to
     wait until the database is in an appropriate state (read-only or read-write).
     In that case, see the functions in the :doc:`/reference/reference_lua/box_ctl`.
 
-    .. code-block:: tarantoolsession
+    :param string        key: a value that will be checked
+    :param function function: a function
+    :param               ...: arguments that must be passed to the function
+
+    ..  NOTE::
+
+        The parameter ``key`` will be stored in the :ref:`_schema <box_space-schema>`
+        system space after ``box.once()`` is called in order to prevent a double
+        run. These keys are global per replica set. So a simultaneous call of
+        ``box.once()`` with the same key on two instances of the same replica set
+        may succeed on both of them, but it'll lead to a transaction conflict.
 
-        tarantool> box.space._schema:select{}
+
+    **Example**
+
+    The example shows how to re-execute the ``box.once()`` block that contains the ``hello`` key.
+
+    First, check the ``_schema`` system space.
+    The ``_schema`` space in the example contains two ``box.once`` objects -- ``oncebye`` and ``oncehello``:
+
+    ..  code-block:: tarantoolsession
+
+        app:instance001> box.space._schema:select{}
         ---
-        - - ['cluster', 'b4e15788-d962-4442-892e-d6c1dd5d13f2']
-          - ['max_id', 512]
-          - ['oncebye']
+        - - ['oncebye']
           - ['oncehello']
-          - ['version', 1, 7, 2]
-        ...
+          - ['replicaset_name', 'replicaset001']
+          - ['replicaset_uuid', '72d2d9bf-5d9f-48c4-ba80-9d657e128fee']
+          - ['version', 3, 1, 0]
+
+    Delete the ``oncehello`` object:
+
+    ..  code-block:: tarantoolsession
 
-        tarantool> box.space._schema:delete('oncehello')
+        app:instance001> box.space._schema:delete('oncehello')
         ---
         - ['oncehello']
         ...
 
-        tarantool> box.once('hello', function() end)
+    After that, check the ``_schema`` space again:
+
+    ..  code-block:: tarantoolsession
+
+        app:instance001> box.space._schema:select{}
         ---
+        - - ['oncebye']
+          - ['replicaset_name', 'replicaset001']
+          - ['replicaset_uuid', '72d2d9bf-5d9f-48c4-ba80-9d657e128fee']
+          - ['version', 3, 1, 0]
         ...
 
-    :param string        key: a value that will be checked
-    :param function function: a function
-    :param               ...: arguments that must be passed to function
+    To re-execute the function, call the ``box.once()`` method again:
 
-    .. NOTE::
+    ..  code-block:: tarantoolsession
+
+        app:instance001> box.once('hello', function() end)
+        ---
+        ...
+
+        app:instance001> box.space._schema:select{}
+        ---
+        - - ['oncebye']
+          - ['oncehello']
+          - ['replicaset_name', 'replicaset001']
+          - ['replicaset_uuid', '72d2d9bf-5d9f-48c4-ba80-9d657e128fee']
+          - ['version', 3, 1, 0]
+        ...
 
-        The parameter ``key`` will be stored in the :ref:`_schema <box_space-schema>`
-        system space after ``box.once()`` is called in order to prevent a double
-        run. These keys are global per replica set. So a simultaneous call of
-        ``box.once()`` with the same key on two instances of the same replica set
-        may succeed on both of them, but it'll lead to a transaction conflict.
diff --git a/doc/reference/reference_lua/box_space/_schema.rst b/doc/reference/reference_lua/box_space/_schema.rst
@@ -1,8 +1,7 @@
 .. _box_space-schema:
 
-===============================================================================
 box.space._schema
-===============================================================================
+=================
 
 .. module:: box.space
 
@@ -12,28 +11,32 @@ box.space._schema
 
     This space contains the following tuples:
 
-    * ``version`` tuple with version information for this Tarantool instance,
-    * ``cluster`` tuple with the instance's replica set ID,
-    * ``max_id`` tuple with the maximal space ID,
-    * ``once...`` tuples that correspond to specific
-      :doc:`box.once() </reference/reference_lua/box_once>` blocks from the instance's
+    * ``version``: version information for this Tarantool instance.
+    * ``replicaset_name`` (since :doc:`3.0.0 <release/3.0.0>`): the name of the replica set to which this instance belongs.
+    * ``replicaset_uuid`` (since :doc:`3.0.0 <release/3.0.0>`): the instance's replica set UUID. In version :doc:`3.0.0 <release/3.0.0>`,
+      the field was renamed from ``cluster`` to ``replicaset_uuid``.
+    * ``max_id`` (deprecated since `2.11.1 <https://github.com/tarantool/tarantool/releases/tag/2.11.1>`__): the maximal space ID.
+      Use the :ref:`box.space._space.index[0]:max() <box_index-max>` function instead.
+    * ``once...``: tuples that correspond to specific
+      :ref:`box.once() <box-once>` blocks from the instance's
       :ref:`initialization file <index-init_label>`.
       The first field in these tuples contains the ``key`` value from the
-      corresponding ``box.once()`` block prefixed with 'once' (e.g. `oncehello`),
+      corresponding ``box.once()`` block prefixed with 'once' (for example, ``oncehello``),
       so you can easily find a tuple that corresponds to a specific
       ``box.once()`` block.
 
     **Example:**
 
-    Here is what ``_schema`` contains in a typical installation (notice the
-    tuples for two ``box.once()`` blocks, ``'oncebye'`` and ``'oncehello'``):
+    In the example, the ``_schema`` space contains two ``box.once`` objects -- ``oncebye`` and ``oncehello``.
 
-    .. code-block:: tarantoolsession
+    ..  code-block:: tarantoolsession
+
+        app:instance001> box.space._schema:select{}
+        ---
+        - - ['oncebye']
+          - ['oncehello']
+          - ['replicaset_name', 'replicaset001']
+          - ['replicaset_uuid', '72d2d9bf-5d9f-48c4-ba80-9d657e128fee']
+          - ['version', 3, 1, 0]
+        ...
 
-       tarantool> box.space._schema:select{}
-       ---
-       - - ['cluster', 'b4e15788-d962-4442-892e-d6c1dd5d13f2']
-         - ['max_id', 512]
-         - ['oncebye']
-         - ['oncehello']
-         - ['version', 1, 7, 2]