docs/rmr_mt_rcv.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_rcv 
============================================================================================ 
 
RMR Library Functions 
============================================================================================ 
 
 
NAME 
-------------------------------------------------------------------------------------------- 
 
rmr_mt_rcv 
 
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. 
 
The *old_msg* parameter allows the user to pass a previously 
generated RMR message back to RMR for reuse. Optionally, the 
user application may pass a nil pointer if no reusable 
message is available. When a timeout occurs, and old_msg was 
not nil, the state will be returned by returning a pointer to 
the old message with the state set. 
 
It is possible to use the *rmr_rcv_msg()* function instead of 
this function. Doing so might be advantageous if the user 
programme does not always start the multi-threaded mode and 
the use of *rmr_rcv_msg()* would make the flow of the code 
more simple. The advantages of using this function are the 
ability to set a timeout without using epoll, and a small 
performance gain (if multi-threaded mode is enabled, and the 
*rmr_rcv_msg()* function is used, it simply invokes this 
function without a timeout value, thus there is the small 
cost of a second call that results). Similarly, 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 
-------------------------------------------------------------------------------------------- 
 
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 
different message buffer than *old_msg;* the user application 
should not continue to use *old_msg* after it is passed to 
this function. 
 
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 
-------------------------------------------------------------------------------------------- 
 
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. 
 
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 
-------------------------------------------------------------------------------------------- 
 
 
 
:: 
  
     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;
         }
     } else {
         printf( "receive timeout (nil)\\n" );
     }
 
 
 
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), 
rmr_torcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), 
rmr_ready(3), rmr_ring_free(3), rmr_torcv_msg(3)