3 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
4 .. SPDX-License-Identifier: CC-BY-4.0
5 .. CAUTION: this document is generated from source in doc/src/rtd.
6 .. To make changes edit the source and recompile the document.
7 .. Do NOT make changes directly to .rst or .md files.
10 ============================================================================================
12 ============================================================================================
15 ============================================================================================
19 --------------------------------------------------------------------------------------------
24 --------------------------------------------------------------------------------------------
30 rmr_mbuf_t* rmr_mt_rcv( void* vctx, rmr_mbuf_t* old_msg, int timeout );
35 --------------------------------------------------------------------------------------------
37 The rmr_mt_rcv function blocks until a message is received,
38 or the timeout period (milliseconds) has passed. The result
39 is an RMR message buffer which references a received message.
40 In the case of a timeout the state will be reflected in an
41 "empty buffer" (if old_msg was not nil, or simply with the
42 return of a nil pointer. If a timeout value of zero (0) is
43 given, then the function will block until the next message
46 The *vctx* pointer is the pointer returned by the rmr_init
47 function. *Old_msg* is a pointer to a previously used message
48 buffer or NULL. The ability to reuse message buffers helps to
49 avoid alloc/free cycles in the user application. When no
50 buffer is available to supply, the receive function will
53 The *old_msg* parameter allows the user to pass a previously
54 generated RMR message back to RMR for reuse. Optionally, the
55 user application may pass a nil pointer if no reusable
56 message is available. When a timeout occurs, and old_msg was
57 not nil, the state will be returned by returning a pointer to
58 the old message with the state set.
60 It is possible to use the *rmr_rcv_msg()* function instead of
61 this function. Doing so might be advantageous if the user
62 programme does not always start the multi-threaded mode and
63 the use of *rmr_rcv_msg()* would make the flow of the code
64 more simple. The advantages of using this function are the
65 ability to set a timeout without using epoll, and a small
66 performance gain (if multi-threaded mode is enabled, and the
67 *rmr_rcv_msg()* function is used, it simply invokes this
68 function without a timeout value, thus there is the small
69 cost of a second call that results). Similarly, the
70 *rmr_torcv_msg()* call can be used when in multi-threaded
71 mode with the same "pass through" overhead to using this
75 --------------------------------------------------------------------------------------------
77 When a message is received before the timeout period expires,
78 a pointer to the RMR message buffer which describes the
79 message is returned. This will, with a high probability, be a
80 different message buffer than *old_msg;* the user application
81 should not continue to use *old_msg* after it is passed to
84 In the event of a timeout the return value will be the old
85 msg with the state set, or a nil pointer if no old message
89 --------------------------------------------------------------------------------------------
91 The *state* field in the message buffer will be set to one of
98 The message was received without error.
103 A parameter passed to the function was not valid (e.g. a
104 nil pointer). indicate either RMR_OK or RMR_ERR_EMPTY if
105 an empty message was received.
110 The message received had no associated data. The length of
111 the message will be 0.
116 The multi-threaded option was not enabled when RMR was
117 initialised. See the man page for *rmr_init()* for
123 A hard error occurred preventing the receive from
126 When a nil pointer is returned, or any other state value was
127 set in the message buffer, errno will be set to one of the
134 Parameter(s) passed to the function were not valid.
139 The underlying message transport is unable to process the
145 The underlying message transport is unable to process the
151 The underlying message transport is unable to process the
157 The underlying message transport is unable to process the
163 The underlying message transport is unable to process the
169 The underlying message transport is unable to process the
175 The underlying message transport is unable to process the
180 --------------------------------------------------------------------------------------------
186 rmr_mbuf_t* mbuf = NULL; // received msg
187 msg = rmr_mt_recv( mr, mbuf, 100 ); // wait up to 100ms
189 switch( msg->state ) {
191 printf( "got a good message\\n" );
194 printf( "received timed out\\n" );
197 printf( "receive error: %d\\n", mbuf->state );
201 printf( "receive timeout (nil)\\n" );
207 --------------------------------------------------------------------------------------------
209 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
210 rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3),
211 rmr_mt_call(3), rmr_payload_size(3), rmr_send_msg(3),
212 rmr_torcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
213 rmr_ready(3), rmr_ring_free(3), rmr_torcv_msg(3)