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.