1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
2 .. SPDX-License-Identifier: CC-BY-4.0
3 .. CAUTION: this document is generated from source in doc/src/rtd.
4 .. To make changes edit the source and recompile the document.
5 .. Do NOT make changes directly to .rst or .md files.
7 ============================================================================================
9 ============================================================================================
33 rmr_mbuf_t* rmr_mt_rcv( void* vctx, rmr_mbuf_t* old_msg, int timeout );
40 The ``rmr_mt_rcv`` function blocks until a message is
41 received, or the timeout period (milliseconds) has passed.
42 The result is an RMR message buffer which references a
43 received message. In the case of a timeout the state will be
44 reflected in an "empty buffer" (if old_msg was not nil, or
45 simply with the return of a nil pointer. If a timeout value
46 of zero (0) is given, then the function will block until the
47 next message received.
49 The *vctx* pointer is the pointer returned by the
50 ``rmr_init`` function. *Old_msg* is a pointer to a previously
51 used message buffer or NULL. The ability to reuse message
52 buffers helps to avoid alloc/free cycles in the user
53 application. When no buffer is available to supply, the
54 receive function will allocate one.
56 The *old_msg* parameter allows the user to pass a previously
57 generated RMR message back to RMR for reuse. Optionally, the
58 user application may pass a nil pointer if no reusable
59 message is available. When a timeout occurs, and old_msg was
60 not nil, the state will be returned by returning a pointer to
61 the old message with the state set.
63 It is possible to use the *rmr_rcv_msg()* function instead of
64 this function. Doing so might be advantageous if the user
65 programme does not always start the multi-threaded mode and
66 the use of *rmr_rcv_msg()* would make the flow of the code
67 more simple. The advantages of using this function are the
68 ability to set a timeout without using epoll, and a small
69 performance gain (if multi-threaded mode is enabled, and the
70 *rmr_rcv_msg()* function is used, it simply invokes this
71 function without a timeout value, thus there is the small
72 cost of a second call that results). Similarly, the
73 *rmr_torcv_msg()* call can be used when in multi-threaded
74 mode with the same "pass through" overhead to using this
81 When a message is received before the timeout period expires,
82 a pointer to the RMR message buffer which describes the
83 message is returned. This will, with a high probability, be a
84 different message buffer than *old_msg;* the user application
85 should not continue to use *old_msg* after it is passed to
88 In the event of a timeout the return value will be the old
89 msg with the state set, or a nil pointer if no old message
96 The *state* field in the message buffer will be set to one of
107 The message was received without error.
109 * - **RMR_ERR_BADARG**
111 A parameter passed to the function was not valid (e.g. a nil
112 pointer). indicate either ``RMR_OK`` or ``RMR_ERR_EMPTY`` if
113 an empty message was received.
115 * - **RMR_ERR_EMPTY**
117 The message received had no associated data. The length of
118 the message will be 0.
120 * - **RMR_ERR_NOTSUPP**
122 The multi-threaded option was not enabled when RMR was
123 initialised. See the man page for *rmr_init()* for details.
125 * - **RMR_ERR_RCVFAILED**
127 A hard error occurred preventing the receive from completing.
130 When a nil pointer is returned, or any other state value was
131 set in the message buffer, ``errno`` will be set to one of
142 Parameter(s) passed to the function were not valid.
146 The underlying message transport is unable to process the
151 The underlying message transport is unable to process the
156 The underlying message transport is unable to process the
161 The underlying message transport is unable to process the
166 The underlying message transport is unable to process the
171 The underlying message transport is unable to process the
176 The underlying message transport is unable to process the
189 rmr_mbuf_t* mbuf = NULL; // received msg
191 msg = rmr_mt_recv( mr, mbuf, 100 ); // wait up to 100ms
193 switch( msg->state ) {
195 printf( "got a good message\\n" );
199 printf( "received timed out\\n" );
203 printf( "receive error: %d\\n", mbuf->state );
207 printf( "receive timeout (nil)\\n" );
215 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
216 rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3),
217 rmr_mt_call(3), rmr_payload_size(3), rmr_send_msg(3),
218 rmr_torcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
219 rmr_ready(3), rmr_ring_free(3), rmr_torcv_msg(3)