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_rcv_msg( void* vctx, rmr_mbuf_t* old_msg );
40 The ``rmr_rcv_msg`` function blocks until a message is
41 received, returning the message to the caller via a pointer
42 to a ``rmr_mbuf_t`` structure type. If messages were queued
43 while waiting for the response to a previous invocation of
44 ``rmr_call,`` the oldest message is removed from the queue
45 and returned without delay.
47 The *vctx* pointer is the pointer returned by the
48 ``rmr_init`` function. *Old_msg* is a pointer to a previously
49 used message buffer or NULL. The ability to reuse message
50 buffers helps to avoid alloc/free cycles in the user
51 application. When no buffer is available to supply, the
52 receive function will allocate one.
58 The function returns a pointer to the ``rmr_mbuf_t``
59 structure which references the message information (state,
60 length, payload), or a nil pointer in the case of an extreme
67 The *state* field in the message buffer will indicate
68 ``RMR_OK`` when the message receive process was successful
69 and the message can be used by the caller. Depending on the
70 underlying transport mechanism, one of the following RMR
71 error stats may be returned:
81 The message received had no payload, or was completely empty.
84 * - **RMR_ERR_TIMEOUT**
86 For some transport mechanisms, or if reading the receive
87 queue from multiple threads, it is possible for one thread to
88 find no data waiting when it queries the queue. When this
89 state is reported, the message buffer does not contain
90 message data and the user application should reinvoke the
95 When an RMR error state is reported, the underlying
96 ``errno`` value might provide more information. The following
97 is a list of possible values that might accompany the states
100 ``RMR_ERR_EMPTY`` if an empty message was received. If a nil
101 pointer is returned, or any other state value was set in the
102 message buffer, ``errno`` will be set to one of the
113 Parameter(s) passed to the function were not valid.
117 The underlying message transport is unable to process the
122 The underlying message transport is unable to process the
127 The underlying message transport is unable to process the
132 The underlying message transport is unable to process the
137 The underlying message transport is unable to process the
142 The underlying message transport is unable to process the
147 The underlying message transport is unable to process the
161 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
162 rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3),
163 rmr_payload_size(3), rmr_send_msg(3), rmr_torcv_msg(3),
164 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
165 rmr_ring_free(3), rmr_torcv_msg(3)