docs/rmr_mt_call.3.rst

 
 
.. 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_mt_call 
 
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. 
 
The *id* supplied as the third parameter is an integer in the 
range of 2 through 255 inclusive. This is a caller defined 
"thread number" and is used to match the response message 
with the correct user application thread. If the ID value is 
not in the proper range, the attempt to make the call will 
fail. 
 
Messages which are received while waiting for the response 
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 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
 
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 
not adjust the transaction ID. 
 
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 
 
 
A retry loop consists of approximately 1000 send attempts 
**without** any intervening calls to *sleep()* or *usleep().* 
The number of retry loops defaults to 1, thus a maximum of 
1000 send attempts is performed before returning to the user 
application. This value can be set at any point after RMr 
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 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
 
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 
will **not** pause with the assumption that the inability to 
send will clear quickly (within a few milliseconds). This 
means that when the retry loop is completely disabled (set to 
0), that the failure to accept a message for sending by the 
underlying mechanisms (software or hardware) will be reported 
immediately to the user application. 
 
It should be noted that depending on the underlying transport 
mechanism being used, it is extremely likely that retry 
conditions will happen during normal operations. These are 
completely out of RMR's control, and there is nothing that 
RMR can do to avoid or mitigate these other than by allowing 
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 
buffer with the state set to reflect the overall state of 
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 
-------------------------------------------------------------------------------------------- 
 
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. 
 
 
The global "variable" *errno* will be set to one of the 
following values if the overall call processing was not 
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. 
 
 
:: 
  
     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 
-------------------------------------------------------------------------------------------- 
 
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), 
rmr_ready(3), rmr_fib(3), rmr_has_str(3), 
rmr_set_stimeout(3), rmr_tokenise(3), rmr_mk_ring(3), 
rmr_ring_free(3)