[3pt] Document net.box watchers

[TarantoolBot]

Document conn:watch method in net.box

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

Details

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:

  -- Broadcast value 123 for key 'foo'.
  box.broadcast('foo', 123)

• Client:

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

Requested by @locker in tarantool/tarantool@eb7712e.