tarantool / tarantool / 5253172795

88%

push

github

net.box: introduce conn:watch_once method

Closes #6493

@TarantoolBot document
Title: Document `conn:watch_once()` net.box connection method

The new method takes a notification key and returns the value currently
associated with it.

For example, let's assume that a Tarantool server was started with the
following script:

```lua
box.cfg{listen = 3301}
box.broadcast('foo', {1, 2, 3})
```

Then the `conn:watch_once()` method would yield the following results:

```yaml
tarantool> conn = require('net.box').connect(3301)
---
...

tarantool> conn:watch_once('foo')
---
- [1, 2, 3]
...

tarantool> conn:watch_once('bar')
---
- null
...
```

The new method can be used instead of `conn:watch()` in case the caller
only needs to retrieve the current associated with a notification key
value without subscribing to future changes.

The method can also take a net.box options table as a second argument.
It supports all the standard request options: `is_async`, `return_raw`,
`timeout`, and others. They work exactly in the same way as with other
net.box method, for example `conn:call`. For example,

```lua
local future = conn:watch_once('foo', {is_async = true})
future:wait_result()

local obj = conn:watch_once('foo', {return_raw = true})
require('msgpack').is_object(obj)
```

Like `conn:watch()`, the new method doesn't require authentication.

Like `conn:watch()`, the new method can be executed in a stream
(see `conn:new_stream()`), but it isn't streamlined (i.e. calling it
as a stream method has the same effect as calling it as a connection
method).

The net.box connection will set `conn.peer_protocol_features.watch_once`
to true if the remote end supports `conn:watch_once()`.

The new method is implemented using the `IPROTO_WATCH_ONCE` request.

63185 of 115741 branches covered (54.59%)

9 of 9 new or added lines in 1 file covered. (100.0%)

94806 of 110411 relevant lines covered (85.87%)

2846227.07 hits per line