Man Page: rmr_torcv_msg¶
RMR LIBRARY FUNCTIONS¶
NAME¶
rmr_torcv_msg
SYNOPSIS¶
#include <rmr/rmr.h>
rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to );
DESCRIPTION¶
The rmr_torcv_msg
function will pause for ms_to
milliseconds waiting for a message to arrive. If a message
arrives before the timeout expires the message buffer
returned will have a status of RMR_OK and the payload will
contain the data received. If the timeout expires before the
message is received, the status will have the value
RMR_ERR_TIMEOUT. When a received message is returned the
message buffer will also contain the message type and length
set by the sender. 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 be one of the following:
RMR_OK
The message buffer (payload) references the received data.
RMR_ERR_INITFAILED
The first call to this function must initialise an underlying system notification mechanism. On failure, this error is returned and errno will have the system error status set. If this function fails to initialise, the poll mechanism, it is likely that message receives will never be successful.
RMR_ERR_TIMEOUT
The timeout expired before a complete message was received. All other fields in the message buffer are not valid.
RMR_ERR_EMPTY
A message was received, but it had no payload. All other fields in the message buffer are not valid.
Upon return the system error number, errno might be set with a value that can help to explain the meaning of the state indicated in the message. The following are possible:
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_payload_size(3), rmr_rcv_msg(3), rmr_send_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)