From b81b7934954398e044486f1e3ec937a6ffd0ba8e Mon Sep 17 00:00:00 2001 From: Samuel Gaist <samuel.gaist@idiap.ch> Date: Thu, 14 Mar 2019 15:05:06 +0100 Subject: [PATCH] [doc] Update backend api doc The some of the commands described here were for the V1 API. --- doc/backend_api.rst | 159 +++++++------------------------------------- 1 file changed, 24 insertions(+), 135 deletions(-) diff --git a/doc/backend_api.rst b/doc/backend_api.rst index 060a0b19..7ac828bb 100644 --- a/doc/backend_api.rst +++ b/doc/backend_api.rst @@ -267,170 +267,59 @@ In the remainder of this section, we describe the various commands, which are supported by this communication protocol. -Command: has-more-data (hmd) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Command: information (ifo) +~~~~~~~~~~~~~~~~~~~~~~~~~~ (User Process -> Infrastructure) -This command asks the infrastructure, whether there is more input data in a -given input or not. The format of this command is: +This command asks the infrastructure to return information about the remote +data sources queried. The format of this command is: .. code-block:: text - "hmd channel [name]" - -where ``name`` refers to the input name and is optional. - -The BEAT infrastructure will answer by writing the following into the input -pipe. - -.. code-block:: text - - "boolean" - -where `boolean` is a boolean indicating whether there is more data to process -or not. The values may be ``tru``, for True and ``fal``, for False. - - -Command: is-dataunit-done (idd) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -(User Process -> Infrastructure) - - -This command asks the infrastructure, whether the current chunk of data is -going to change or not, next time the current data index is increased. The -format of this command is: - -.. code-block:: text - - "idd channel name" + "ifo name\n" The infrastructure will answer by writing the following into the input pipe. .. code-block:: text - "boolean" - -where `boolean` is a boolean indicating whether there is more data to process -or not. The values may be ``tru``, for True and ``fal``, for False. - - -Command: next (nxt) -~~~~~~~~~~~~~~~~~~~ - -(User Process -> Infrastructure) - - -This command asks the infrastructure to provide the next data on a given -channel and/or input. If no input ``name`` is provided, then the infrastructure -will return the data on all inputs of the given ``channel``. The format of this -command is: - -.. code-block:: text - - "nxt channel [name]" - -where ``name`` refers to the input name and is optional. - -If an input ``name`` is provided, the infrastructure will answer by writing the -following into the input pipe: - -.. code-block:: text - - "dat N name1 <bin1> .. nameN-1 <binN-1>" - -where ``N`` refers to the number of data chunks in the reply, ``name`` is the -name of a given channel, and ``<bin>`` corresponds to the binary representation -of the data contents. The binary data format uses the same format for disk -storage used by the infrastructure so as to optimize I/O performance. Our -reference backend implementation at `beat.backend.python`_ contains -implementation details about the binary data format. As a backend developer, -you must ensure your backend is fully capable of **correctly** interpreting the -contents of the binary stream given the data formats associated with each input -and output of the algorithm. - - -Command: write (wrt) -~~~~~~~~~~~~~~~~~~~~ - -(User Process -> Infrastructure) - - -This command asks the infrastructure to write data on a given output. The -format of this command is: - -.. code-block:: text - - "wrt name <bin>" - -The ``name`` identifies the output on which to write the data. The message -`<bin>` is the raw data to write on the output, pre-encoded in the same binary -data format as the one used for the input. The contents of the binary stream -sent to the infrastructure will be checked again before being written to disk. -In case of problems, a system error will be issued and the processing will -stop. It is the task of the backend developer to insure conformity in order to -avoid such errors. - -The infrastructure acknowledges with: - -.. code-block:: text - - "ack" + "X" + "Start0" + "End0" + ... + "StartX-1" + "EndX-1" -In case all is OK or with the keyword ``err``, if there was an error -interpreting the binary data back. In such cases, the UP is expected to stop -processing and issue a ``done`` command, waiting to be gracefully stopped by -the infrastructure. If the UP does not issue the ``done`` command next, the UP -is forcibly terminated with a operating system level signal. +where `X` is the length of the data source and the `StartX` and `EndX` are the +start and end indexes available through that data source. -Command: is-data-missing (idm) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Command: get data (get) +~~~~~~~~~~~~~~~~~~~~~~~ (User Process -> Infrastructure) -This command asks the infrastructure whether there is missing data on a given -output, by looking at the synchronization information. The format of this -command is: - -.. code-block:: text - - "idm name" - -The infrastructure will answer by writing the following into the input pipe. +This command asks the infrastructure to return the data at the given index. +The format of this command is: .. code-block:: text - "boolean" - -where `boolean` is a boolean indicating whether there is more data to process -or not. The values may be ``tru``, for True and ``fal``, for False. - - -Command: output-is-connected (oic) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -(User Process -> Infrastructure) - - -This command asks the infrastructure, whether a given output is connected or -not. The format of this command is: - -.. code-block:: text + "get X" - "ict name\n" +where X is the index of the data in the data source. The infrastructure will answer by writing the following into the input pipe. .. code-block:: text - "boolean" + "StartX" + "EndX" + "data" -where `boolean` is a boolean indicating whether there is more data to process -or not. The values may be ``tru``, for True and ``fal``, for False. +where `StartX` and `EndX` and the start and end indexes in the data sources and +`data` is the packed data that the data sources provides. Command: done (don) -- GitLab