Skip to content

Commit 4a87eca

Browse files
xuniqxuniq
committed
Update text
1 parent 8ed04a7 commit 4a87eca

File tree

3 files changed

+185
-11
lines changed

3 files changed

+185
-11
lines changed

‎doc/reference/reference_lua/net_box.rst

Lines changed: 40 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -125,14 +125,16 @@ Below is a list of all ``net.box`` functions.
125125
* - :ref:`conn:call() <net_box-call>`
126126
- Call a stored procedure
127127
* - :ref:`conn:timeout() <conn-timeout>`
128-
- Set a timeout
128+
- Set a timeout
129+
* - :ref:`conn:watch() <conn-watch>`
130+
- Subscribe to events broadcast by a remote host
129131
* - :ref:`conn:on_connect() <net_box-on_connect>`
130132
- Define a connect trigger
131133
* - :ref:`conn:on_disconnect() <net_box-on_disconnect>`
132134
- Define a disconnect trigger
133135
* - :ref:`conn:on_schema_reload() <net_box-on_schema_reload>`
134136
- Define a trigger when schema is modified
135-
* - :ref:`conn:new_stream() <conn-new_stream>`
137+
* - :ref:`conn:new_stream() <conn-new_stream>`
136138
- Create a stream
137139
* - :ref:`stream:begin() <net_box-stream_begin>`
138140
- Begin a stream transaction
@@ -533,7 +535,43 @@ Below is a list of all ``net.box`` functions.
533535
- B
534536
...
535537
538+
.. _conn-watch:
536539

540+
.. method:: watch(key, func)
541+
542+
Subscribe to events broadcast by a remote host.
543+
544+
:param string key: a key name to subscribe to
545+
:param number func: a callback to invoke when the key value is updated
546+
:return: a watcher handle that can be used to unregister the watcher
547+
:rtype: ?
548+
549+
.. admonition:: note
550+
551+
Garbage collection of a watcher handle doesn't result in unregistering the watcher.
552+
It is okay to discard the result of box.watch if the watcher is never going to be unregistered.
553+
554+
**Example:**
555+
556+
Server:
557+
558+
.. code-block:: lua
559+
560+
-- Broadcast value 123 for key 'foo'.
561+
box.broadcast('foo', 123)
562+
563+
Client:
564+
565+
.. code-block:: lua
566+
567+
conn = net.box.connect(URI)
568+
-- Subscribe to updates of key 'foo'.
569+
w = conn:watch('foo', function(key, value)
570+
assert(key == 'foo')
571+
-- do something with value
572+
end)
573+
-- Unregister the watcher when it's no longer needed.
574+
w:unregister()
537575
538576
.. _conn-timeout:
539577

‎doc/reference/reference_rock/vshard/index.rst

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -11,13 +11,14 @@ scaling in Tarantool.
1111
Check out the :ref:`Quick start guide <vshard-quick-start>` -- or dive into the
1212
complete ``vshard`` documentation:
1313

14-
.. toctree::
15-
:maxdepth: 2
16-
:numbered: 0
14+
.. toctree::
15+
:maxdepth: 2
16+
:numbered: 0
1717

18-
vshard_summary_index
19-
vshard_architecture
20-
vshard_admin
21-
vshard_quick
22-
vshard_ref
23-
vshard_api
18+
vshard_summary_index
19+
vshard_architecture
20+
vshard_admin
21+
vshard_quick
22+
vshard_ref
23+
vshard_api
24+
vshard_pub-sub

‎doc/reference/reference_rock/vshard/vshard_pub-sub.rst

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
.. _vshard-pubsub:
2+
3+
Pub/sub system and its events
4+
=============================
5+
6+
Pub/sub is a notification system for Tarantool events.
7+
It is related to one-time subscriptions.
8+
9+
Events that the system will process:
10+
11+
box.id
12+
box.status
13+
box.election
14+
box.schema
15+
16+
As a reaction to each event, the server sends back specific IPROTO fields.
17+
18+
Built-in events for pub/sub
19+
---------------------------
20+
21+
The important purpose of the built-in events is to learn who is the
22+
master, unless it is defined in an application specific way. Knowing who
23+
is the master is necessary to send changes to a correct instance, and
24+
probably make reads of the most actual data if it is important. Also
25+
defined more built-in events for other mutable properties like leader
26+
state change, his election role and election term, schema version change
27+
and instance state.
28+
29+
Built-in events have a special naming schema - their name always starts
30+
with box.. The prefix is reserved for built-in events. Creating new events
31+
with this prefix is banned. Below is a list of all the events + their names
32+
and values:
33+
34+
.. container:: table
35+
36+
.. list-table::
37+
:widths: 20 40 40
38+
39+
* - Built-in event
40+
- Description
41+
- Value
42+
43+
* - box.id
44+
- Identification of the instance. Changes are extra rare. Some
45+
values never change or change only once. For example, instance UUID never
46+
changes after the first box.cfg. But is not known before box.cfg is called.
47+
Replicaset UUID is unknown until the instance joins to a replicaset or
48+
bootsa new one, but the events are supposed to start working before that -
49+
right at listen launch. Instance numeric ID is known only after
50+
registration. On anonymous replicas is 0 until they are registered officially.
51+
- .. code-block:: lua
52+
53+
{
54+
MP_STR “id”: MP_UINT; box.info.id,
55+
MP_STR “instance_uuid”: MP_UUID; box.info.uuid,
56+
MP_STR “replicaset_uuid”: MP_UUID box.info.cluster.uuid,
57+
}
58+
59+
* - box.status
60+
- Generic blob about instance status. It is most commonly used
61+
and not frequently changed config options and box.info fields.]
62+
- .. code-block:: lua
63+
64+
{
65+
MP_STR “is_ro”: MP_BOOL box.info.ro,
66+
MP_STR “is_ro_cfg”: MP_BOOL box.cfg.read_only,
67+
MP_STR “status”: MP_STR box.info.status,
68+
}
69+
70+
* - box.election
71+
- All the needed parts of box.info.election needed to find who is the most recent writable leader.
72+
- .. code-block:: lua
73+
74+
{
75+
MP_STR “term”: MP_UINT box.info.election.term,
76+
MP_STR “role”: MP_STR box.info.election.state,
77+
MP_STR “is_ro”: MP_BOOL box.info.ro,
78+
MP_STR “leader”: MP_UINT box.info.election.leader,
79+
}
80+
81+
* - box.schema
82+
- Schema-related data. Currently it is only version.
83+
- .. code-block:: lua
84+
85+
{
86+
MP_STR “version”: MP_UINT schema_version,
87+
}
88+
89+
Built-in events can't be override. Meaning, users can't be able to call
90+
box.broadcast(‘box.id’, any_data) etc.
91+
92+
The events are available from the very beginning as not MP_NIL. It's
93+
necessary for supported local subscriptions. Otherwise, there is no way to detect
94+
whether an event is even supported at all by this Tarantool version. If
95+
events are broadcast before box.cfg{}, then the following values will
96+
available:
97+
box.id = {}
98+
box.schema = {}
99+
box.status = {}
100+
box.election = {}
101+
102+
This way, the users will be able to distinguish an event being not supported
103+
at all from ``box.cfg{}`` being not called yet. Otherwise they would need to
104+
parse ``_TARANTOOL`` version string locally and peer_version in net.box.
105+
106+
Usage example
107+
-------------
108+
109+
.. code-block:: lua
110+
111+
conn = net.box.connect(URI)
112+
-- Subscribe to updates of key 'box.id'
113+
w = conn:watch('box.id', function(key, value)
114+
assert(key == 'box.id')
115+
-- do something with value
116+
end)
117+
-- or to updates of key 'box.status'
118+
w = conn:watch('box.status', function(key, value)
119+
assert(key == 'box.status')
120+
-- do something with value
121+
end)
122+
-- or to updates of key 'box.election'
123+
w = conn:watch('box.election', function(key, value)
124+
assert(key == 'box.election')
125+
-- do something with value
126+
end)
127+
-- or to updates of key 'box.schema'
128+
w = conn:watch('box.schema', function(key, value)
129+
assert(key == 'box.schema')
130+
-- do something with value
131+
end)
132+
-- Unregister the watcher when it's no longer needed.
133+
w:unregister()
134+
135+

0 commit comments

Comments
 (0)