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 ============================================================================================
8 Man Page: rmr_torcv_msg
9 ============================================================================================
33 rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to );
40 The ``rmr_torcv_msg`` function will pause for *ms_to*
41 milliseconds waiting for a message to arrive. If a message
42 arrives before the timeout expires the message buffer
43 returned will have a status of RMR_OK and the payload will
44 contain the data received. If the timeout expires before the
45 message is received, the status will have the value
46 RMR_ERR_TIMEOUT. When a received message is returned the
47 message buffer will also contain the message type and length
48 set by the sender. If messages were queued while waiting for
49 the response to a previous invocation of ``rmr_call,`` the
50 oldest message is removed from the queue and returned without
53 The *vctx* pointer is the pointer returned by the
54 ``rmr_init`` function. *Old_msg* is a pointer to a previously
55 used message buffer or NULL. The ability to reuse message
56 buffers helps to avoid alloc/free cycles in the user
57 application. When no buffer is available to supply, the
58 receive function will allocate one.
64 The function returns a pointer to the ``rmr_mbuf_t``
65 structure which references the message information (state,
66 length, payload), or a nil pointer in the case of an extreme
73 The *state* field in the message buffer will be one of the
84 The message buffer (payload) references the received data.
86 * - **RMR_ERR_INITFAILED**
88 The first call to this function must initialise an underlying
89 system notification mechanism. On failure, this error is
90 returned and errno will have the system error status set. If
91 this function fails to initialise, the poll mechanism, it is
92 likely that message receives will never be successful.
94 * - **RMR_ERR_TIMEOUT**
96 The timeout expired before a complete message was received.
97 All other fields in the message buffer are not valid.
101 A message was received, but it had no payload. All other
102 fields in the message buffer are not valid.
105 Upon return the system error number, *errno* might be set
106 with a value that can help to explain the meaning of the
107 state indicated in the message. The following are possible:
116 Parameter(s) passed to the function were not valid.
120 The underlying message transport is unable to process the
125 The underlying message transport is unable to process the
130 The underlying message transport is unable to process the
135 The underlying message transport is unable to process the
140 The underlying message transport is unable to process the
145 The underlying message transport is unable to process the
150 The underlying message transport is unable to process the
164 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
165 rmr_get_rcvfd(3), rmr_init(3), rmr_payload_size(3),
166 rmr_rcv_msg(3), rmr_send_msg(3), rmr_rcv_specific(3),
167 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
168 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)