Add box.watch_once() (#4692)

Resolves #3510

Author: p7nov

doc/reference/reference_lua/box_events.rst

@@ -64,9 +64,12 @@ Below is a list of all functions and pages related to watchers or events.
         *   - Name
             - Use
 
-        *  - :doc:`./box_events/watch`
+        *  - :ref:`box.watch() <box-watch>`
            - Create a local watcher.
 
+        *  - :ref:`box.watch_once() <box-watch>`
+           - Get the current key value.
+
         *  - :ref:`conn:watch() <conn-watch>`
            - Create a watcher for the remote host.
 
@@ -80,5 +83,6 @@ Below is a list of all functions and pages related to watchers or events.
     :hidden:
 
     box_events/watch
+    box_events/watch_once
     box_events/broadcast
     box_events/system_events

doc/reference/reference_lua/box_events/watch_once.rst

@@ -0,0 +1,37 @@
+.. _box-watch_once:
+
+box.watch_once()
+================
+
+..  function:: box.watch_once(key, func)
+
+    Returns the current value of a given notification key.
+    The function can be used as an alternative to :ref:`box.watch() <box-watch>`
+    when the caller only needs the current value without subscribing to future changes.
+
+    :param string key: key name
+
+    :return: the key value
+
+    To read more about watchers, see the :ref:`box-watchers` section.
+
+    **Example:**
+
+    ..  code-block:: lua
+
+        -- Broadcast value 42 for the 'foo' key.
+        box.broadcast('foo', 42)
+
+        -- Get the value of this key
+        tarantool> box.watch_once('foo')
+        ---
+        - 42
+        ...
+
+        -- Non-existent keys' values are empty
+        tarantool> box.watch_once('none')
+        ---
+        ...
+
+
+