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" );
}