Skip to content

Commit f58bb6f

Browse files
xuniqlenkis
xuniq
and
lenkis
authored
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]>
1 parent dca6d47 commit f58bb6f

File tree

2 files changed

+79
-40
lines changed

2 files changed

+79
-40
lines changed

‎doc/reference/reference_lua/box_once.rst‎

Lines changed: 58 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,7 @@
11
.. _box-once:
22

3-
-------------------------------------------------------------------------------
4-
Function box.once
5-
-------------------------------------------------------------------------------
3+
Function box.once
4+
=================
65

76
.. function:: box.once(key, function[, ...])
87

@@ -18,40 +17,77 @@
1817
stopping the database. The solution is to delete the ``once`` object from
1918
the system space :ref:`_schema <box_space-schema>`.
2019
Say ``box.space._schema:select{}``, find your ``once`` object there and
21-
delete it. For example, re-executing a block with ``key='hello'`` :
20+
delete it.
2221

2322
When ``box.once()`` is used for initialization, it may be useful to
2423
wait until the database is in an appropriate state (read-only or read-write).
2524
In that case, see the functions in the :doc:`/reference/reference_lua/box_ctl`.
2625

27-
.. code-block:: tarantoolsession
26+
:param string key: a value that will be checked
27+
:param function function: a function
28+
:param ...: arguments that must be passed to the function
29+
30+
.. NOTE::
31+
32+
The parameter ``key`` will be stored in the :ref:`_schema <box_space-schema>`
33+
system space after ``box.once()`` is called in order to prevent a double
34+
run. These keys are global per replica set. So a simultaneous call of
35+
``box.once()`` with the same key on two instances of the same replica set
36+
may succeed on both of them, but it'll lead to a transaction conflict.
2837

29-
tarantool> box.space._schema:select{}
38+
39+
**Example**
40+
41+
The example shows how to re-execute the ``box.once()`` block that contains the ``hello`` key.
42+
43+
First, check the ``_schema`` system space.
44+
The ``_schema`` space in the example contains two ``box.once`` objects -- ``oncebye`` and ``oncehello``:
45+
46+
.. code-block:: tarantoolsession
47+
48+
app:instance001> box.space._schema:select{}
3049
---
31-
- - ['cluster', 'b4e15788-d962-4442-892e-d6c1dd5d13f2']
32-
- ['max_id', 512]
33-
- ['oncebye']
50+
- - ['oncebye']
3451
- ['oncehello']
35-
- ['version', 1, 7, 2]
36-
...
52+
- ['replicaset_name', 'replicaset001']
53+
- ['replicaset_uuid', '72d2d9bf-5d9f-48c4-ba80-9d657e128fee']
54+
- ['version', 3, 1, 0]
55+
56+
Delete the ``oncehello`` object:
57+
58+
.. code-block:: tarantoolsession
3759
38-
tarantool> box.space._schema:delete('oncehello')
60+
app:instance001> box.space._schema:delete('oncehello')
3961
---
4062
- ['oncehello']
4163
...
4264
43-
tarantool> box.once('hello', function() end)
65+
After that, check the ``_schema`` space again:
66+
67+
.. code-block:: tarantoolsession
68+
69+
app:instance001> box.space._schema:select{}
4470
---
71+
- - ['oncebye']
72+
- ['replicaset_name', 'replicaset001']
73+
- ['replicaset_uuid', '72d2d9bf-5d9f-48c4-ba80-9d657e128fee']
74+
- ['version', 3, 1, 0]
4575
...
4676
47-
:param string key: a value that will be checked
48-
:param function function: a function
49-
:param ...: arguments that must be passed to function
77+
To re-execute the function, call the ``box.once()`` method again:
5078

51-
.. NOTE::
79+
.. code-block:: tarantoolsession
80+
81+
app:instance001> box.once('hello', function() end)
82+
---
83+
...
84+
85+
app:instance001> box.space._schema:select{}
86+
---
87+
- - ['oncebye']
88+
- ['oncehello']
89+
- ['replicaset_name', 'replicaset001']
90+
- ['replicaset_uuid', '72d2d9bf-5d9f-48c4-ba80-9d657e128fee']
91+
- ['version', 3, 1, 0]
92+
...
5293
53-
The parameter ``key`` will be stored in the :ref:`_schema <box_space-schema>`
54-
system space after ``box.once()`` is called in order to prevent a double
55-
run. These keys are global per replica set. So a simultaneous call of
56-
``box.once()`` with the same key on two instances of the same replica set
57-
may succeed on both of them, but it'll lead to a transaction conflict.

‎doc/reference/reference_lua/box_space/_schema.rst‎

Lines changed: 21 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,7 @@
11
.. _box_space-schema:
22

3-
===============================================================================
43
box.space._schema
5-
===============================================================================
4+
=================
65

76
.. module:: box.space
87

@@ -12,28 +11,32 @@ box.space._schema
1211

1312
This space contains the following tuples:
1413

15-
* ``version`` tuple with version information for this Tarantool instance,
16-
* ``cluster`` tuple with the instance's replica set ID,
17-
* ``max_id`` tuple with the maximal space ID,
18-
* ``once...`` tuples that correspond to specific
19-
:doc:`box.once() </reference/reference_lua/box_once>` blocks from the instance's
14+
* ``version``: version information for this Tarantool instance.
15+
* ``replicaset_name`` (since :doc:`3.0.0 <release/3.0.0>`): the name of the replica set to which this instance belongs.
16+
* ``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>`,
17+
the field was renamed from ``cluster`` to ``replicaset_uuid``.
18+
* ``max_id`` (deprecated since `2.11.1 <https://github.com/tarantool/tarantool/releases/tag/2.11.1>`__): the maximal space ID.
19+
Use the :ref:`box.space._space.index[0]:max() <box_index-max>` function instead.
20+
* ``once...``: tuples that correspond to specific
21+
:ref:`box.once() <box-once>` blocks from the instance's
2022
:ref:`initialization file <index-init_label>`.
2123
The first field in these tuples contains the ``key`` value from the
22-
corresponding ``box.once()`` block prefixed with 'once' (e.g. `oncehello`),
24+
corresponding ``box.once()`` block prefixed with 'once' (for example, ``oncehello``),
2325
so you can easily find a tuple that corresponds to a specific
2426
``box.once()`` block.
2527

2628
**Example:**
2729

28-
Here is what ``_schema`` contains in a typical installation (notice the
29-
tuples for two ``box.once()`` blocks, ``'oncebye'`` and ``'oncehello'``):
30+
In the example, the ``_schema`` space contains two ``box.once`` objects -- ``oncebye`` and ``oncehello``.
3031

31-
.. code-block:: tarantoolsession
32+
.. code-block:: tarantoolsession
33+
34+
app:instance001> box.space._schema:select{}
35+
---
36+
- - ['oncebye']
37+
- ['oncehello']
38+
- ['replicaset_name', 'replicaset001']
39+
- ['replicaset_uuid', '72d2d9bf-5d9f-48c4-ba80-9d657e128fee']
40+
- ['version', 3, 1, 0]
41+
...
3242
33-
tarantool> box.space._schema:select{}
34-
---
35-
- - ['cluster', 'b4e15788-d962-4442-892e-d6c1dd5d13f2']
36-
- ['max_id', 512]
37-
- ['oncebye']
38-
- ['oncehello']
39-
- ['version', 1, 7, 2]

0 commit comments

Comments
 (0)