Skip to content
Snippets Groups Projects
user avatar
Vladimir Davydov authored
Part of #6257

@TarantoolBot document
Title: Document box.watch and box.broadcast

`box.watch(key, func)` registers a watcher for the given key and returns
a watcher handle, which can be used to unregister the watcher (by
calling the `unregister` method). A key is an arbitrary string. It's
possible to register more than one watcher for the same key. 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.

`box.broadcast(key, value)` updates the value of the given key and
signals all watchers registered for it.

A watcher callback is first invoked unconditionally after the watcher
registration. Subsequent invocations are triggered by `box.broadcast()`
called on the local 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.

`box.watch` and `box.broadcast` may be used before `box.cfg`.

Example usage:

```lua
-- Broadcast value 123 for key 'foo'.
box.broadcast('foo', 123)
-- Subscribe to updates of key 'foo'.
w = box.watch('foo', function(key, value)
    assert(key == 'foo')
    -- do something with value
end)
-- Unregister the watcher when it's no longer needed.
w:unregister()
```
11f2d999
History
Name Last commit Last update