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() ```
Showing
- changelogs/unreleased/gh-6257-net-box-watcher.md 3 additions, 0 deletionschangelogs/unreleased/gh-6257-net-box-watcher.md
- src/box/lua/net_box.c 111 additions, 11 deletionssrc/box/lua/net_box.c
- src/box/lua/net_box.lua 185 additions, 1 deletionsrc/box/lua/net_box.lua
- src/box/xrow.c 6 additions, 0 deletionssrc/box/xrow.c
- src/box/xrow.h 5 additions, 1 deletionsrc/box/xrow.h
- test/box/net.box_watcher.result 536 additions, 0 deletionstest/box/net.box_watcher.result
- test/box/net.box_watcher.test.lua 174 additions, 0 deletionstest/box/net.box_watcher.test.lua
- test/box/net.box_watcher_reconnect.result 122 additions, 0 deletionstest/box/net.box_watcher_reconnect.result
- test/box/net.box_watcher_reconnect.test.lua 40 additions, 0 deletionstest/box/net.box_watcher_reconnect.test.lua
- test/box/suite.ini 1 addition, 1 deletiontest/box/suite.ini
Loading
Please register or sign in to comment