[5pt] Document box.watch and box.broadcast

[TarantoolBot]

Document functions box.watch and box.broadcast

Product: Tarantool
Root document: https://www.tarantool.io/en/doc/latest/reference/reference_lua/box/
SME: @ locker
Peer reviewer:

Details

1. 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.

2. 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:

-- 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()

Requested by @locker in tarantool/tarantool@11f2d99.