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_rcv_msg( void* vctx, rmr_mbuf_t* old_msg );
35 --------------------------------------------------------------------------------------------
37 The rmr_rcv_msg function blocks until a message is received,
38 returning the message to the caller via a pointer to a
39 rmr_mbuf_t structure type. If messages were queued while
40 waiting for the response to a previous invocation of
41 rmr_call, the oldest message is removed from the queue and
42 returned without delay.
44 The *vctx* pointer is the pointer returned by the rmr_init
45 function. *Old_msg* is a pointer to a previously used message
46 buffer or NULL. The ability to reuse message buffers helps to
47 avoid alloc/free cycles in the user application. When no
48 buffer is available to supply, the receive function will
52 --------------------------------------------------------------------------------------------
54 The function returns a pointer to the rmr_mbuf_t structure
55 which references the message information (state, length,
56 payload), or a nil pointer in the case of an extreme error.
59 --------------------------------------------------------------------------------------------
61 The *state* field in the message buffer will indicate RMR_OK
62 when the message receive process was successful and the
63 message can be used by the caller. Depending on the
64 underlying transport mechanism, one of the following RMR
65 error stats may be returned:
71 The message received had no payload, or was completely
77 For some transport mechanisms, or if reading the receive
78 queue from multiple threads, it is possible for one thread
79 to find no data waiting when it queries the queue. When
80 this state is reported, the message buffer does not
81 contain message data and the user application should
82 reinvoke the receive function.
85 When an RMR error state is reported, the underlying errno
86 value might provide more information. The following is a list
87 of possible values that might accompany the states listed
90 RMR_ERR_EMPTY if an empty message was received. If a nil
91 pointer is returned, or any other state value was set in the
92 message buffer, errno will be set to one of the following:
98 Parameter(s) passed to the function were not valid.
103 The underlying message transport is unable to process the
109 The underlying message transport is unable to process the
115 The underlying message transport is unable to process the
121 The underlying message transport is unable to process the
127 The underlying message transport is unable to process the
133 The underlying message transport is unable to process the
139 The underlying message transport is unable to process the
144 --------------------------------------------------------------------------------------------
148 --------------------------------------------------------------------------------------------
150 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
151 rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3),
152 rmr_payload_size(3), rmr_send_msg(3), rmr_torcv_msg(3),
153 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
154 rmr_ring_free(3), rmr_torcv_msg(3)