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)