diff --git a/doc/reference/reference_lua/box_once.rst b/doc/reference/reference_lua/box_once.rst index 68bf1fea5..1a3a239c3 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 the 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. - 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 ` - 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 2a254693a..172edb1bd 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 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. + 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]