.. 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_mt_rcv ============================================================================================ RMR Library Functions ============================================================================================ NAME -------------------------------------------------------------------------------------------- rmr_mt_rcv SYNOPSIS -------------------------------------------------------------------------------------------- :: #include 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" ); } 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_mt_call(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)