docs/rmr_rcv_msg.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_rcv_msg 
============================================================================================ 
 
RMR Library Functions 
============================================================================================ 
 
 
NAME 
-------------------------------------------------------------------------------------------- 
 
rmr_rcv_msg 
 
SYNOPSIS 
-------------------------------------------------------------------------------------------- 
 
 
:: 
  
 #include <rmr/rmr.h>
 rmr_mbuf_t* rmr_rcv_msg( void* vctx, rmr_mbuf_t* old_msg );
 
 
 
DESCRIPTION 
-------------------------------------------------------------------------------------------- 
 
The rmr_rcv_msg function blocks until a message is received, 
returning the message to the caller via a pointer to a 
rmr_mbuf_t structure type. If messages were queued while 
waiting for the response to a previous invocation of 
rmr_call, the oldest message is removed from the queue and 
returned without delay. 
 
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. 
 
RETURN VALUE 
-------------------------------------------------------------------------------------------- 
 
The function returns a pointer to the rmr_mbuf_t structure 
which references the message information (state, length, 
payload), or a nil pointer in the case of an extreme error. 
 
ERRORS 
-------------------------------------------------------------------------------------------- 
 
The *state* field in the message buffer will indicate RMR_OK 
when the message receive process was successful and the 
message can be used by the caller. Depending on the 
underlying transport mechanism, one of the following RMR 
error stats may be returned: 
 
 
 
RMR_ERR_EMPTY 
   
  The message received had no payload, or was completely 
  empty. 
   
 
RMR_ERR_TIMEOUT 
   
  For some transport mechanisms, or if reading the receive 
  queue from multiple threads, it is possible for one thread 
  to find no data waiting when it queries the queue. When 
  this state is reported, the message buffer does not 
  contain message data and the user application should 
  reinvoke the receive function. 
 
 
When an RMR error state is reported, the underlying errno 
value might provide more information. The following is a list 
of possible values that might accompany the states listed 
above: 
 
RMR_ERR_EMPTY if an empty message was received. If 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 
-------------------------------------------------------------------------------------------- 
 
 
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_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)