Skip to content
Snippets Groups Projects
Commit eb7712e3 authored by Vladimir Davydov's avatar Vladimir Davydov Committed by Vladimir Davydov
Browse files

net.box: add watchers support

Part of #6257

@TarantoolBot document
Title: Document net.box watchers

Using the new `watch` method of a net.box connection, one can subscribe
to events broadcasted by a remote host. The method has the same syntax
as the `box.watch()` function, which is used for subscribing to events
locally. It takes a key name (string) to subscribe to and a callback to
invoke when the key value is updated. It returns a watcher handle that
can be used to unregister the watcher. Note, garbage collection of a
watcher handle doesnt result in unregistering the watcher so it's okay
to discard the result of `box.watch` if the watcher is never going to be
unregistered.

A watcher callback is first invoked unconditionally after the watcher
registration. Subsequent invocations are triggered by `box.broadcast()`
called on the remote host. A watcher callback is passed the name of the
key the watcher was subscribed to and the current key value. A watcher
callback is always executed in a new fiber so it's okay to yield inside
it. A watcher callback never runs in parallel with itself: if the key
to which a watcher is subscribed is updated while the watcher callback
is running, the callback will be invoked again with the new value as
soon as it returns.

Watchers survive reconnect (see `reconnect_after` connection option):
all registered watchers are automatically resubscribed as soon as the
connection is reestablished.

If a remote host supports watchers, the 'watchers' key will be set in
connection's `peer_protocol_features`.

Example usage:

 * Server:
   ```lua
   -- Broadcast value 123 for key 'foo'.
   box.broadcast('foo', 123)
   ```
 * Client:
   ```lua
   conn = net.box.connect(URI)
   -- Subscribe to updates of key 'foo'.
   w = conn:watch('foo', function(key, value)
       assert(key == 'foo')
       -- do something with value
   end)
   -- Unregister the watcher when it's no longer needed.
   w:unregister()
   ```
parent 4be5de4c
No related branches found
No related tags found
Loading
Loading
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment