From d1234f52093a380270489dc8647bebb4ee52a1a9 Mon Sep 17 00:00:00 2001 From: Kseniia Antonova Date: Fri, 4 Oct 2024 11:29:15 +0300 Subject: [PATCH 1/4] Update _schema and box.once description --- doc/reference/reference_lua/box_once.rst | 80 ++++++++++++++----- .../reference_lua/box_space/_schema.rst | 39 ++++----- 2 files changed, 79 insertions(+), 40 deletions(-) diff --git a/doc/reference/reference_lua/box_once.rst b/doc/reference/reference_lua/box_once.rst index 68bf1fea51..ac150091a4 100644 --- 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 `. 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 function + + .. NOTE:: + + The parameter ``key`` will be stored in the :ref:`_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. + + + **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``: - tarantool> box.space._schema:select{} + .. code-block:: console + + 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:: console - 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:: console + + 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:: console + + 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 ` - 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 index 2a254693ab..7c24387e19 100644 --- 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() ` blocks from the instance's + * ``version``: version information for this Tarantool instance. + * ``replicaset_name`` (since :doc:`3.0.0 `): the name of a replica set to which this instance belongs. + * ``replicaset_uuid`` (since :doc:`3.0.0 `): the instance's replica set UUID. In version :doc:`3.0.0 `, + the field was renamed from ``cluster`` to ``replicaset_uuid``. + * ``max_id`` (deprecated since :doc:`2.11.1 `__): the maximal space ID. + Use the :ref:`box.space._space.index[0]:max() ` function instead. + * ``once...``: tuples that correspond to specific + :ref:`box.once() ` blocks from the instance's :ref:`initialization file `. 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] From 0fb06065faad751b657ac41e7904fe7c71a713d8 Mon Sep 17 00:00:00 2001 From: Kseniia Antonova Date: Fri, 11 Oct 2024 10:37:26 +0300 Subject: [PATCH 2/4] Fix link --- doc/reference/reference_lua/box_space/_schema.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/reference/reference_lua/box_space/_schema.rst b/doc/reference/reference_lua/box_space/_schema.rst index 7c24387e19..7fb27b1bbb 100644 --- a/doc/reference/reference_lua/box_space/_schema.rst +++ b/doc/reference/reference_lua/box_space/_schema.rst @@ -15,7 +15,7 @@ box.space._schema * ``replicaset_name`` (since :doc:`3.0.0 `): the name of a replica set to which this instance belongs. * ``replicaset_uuid`` (since :doc:`3.0.0 `): the instance's replica set UUID. In version :doc:`3.0.0 `, the field was renamed from ``cluster`` to ``replicaset_uuid``. - * ``max_id`` (deprecated since :doc:`2.11.1 `__): the maximal space ID. + * ``max_id`` (deprecated since `2.11.1 `__): the maximal space ID. Use the :ref:`box.space._space.index[0]:max() ` function instead. * ``once...``: tuples that correspond to specific :ref:`box.once() ` blocks from the instance's From 2534ce2ce4d4984523ce39f523bc80ab3ee73f1b Mon Sep 17 00:00:00 2001 From: Kseniia Antonova Date: Fri, 11 Oct 2024 12:56:14 +0300 Subject: [PATCH 3/4] Fix codeblock formatting --- doc/reference/reference_lua/box_once.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/reference/reference_lua/box_once.rst b/doc/reference/reference_lua/box_once.rst index ac150091a4..3cb0a17215 100644 --- a/doc/reference/reference_lua/box_once.rst +++ b/doc/reference/reference_lua/box_once.rst @@ -43,7 +43,7 @@ Function box.once First, check the ``_schema`` system space. The ``_schema`` space in the example contains two ``box.once`` objects -- ``oncebye`` and ``oncehello``: - .. code-block:: console + .. code-block:: tarantoolsession app:instance001> box.space._schema:select{} --- @@ -55,7 +55,7 @@ Function box.once Delete the ``oncehello`` object: - .. code-block:: console + .. code-block:: tarantoolsession app:instance001> box.space._schema:delete('oncehello') --- @@ -64,7 +64,7 @@ Function box.once After that, check the ``_schema`` space again: - .. code-block:: console + .. code-block:: tarantoolsession app:instance001> box.space._schema:select{} --- @@ -76,7 +76,7 @@ Function box.once To re-execute the function, call the ``box.once()`` method again: - .. code-block:: console + .. code-block:: tarantoolsession app:instance001> box.once('hello', function() end) --- From 349658a7b88f060359a6ad2b52541d19ca732428 Mon Sep 17 00:00:00 2001 From: Kseniia Antonova <73473519+xuniq@users.noreply.github.com> Date: Fri, 11 Oct 2024 12:59:55 +0300 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Elena Shebunyaeva --- doc/reference/reference_lua/box_once.rst | 2 +- doc/reference/reference_lua/box_space/_schema.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/reference/reference_lua/box_once.rst b/doc/reference/reference_lua/box_once.rst index 3cb0a17215..1a3a239c3b 100644 --- a/doc/reference/reference_lua/box_once.rst +++ b/doc/reference/reference_lua/box_once.rst @@ -25,7 +25,7 @@ Function box.once :param string key: a value that will be checked :param function function: a function - :param ...: arguments that must be passed to function + :param ...: arguments that must be passed to the function .. NOTE:: diff --git a/doc/reference/reference_lua/box_space/_schema.rst b/doc/reference/reference_lua/box_space/_schema.rst index 7fb27b1bbb..172edb1bdc 100644 --- a/doc/reference/reference_lua/box_space/_schema.rst +++ b/doc/reference/reference_lua/box_space/_schema.rst @@ -12,7 +12,7 @@ box.space._schema This space contains the following tuples: * ``version``: version information for this Tarantool instance. - * ``replicaset_name`` (since :doc:`3.0.0 `): the name of a replica set to which this instance belongs. + * ``replicaset_name`` (since :doc:`3.0.0 `): the name of the replica set to which this instance belongs. * ``replicaset_uuid`` (since :doc:`3.0.0 `): the instance's replica set UUID. In version :doc:`3.0.0 `, the field was renamed from ``cluster`` to ``replicaset_uuid``. * ``max_id`` (deprecated since `2.11.1 `__): the maximal space ID.