Description
Product: Tarantool
Since: 3.0
Root document: https://www.tarantool.io/en/doc/latest/dev_guide/internals/iproto/requests/
SME: @ locker
Details
The new request type IPROTO_WATCH_ONCE has code 77 and can be used to
synchronously fetch the value currently associated with a specified
notification key. You can use it instead of IPROTO_WATCH if you just
need to get the current value without subscribing to future changes.
The new request is a standard synchronous request. Like any other
synchronous request (for example, IPROTO_SELECT), it takes a sync
number (IPROTO_SYNC) and optionally the desired schema version
(IPROTO_SCHEMA_VERSION) in the header. The same sync number and
the actual schema version are returned in the response header.
The request body is supposed to contain a single key IPROTO_EVENT_KEY
(which is also used by IPROTO_WATCH) with a string value that stores
the notification key of interest. The actual value is returned in the
response body, in the first entry of the IPROTO_DATA array. If there's
no value associated with a notification key (the key has never been
broadcast or was last set to nil), the IPROTO_DATA array will be
empty. (Note that IPROTO_DATA is also used by most other synchronous
requests. For example, IPROTO_SELECT returns the selected tuple array
in it.)
For example, suppose a key was broadcast with the following command on
the server:
box.broadcast('foo', {1, 2, 3})Then IPROTO_WATCH_ONCE for IPROTO_EVENT_KEY equal to 'foo' will
return IPROTO_DATA' equal to [[1, 2, 3]]` (an array of one entry
containing the current value).
If the key didn't exist or was set to nil with
box.broadcast('foo', nil)then IPROTO_WATCH_ONCE would return IPROTO_DATA equal to []
(an empty array).
The request shouldn't normally fail. It may fail only on some sort of
system error (out of memory; socket error), on schema version mismatch,
or on invalid input.
Like IPROTO_WATCH, the new request doesn't require authentication.
Like IPROTO_WATCH, the new request can't processed in a stream
(IPROTO_STREAM_ID must not be set in the request header).
If a server supports the IPROTO_WATCH_ONCE request, it'll set the
IPROTO_FEATURE_WATCH_ONCE = 6 bit in the protocol feature mask and
report the protocol version >= 6 in response to IPROTO_ID.
Requested by @locker in tarantool/tarantool@6dc1433.