Description
Document IPROTO watchers
Product: Tarantool
Root document: https://www.tarantool.io/en/doc/latest/dev_guide/internals/box_protocol/
SME: @ locker
Peer reviewer: @
Details
There are three new commands to support asynchronous server->client
notifications signaled with box.broadcast()
:
-
IPROTO_WATCH
(code 74). Registers a new watcher for the given
notification key or acknowledges a notification if a watcher is
already registered. The key name is passed inIPROTO_EVENT_KEY
(code 0x56). The watcher will be notified unconditionally after
registration and then every time the key is updated with
box.broadcast()
provided the last notification was acknowledged.
The server doesn't reply to the request unless it fails to parse
the packet. -
IPROTO_UNWATCH
(code 75). Unregisters a watcher registered for the
given notification key. The key name is passed inIPROTO_EVENT_KEY
(code 0x56). A server doesn't reply to the request unless it fails to
parse the packet. -
IPROTO_EVENT
(code 76). Sent by the server to notify a client
about a key update. The key name is passed inIPROTO_EVENT_KEY
(code 0x56). The key data (optional) is passed inIPROTO_EVENT_DATA
(code 0x57).
When a connection is closed, all watchers registered for it are
unregistered.
Servers that support the new feature set the IPROTO_FEATURE_WATCHERS
feature bit (bit 3) in reply to the IPROTO_ID
command.
Requested by @locker in tarantool/tarantool@4be5de4.