-
-
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. SPDX-License-Identifier: CC-BY-4.0
.. CAUTION: this document is generated from source in doc/src/rtd.
.. To make changes edit the source and recompile the document.
.. Do NOT make changes directly to .rst or .md files.
-
============================================================================================
Man Page: rmr_mt_rcv
============================================================================================
-RMR Library Functions
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_mt_rcv
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
rmr_mbuf_t* rmr_mt_rcv( void* vctx, rmr_mbuf_t* old_msg, int timeout );
-
-
-DESCRIPTION
---------------------------------------------------------------------------------------------
-
-The rmr_mt_rcv function blocks until a message is received,
-or the timeout period (milliseconds) has passed. The result
-is an RMR message buffer which references a received message.
-In the case of a timeout the state will be reflected in an
-"empty buffer" (if old_msg was not nil, or simply with the
-return of a nil pointer. If a timeout value of zero (0) is
-given, then the function will block until the next message
-received.
-
-The *vctx* pointer is the pointer returned by the rmr_init
-function. *Old_msg* is a pointer to a previously used message
-buffer or NULL. The ability to reuse message buffers helps to
-avoid alloc/free cycles in the user application. When no
-buffer is available to supply, the receive function will
-allocate one.
+
+
+DESCRIPTION
+-----------
+
+The ``rmr_mt_rcv`` function blocks until a message is
+received, or the timeout period (milliseconds) has passed.
+The result is an RMR message buffer which references a
+received message. In the case of a timeout the state will be
+reflected in an "empty buffer" (if old_msg was not nil, or
+simply with the return of a nil pointer. If a timeout value
+of zero (0) is given, then the function will block until the
+next message received.
+
+The *vctx* pointer is the pointer returned by the
+``rmr_init`` function. *Old_msg* is a pointer to a previously
+used message buffer or NULL. The ability to reuse message
+buffers helps to avoid alloc/free cycles in the user
+application. When no buffer is available to supply, the
+receive function will allocate one.
The *old_msg* parameter allows the user to pass a previously
generated RMR message back to RMR for reuse. Optionally, the
*rmr_torcv_msg()* call can be used when in multi-threaded
mode with the same "pass through" overhead to using this
function directly.
-
-RETURN VALUE
---------------------------------------------------------------------------------------------
-
+
+
+RETURN VALUE
+------------
+
When a message is received before the timeout period expires,
a pointer to the RMR message buffer which describes the
message is returned. This will, with a high probability, be a
In the event of a timeout the return value will be the old
msg with the state set, or a nil pointer if no old message
was provided.
-
-ERRORS
---------------------------------------------------------------------------------------------
-
+
+
+ERRORS
+------
+
The *state* field in the message buffer will be set to one of
the following values:
-
-RMR_OK
-
- The message was received without error.
-
-
-RMR_ERR_BADARG
-
- A parameter passed to the function was not valid (e.g. a
- nil pointer). indicate either RMR_OK or RMR_ERR_EMPTY if
- an empty message was received.
-
-
-RMR_ERR_EMPTY
-
- The message received had no associated data. The length of
- the message will be 0.
-
-
-RMR_ERR_NOTSUPP
-
- The multi-threaded option was not enabled when RMR was
- initialised. See the man page for *rmr_init()* for
- details.
-
-
-RMR_ERR_RCVFAILED
-
- A hard error occurred preventing the receive from
- completing.
+ .. list-table::
+ :widths: auto
+ :header-rows: 0
+ :class: borderless
+
+ * - **RMR_OK**
+ -
+ The message was received without error.
+
+ * - **RMR_ERR_BADARG**
+ -
+ A parameter passed to the function was not valid (e.g. a nil
+ pointer). indicate either ``RMR_OK`` or ``RMR_ERR_EMPTY`` if
+ an empty message was received.
+
+ * - **RMR_ERR_EMPTY**
+ -
+ The message received had no associated data. The length of
+ the message will be 0.
+
+ * - **RMR_ERR_NOTSUPP**
+ -
+ The multi-threaded option was not enabled when RMR was
+ initialised. See the man page for *rmr_init()* for details.
+
+ * - **RMR_ERR_RCVFAILED**
+ -
+ A hard error occurred preventing the receive from completing.
+
When a nil pointer is returned, or any other state value was
-set in the message buffer, errno will be set to one of the
-following:
-
-
-
-INVAL
-
- Parameter(s) passed to the function were not valid.
-
-
-EBADF
-
- The underlying message transport is unable to process the
- request.
-
-
-ENOTSUP
-
- The underlying message transport is unable to process the
- request.
-
-
-EFSM
-
- The underlying message transport is unable to process the
- request.
-
-
-EAGAIN
-
- The underlying message transport is unable to process the
- request.
-
-
-EINTR
-
- The underlying message transport is unable to process the
- request.
-
-
-ETIMEDOUT
-
- The underlying message transport is unable to process the
- request.
-
-
-ETERM
-
- The underlying message transport is unable to process the
- request.
-
-
-EXAMPLE
---------------------------------------------------------------------------------------------
-
+set in the message buffer, ``errno`` will be set to one of
+the following:
+
+
+ .. list-table::
+ :widths: auto
+ :header-rows: 0
+ :class: borderless
+
+ * - **INVAL**
+ -
+ Parameter(s) passed to the function were not valid.
+
+ * - **EBADF**
+ -
+ The underlying message transport is unable to process the
+ request.
+
+ * - **ENOTSUP**
+ -
+ The underlying message transport is unable to process the
+ request.
+
+ * - **EFSM**
+ -
+ The underlying message transport is unable to process the
+ request.
+
+ * - **EAGAIN**
+ -
+ The underlying message transport is unable to process the
+ request.
+
+ * - **EINTR**
+ -
+ The underlying message transport is unable to process the
+ request.
+
+ * - **ETIMEDOUT**
+ -
+ The underlying message transport is unable to process the
+ request.
+
+ * - **ETERM**
+ -
+ The underlying message transport is unable to process the
+ request.
+
+
+
+
+EXAMPLE
+-------
+
::
-
+
rmr_mbuf_t* mbuf = NULL; // received msg
+
msg = rmr_mt_recv( mr, mbuf, 100 ); // wait up to 100ms
if( msg != NULL ) {
switch( msg->state ) {
case RMR_OK:
printf( "got a good message\\n" );
break;
+
case RMR_ERR_EMPTY:
printf( "received timed out\\n" );
break;
+
default:
printf( "receive error: %d\\n", mbuf->state );
break;
printf( "receive timeout (nil)\\n" );
}
-
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+
+
+SEE ALSO
+--------
+
rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3),
rmr_mt_call(3), rmr_payload_size(3), rmr_send_msg(3),
Code Review / ric-plt / lib / rmr.git / blobdiff