Event watchers
Since 2.10.0.
The box module contains some features related to event subscriptions, also known as watchers.
The subscriptions are used to inform the client about server-side events.
Each event subscription is defined by a certain key.
- Event
- An event is a state change or a system update that triggers the action of other systems. To read more about built-in events in Tarantool, check the system events section.
- State
- A state is an internally stored key-value pair.
The key is a string.
The value is an arbitrary type that can be encoded as MsgPack.
To update a state, use the
box.broadcast()function. - Watcher
- A watcher is a callback that is invoked when a state change occurs.
To register a local watcher, use the
box.watch()function. To create a remote watcher, use thewatch()function from thenet.boxmodule. Note that it is possible to register more than one watcher for the same key.
First, you register a watcher. After that, the watcher callback is invoked for the first time. In this case, the callback is triggered whether or not the key has already been broadcast. All subsequent invocations are triggered with box.broadcast() called on the remote host. If a watcher is subscribed for a key that has not been broadcast yet, the callback is triggered only once, after the registration of the watcher.
The watcher callback takes two arguments. The first argument is the name of the key for which it was registered. The second one contains current key data. The callback is always invoked in a new fiber. It means that it is allowed to yield in it. A watcher callback is never executed in parallel with itself. If the key 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 functions can be used before box.cfg.
Below is a list of all functions and pages related to watchers or events.
| Name | Use |
|---|---|
| box.watch() | Create a local watcher. |
| conn:watch() | Create a watcher for the remote host. |
| box.broadcast() | Update a state. |
| Built-in events | Predefined events in Tarantool |