Fixes gh-538 Document box.session.push() and IPROTO_CHUNK code

Author: pgulutzan

doc/1.10/book/box/box_session.rst

@@ -9,7 +9,8 @@
 ===============================================================================
 
 The ``box.session`` submodule allows querying the session state, writing to a
-session-specific temporary Lua table, or setting up triggers which will fire
+session-specific temporary Lua table, or sending out-of-band messages, or
+setting up triggers which will fire
 when a session starts or ends. A *session* is an object associated with each
 client connection.
 
@@ -66,6 +67,10 @@ Below is a list of all ``box.session`` functions and members.
     | :ref:`box.session.on_auth()          | Define an authentication        |
     | <box_session-on_auth>`               | trigger                         |
     +--------------------------------------+---------------------------------+
+    | :ref:`box.session.push()             | Send an out-of-band message     |
+    | <box_session-push>`                  |                                 |
+    +--------------------------------------+---------------------------------+
+
 
 .. module:: box.session
 
@@ -476,3 +481,130 @@ Below is a list of all ``box.session`` functions and members.
         function 2, box.session.user()=guest
         function 2, user_name=admin
         function 1, box.session.user()=guest
+
+.. _box_session-push:
+
+.. function:: box.session.push(message [, sync])
+
+    Generate an out-of-band message. By "out-of-band" we mean an extra
+    message which supplements what is passed in a network via the usual
+    channels. Although ``box.session.push()`` can be called at any time, in
+    practice it is used with networks that are set up with
+    :ref:`module net.box <net_box-module>`, and
+    it is invoked by the server (on the "remote database system" to use
+    our terminology for net.box), and the client has options for getting
+    such messages.
+
+    :param string-or-number message: what to send
+    :param int sync: for an optional argument to indicate what the session is,
+                     as taken from an earlier call to :ref:`box_session:sync() <box_session-sync>`.
+                     If it is omitted, the default is the current ``box.session.sync()`` value.
+    :rtype: {nil, error} or true.
+
+    If the result is an error, then the first part of the return is
+    ``nil`` and the second part is the error object. If the result is not
+    an error, then the return is the boolean value ``true``.
+    When the return is ``true``, the message has gone to the network
+    buffer as a :ref:`packet <box_protocol-iproto_protocol>`
+    with the code IPROTO_CHUNK (0x80).
+
+    The server's sole job is to call ``box.session.push()``, there is no
+    automatic mechanism for showing that the message was received.
+    The client's job is to check for such messages after it sends
+    something to the server. The major client methods --
+    :ref:`conn:call <net_box-call>`, :ref:`conn:eval <net_box-eval>`,
+    :ref:`conn:select <conn-select>`, :ref:`conn:insert <conn-insert>`,
+    :ref:`conn:replace <conn-replace>`, :ref:`conn:update <conn-update>`,
+    :ref:`conn:upsert <conn-upsert>`, :ref:`delete <conn-delete>` --
+    may cause the server to send a message.
+
+    Situation 1: when the client calls synchronously with the default
+    ``{async=false}`` option: there are two optional additional options:
+    :samp:`on_push={function-name}`, and :samp:`on_push_ctx={function-argument}`.
+    When the client receives an out-of-band message for the session,
+    it invokes "function-name(function-argument)". For example, with
+    options ``{on_push=table.insert, on_push_ctx=messages}``, the client
+    will insert whatever it receives into a table named messages.
+
+    Situation 2: when the client calls asynchronously with the non-default
+    ``{async=true}`` option: ``on_push`` and ``on_push_ctx`` are not allowed, but
+    the messages can be seen by calling ``pairs()`` in a loop.
+
+    Situation 2 complication: ``pairs()`` is subject to timeout. So there
+    is an optional argument = timeout per iteration. If timeout occurs before
+    there is a new message or a final response, there is an error return.
+    To check for an error a one can use the first loop parameter (if the loop
+    starts with "for i, message in future:pairs()" then the first loop parameter
+    is i). If it is box.NULL then the second parameter (in our example, "message")
+    is the error object.
+
+    ** Example **
+
+    .. code-block:: lua
+
+        -- Make two shells. On Shell#1 set up a "server", and
+        -- in it have a function that includes box.session.push:
+        box.cfg{listen=3301}
+        box.schema.user.grant('guest','read,write,execute','universe')
+        x = 0
+        fiber = require('fiber')
+        function server_function() x=x+1; fiber.sleep(1); box.session.push(x); end
+
+        -- On Shell#2 connect to this server as a "client" that
+        -- can handle Lua (such as another Tarantool server operating
+        -- as a client), and initialize a table where we'll get messages:
+        net_box = require('net.box')
+        conn = net_box.connect(3301)
+        messages_from_server = {}
+
+        -- On Shell#2 remotely call the server function and receive
+        -- a SYNCHRONOUS out-of-band message:
+        conn:call('server_function', {},
+                  {is_async = false,
+                   on_push = table.insert,
+                   on_push_ctx = messages_from_server})
+        messages_from_server
+        -- After a 1-second pause that is caused by the fiber.sleep()
+        -- request inside server_function, the result in the
+        --  messages_from_server table will be: 1. Like this:
+        -- tarantool> messages_from_server
+        -- ---
+        -- - - 1
+        -- ...
+        -- Good. That shows that box.session.push(x) worked,
+        -- because we know that x was 1.
+
+        -- On Shell#2 remotely call the same server function and
+        -- get an ASYNCHRONOUS out-of-band message. For this we cannot
+        -- use on_push and on_push_ctx options, but we can use pairs():
+        future = conn:call('server_function', {}, {is_async = true})
+        messages = {}
+        keys = {}
+        for i, message in future:pairs() do
+            table.insert(messages, message) table.insert(keys, i) end
+        messages
+        future:wait_result(1000)
+        for i, message in future:pairs() do
+            table.insert(messages, message) table.insert(keys, i) end
+        messages
+        -- There is no pause because conn:call does not wait for
+        -- server_function to finish. The first time that we go through
+        -- the pairs() loop, we see the messages table is empty. Like this:
+        -- tarantool> messages
+        -- ---
+        -- - - 2
+        --   - []
+        -- ...
+        -- That is okay because the server hasn't yet called
+        -- box.session.push(). The second time that we go through
+        -- the pairs() loop, we see the value of x at the time of
+        -- the second call to box.session.push(). Like this:
+        -- tarantool> messages
+        -- ---
+        -- - - 2
+         --  - &0 []
+         --  - 2
+        --   - *0
+        -- ...
+        -- Good. That shows that the message was asynchronous, and
+        -- that box.session.push() did its job.

doc/1.10/dev_guide/box_protocol.rst

@@ -125,7 +125,8 @@ We list them here too:
     <join>         ::= 0x41
     <subscribe>    ::= 0x42
     <request_vote> ::= 0x43
-
+    -- box.session.push's out-of-band message 
+    <chunk>        ::= 0x80
     -- -- Value for <code> key in response can be:
     <OK>      ::= 0x00
     <ERROR>   ::= 0x8XXX

doc/1.10/reference/reference_lua/net_box.rst

@@ -42,6 +42,8 @@ Most ``net.box`` methods allow a final ``{options}`` argument, which can be:
 * ``{is_async=...}``. For example, a method whose final argument is
   ``{is_async=true}`` will not wait for the result of a request. See the
   :ref:`is_async <net_box-is_async>` description.
+* ``{on_push=... on_push_ctx=...}``. For receiving out-of-band messages.
+  See the :ref:`box.session.push <box_session-push>` description.
 
 The diagram below shows possible connection states and transitions: