-
-
.. 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_call
============================================================================================
-RMR Library Functions
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_mt_call
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
extern rmr_mbuf_t* rmr_mt_call( void* vctx, rmr_mbuf_t* msg, int id, int timeout );
-
-
-DESCRIPTION
---------------------------------------------------------------------------------------------
-
-The rmr_mt_call function sends the user application message
-to a remote endpoint, and waits for a corresponding response
-message before returning control to the user application. The
-user application supplies a completed message buffer, as it
-would for a rmr_send_msg call, but unlike with a send, the
-buffer returned will have the response from the application
-that received the message. The thread invoking the
-*rmr_mt_call()* will block until a message arrives or until
-*timeout* milliseconds has passed; which ever comes first.
-Using a timeout value of zero (0) will cause the thread to
-block without a timeout.
+
+
+DESCRIPTION
+-----------
+
+The ``rmr_mt_call`` function sends the user application
+message to a remote endpoint, and waits for a corresponding
+response message before returning control to the user
+application. The user application supplies a completed
+message buffer, as it would for a ``rmr_send_msg`` call, but
+unlike with a send, the buffer returned will have the
+response from the application that received the message. The
+thread invoking the *rmr_mt_call()* will block until a
+message arrives or until *timeout* milliseconds has passed;
+which ever comes first. Using a timeout value of zero (0)
+will cause the thread to block without a timeout.
The *id* supplied as the third parameter is an integer in the
range of 2 through 255 inclusive. This is a caller defined
are queued on a *normal* receive queue and will be delivered
to the user application with the next invocation of
*rmr_mt_rcv()* or *rmr_rvv_msg().* by RMR, and are returned
-to the user application when rmr_rcv_msg is invoked. These
-messages are returned in the order received, one per call to
-rmr_rcv_msg.
-
-The Transaction ID
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+to the user application when ``rmr_rcv_msg`` is invoked.
+These messages are returned in the order received, one per
+call to ``rmr_rcv_msg.``
+
+
+The Transaction ID
+------------------
+
The user application is responsible for setting the value of
the transaction ID field before invoking *rmr_mt_call.* The
-transaction ID is a RMR_MAX_XID byte field that is used to
-match the response message when it arrives. RMR will compare
-**all** of the bytes in the field, so the caller must ensure
-that they are set correctly to avoid missing the response
-message. The application which returns the response message
-is also expected to ensure that the return buffer has the
-matching transaction ID. This can be done transparently if
-the application uses the *rmr_rts_msg()* function and does
+transaction ID is a ``RMR_MAX_XID`` byte field that is used
+to match the response message when it arrives. RMR will
+compare **all** of the bytes in the field, so the caller must
+ensure that they are set correctly to avoid missing the
+response message. The application which returns the response
+message is also expected to ensure that the return buffer has
+the matching transaction ID. This can be done transparently
+if the application uses the *rmr_rts_msg()* function and does
not adjust the transaction ID.
-
-Retries
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+Retries
+-------
+
The send operations in RMR will retry *soft* send failures
until one of three conditions occurs:
-
-1.
-
- The message is sent without error
-
-
-2.
-
- The underlying transport reports a *hard* failure
-
-
-3.
-
- The maximum number of retry loops has been attempted
+ &item The message is sent without error
+
+ &item The underlying transport reports a *hard* failure
+
+ &item The maximum number of retry loops has been attempted
A retry loop consists of approximately 1000 send attempts
initialisation using the *rmr_set_stimeout()* function
allowing the user application to completely disable retires
(set to 0), or to increase the number of retry loops.
-
-Transport Level Blocking
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+Transport Level Blocking
+------------------------
+
The underlying transport mechanism used to send messages is
configured in *non-blocking* mode. This means that if a
message cannot be sent immediately the transport mechanism
RMR to retry the send operation, and even then it is possible
(e.g., during connection reattempts), that a single retry
loop is not enough to guarantee a successful send.
-
-RETURN VALUE
---------------------------------------------------------------------------------------------
-
-The rmr_mt_call function returns a pointer to a message
+
+
+RETURN VALUE
+------------
+
+The ``rmr_mt_call`` function returns a pointer to a message
buffer with the state set to reflect the overall state of
-call processing. If the state is RMR_OK then the buffer
+call processing. If the state is ``RMR_OK`` then the buffer
contains the response message; otherwise the state indicates
the error encountered while attempting to send the message.
If no response message is received when the timeout period
has expired, a nil pointer will be returned (NULL).
-
-ERRORS
---------------------------------------------------------------------------------------------
-
+
+
+ERRORS
+------
+
These values are reflected in the state field of the returned
message.
-
-RMR_OK
-
- The call was successful and the message buffer references
- the response message.
-
-
-RMR_ERR_BADARG
-
- An argument passed to the function was invalid.
-
-
-RMR_ERR_CALLFAILED
-
- The call failed and the value of *errno,* as described
- below, should be checked for the specific reason.
-
-
-RMR_ERR_NOENDPT
-
- An endpoint associated with the message type could not be
- found in the route table.
-
-
-RMR_ERR_RETRY
-
- The underlying transport mechanism was unable to accept
- the message for sending. The user application can retry
- the call operation if appropriate to do so.
+ .. list-table::
+ :widths: auto
+ :header-rows: 0
+ :class: borderless
+
+ * - **RMR_OK**
+ -
+ The call was successful and the message buffer references the
+ response message.
+
+ * - **RMR_ERR_BADARG**
+ -
+ An argument passed to the function was invalid.
+
+ * - **RMR_ERR_CALLFAILED**
+ -
+ The call failed and the value of *errno,* as described below,
+ should be checked for the specific reason.
+
+ * - **RMR_ERR_NOENDPT**
+ -
+ An endpoint associated with the message type could not be
+ found in the route table.
+
+ * - **RMR_ERR_RETRY**
+ -
+ The underlying transport mechanism was unable to accept the
+ message for sending. The user application can retry the call
+ operation if appropriate to do so.
+
The global "variable" *errno* will be set to one of the
successful.
-
-ETIMEDOUT
-
- Too many messages were queued before receiving the
- expected response
-
-
-ENOBUFS
-
- The queued message ring is full, messages were dropped
-
-
-EINVAL
-
- A parameter was not valid
-
-
-EAGAIN
-
- The underlying message system wsa interrupted or the
- device was busy; the message was **not** sent, and user
- application should call this function with the message
- again.
-
-
-EXAMPLE
---------------------------------------------------------------------------------------------
-
-The following code bit shows one way of using the rmr_mt_call
-function, and illustrates how the transaction ID must be set.
+ .. list-table::
+ :widths: auto
+ :header-rows: 0
+ :class: borderless
+
+ * - **ETIMEDOUT**
+ -
+ Too many messages were queued before receiving the expected
+ response
+
+ * - **ENOBUFS**
+ -
+ The queued message ring is full, messages were dropped
+
+ * - **EINVAL**
+ -
+ A parameter was not valid
+
+ * - **EAGAIN**
+ -
+ The underlying message system wsa interrupted or the device
+ was busy; the message was **not** sent, and user application
+ should call this function with the message again.
+
+
+
+
+EXAMPLE
+-------
+
+The following code bit shows one way of using the
+``rmr_mt_call`` function, and illustrates how the transaction
+ID must be set.
::
-
+
int retries_left = 5; // max retries on dev not available
static rmr_mbuf_t* mbuf = NULL; // response msg
msg_t* pm; // appl message struct (payload)
+
// get a send buffer and reference the payload
mbuf = rmr_alloc_msg( mr, sizeof( pm->req ) );
pm = (msg_t*) mbuf->payload;
+
// generate an xaction ID and fill in payload with data and msg type
rmr_bytes2xact( mbuf, xid, RMR_MAX_XID );
snprintf( pm->req, sizeof( pm->req ), "{ \\"req\\": \\"num users\\"}" );
mbuf->mtype = MT_USR_RESP;
+
msg = rmr_mt_call( mr, msg, my_id, 100 ); // wait up to 100ms
if( ! msg ) { // probably a timeout and no msg received
return NULL; // let errno trickle up
}
+
if( mbuf->state != RMR_OK ) {
while( retries_left-- > 0 && // loop as long as eagain
mbuf->state == RMR_ERR_RETRY &&
(msg = rmr_mt_call( mr, msg )) != NULL &&
mbuf->state != RMR_OK ) {
+
usleep( retry_delay );
}
+
if( mbuf == NULL || mbuf->state != RMR_OK ) {
rmr_free_msg( mbuf ); // safe if nil
return NULL;
}
}
+
// do something with mbuf
-
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+
+
+SEE ALSO
+--------
+
rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3),
rmr_mt_rcv(3), rmr_payload_size(3), rmr_send_msg(3),
rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
Code Review / ric-plt / lib / rmr.git / blobdiff