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_rts_msg( void* vctx, rmr_mbuf_t* msg );
40 The ``rmr_rts_msg`` function sends a message returning it to
41 the endpoint which sent the message rather than selecting an
42 endpoint based on the message type and routing table. Other
43 than this small difference, the behaviour is exactly the same
50 The send operations in RMR will retry *soft* send failures
51 until one of three conditions occurs:
54 * The message is sent without error
56 * The underlying transport reports a *hard* failure
58 * The maximum number of retry loops has been attempted
61 A retry loop consists of approximately 1000 send attempts
62 **without** any intervening calls to *sleep()* or *usleep().*
63 The number of retry loops defaults to 1, thus a maximum of
64 1000 send attempts is performed before returning to the user
65 application. This value can be set at any point after RMR
66 initialisation using the *rmr_set_stimeout()* function
67 allowing the user application to completely disable retires
68 (set to 0), or to increase the number of retry loops.
71 Transport Level Blocking
72 ------------------------
74 The underlying transport mechanism used to send messages is
75 configured in *non-blocking* mode. This means that if a
76 message cannot be sent immediately the transport mechanism
77 will **not** pause with the assumption that the inability to
78 send will clear quickly (within a few milliseconds). This
79 means that when the retry loop is completely disabled (set to
80 0), that the failure to accept a message for sending by the
81 underlying mechanisms (software or hardware) will be reported
82 immediately to the user application.
84 It should be noted that depending on the underlying transport
85 mechanism being used, it is extremely likely that retry
86 conditions will happen during normal operations. These are
87 completely out of RMR's control, and there is nothing that
88 RMR can do to avoid or mitigate these other than by allowing
89 RMR to retry the send operation, and even then it is possible
90 (e.g., during connection reattempts), that a single retry
91 loop is not enough to guarantee a successful send.
97 When crafting a response based on a received message, the
98 user application must take care not to write more bytes to
99 the message payload than the allocated message has. In the
100 case of a received message, it is possible that the response
101 needs to be larger than the payload associated with the
102 inbound message. In order to use the return to sender
103 function, the source information in the original message must
104 be present in the response; information which cannot be added
105 to a message buffer allocated through the standard RMR
106 allocation function. To allocate a buffer with a larger
107 payload, and which retains the necessary sender data needed
108 by this function, the *rmr_realloc_payload()* function must
109 be used to extend the payload to a size suitable for the
116 On success, a new message buffer, with an empty payload, is
117 returned for the application to use for the next send. The
118 state in this buffer will reflect the overall send operation
119 state and should be ``RMR_OK.``
121 If the state in the returned buffer is anything other than
122 ``RMR_OK,`` the user application may need to attempt a
123 retransmission of the message, or take other action depending
124 on the setting of ``errno`` as described below.
126 In the event of extreme failure, a nil pointer is returned.
127 In this case the value of ``errno`` might be of some use, for
128 documentation, but there will be little that the user
129 application can do other than to move on.
135 The following values may be passed back in the *state* field
136 of the returned message buffer.
144 * - **RMR_ERR_BADARG**
146 The message buffer pointer did not refer to a valid message.
148 * - **RMR_ERR_NOHDR**
150 The header in the message buffer was not valid or corrupted.
152 * - **RMR_ERR_NOENDPT**
154 The message type in the message buffer did not map to a known
157 * - **RMR_ERR_SENDFAILED**
159 The send failed; ``errno`` has the possible reason.
163 The following values may be assigned to ``errno`` on failure.
172 Parameter(s) passed to the function were not valid, or the
173 underlying message processing environment was unable to
174 interpret the message.
178 The header information in the message buffer was invalid.
182 No known endpoint for the message could be found.
186 The underlying transport refused to accept the message
187 because of a size value issue (message was not attempted to
192 The message referenced by the message buffer is corrupt (nil
193 pointer or bad internal length).
197 Internal RMR error; information provided to the message
198 transport environment was not valid.
202 Sending was not supported by the underlying message
207 The device is not in a state that can accept the message.
211 The device is not able to accept a message for sending. The
212 user application should attempt to resend.
216 The operation was interrupted by delivery of a signal before
217 the message was sent.
221 The underlying message environment timed out during the send
226 The underlying message environment is in a shutdown state.
239 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
240 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
241 rmr_rcv_specific(3), rmr_ready(3), rmr_fib(3),
242 rmr_has_str(3), rmr_set_stimeout(3), rmr_tokenise(3),
243 rmr_mk_ring(3), rmr_ring_free(3)