Events and subscriptions
The commands below support asynchronous server-client notifications signalled
with box.broadcast().
Servers that support the new feature set the IPROTO_FEATURE_WATCHERS feature in reply to the IPROTO_ID command.
When the connection is closed, all watchers registered for it are unregistered.
The remote watcher (event subscription) protocol works in the following way:
- The client sends an
IPROTO_WATCHpacket to subscribe to the updates of a specified key defined on the server. - The server sends an
IPROTO_EVENTpacket to the subscribed client after registration. The packet contains the key name and its current value. After that, the packet is sent every time the key value is updated withbox.broadcast(), provided that the last notification was acknowledged (see below). - After receiving the notification, the client sends an
IPROTO_WATCHpacket to acknowledge the notification. - If the client doesn’t want to receive any more notifications, it unsubscribes by sending
an
IPROTO_UNWATCHpacket.
All the three request types are asynchronous – the receiving end doesn’t send a packet in reply to any of them. Therefore, neither of them has a sync number.
Code: 0x4a.
Register a new watcher for the given notification key or confirms a notification if the watcher is already subscribed. The watcher is notified after registration. After that, the notification is sent every time the key is updated. The server doesn’t reply to the request unless it fails to parse the packet.
Code: 0x4b.
Unregister a watcher subscribed to the given notification key. The server doesn’t reply to the request unless it fails to parse the packet.