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_rts_msg( void* vctx, rmr_mbuf_t* msg );
35 --------------------------------------------------------------------------------------------
37 The rmr_rts_msg function sends a message returning it to the
38 endpoint which sent the message rather than selecting an
39 endpoint based on the message type and routing table. Other
40 than this small difference, the behaviour is exactly the same
44 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
46 The send operations in RMR will retry *soft* send failures
47 until one of three conditions occurs:
53 The message is sent without error
58 The underlying transport reports a *hard* failure
63 The maximum number of retry loops has been attempted
66 A retry loop consists of approximately 1000 send attempts
67 **without** any intervening calls to *sleep()* or *usleep().*
68 The number of retry loops defaults to 1, thus a maximum of
69 1000 send attempts is performed before returning to the user
70 application. This value can be set at any point after RMR
71 initialisation using the *rmr_set_stimeout()* function
72 allowing the user application to completely disable retires
73 (set to 0), or to increase the number of retry loops.
75 Transport Level Blocking
76 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
78 The underlying transport mechanism used to send messages is
79 configured in *non-blocking* mode. This means that if a
80 message cannot be sent immediately the transport mechanism
81 will **not** pause with the assumption that the inability to
82 send will clear quickly (within a few milliseconds). This
83 means that when the retry loop is completely disabled (set to
84 0), that the failure to accept a message for sending by the
85 underlying mechanisms (software or hardware) will be reported
86 immediately to the user application.
88 It should be noted that depending on the underlying transport
89 mechanism being used, it is extremely likely that retry
90 conditions will happen during normal operations. These are
91 completely out of RMR's control, and there is nothing that
92 RMR can do to avoid or mitigate these other than by allowing
93 RMR to retry the send operation, and even then it is possible
94 (e.g., during connection reattempts), that a single retry
95 loop is not enough to guarantee a successful send.
98 --------------------------------------------------------------------------------------------
100 When crafting a response based on a received message, the
101 user application must take care not to write more bytes to
102 the message payload than the allocated message has. In the
103 case of a received message, it is possible that the response
104 needs to be larger than the payload associated with the
105 inbound message. In order to use the return to sender
106 function, the source information in the original message must
107 be present in the response; information which cannot be added
108 to a message buffer allocated through the standard RMR
109 allocation function. To allocate a buffer with a larger
110 payload, and which retains the necessary sender data needed
111 by this function, the *rmr_realloc_payload()* function must
112 be used to extend the payload to a size suitable for the
116 --------------------------------------------------------------------------------------------
118 On success, a new message buffer, with an empty payload, is
119 returned for the application to use for the next send. The
120 state in this buffer will reflect the overall send operation
121 state and should be RMR_OK.
123 If the state in the returned buffer is anything other than
124 RMR_OK, the user application may need to attempt a
125 retransmission of the message, or take other action depending
126 on the setting of errno as described below.
128 In the event of extreme failure, a nil pointer is returned.
129 In this case the value of errno might be of some use, for
130 documentation, but there will be little that the user
131 application can do other than to move on.
134 --------------------------------------------------------------------------------------------
136 The following values may be passed back in the *state* field
137 of the returned message buffer.
143 The message buffer pointer did not refer to a valid
148 The header in the message buffer was not valid or
153 The message type in the message buffer did not map to a
158 The send failed; errno has the possible reason.
161 The following values may be assigned to errno on failure.
166 Parameter(s) passed to the function were not valid, or the
167 underlying message processing environment was unable to
168 interpret the message.
173 The header information in the message buffer was invalid.
178 No known endpoint for the message could be found.
183 The underlying transport refused to accept the message
184 because of a size value issue (message was not attempted
190 The message referenced by the message buffer is corrupt
191 (nil pointer or bad internal length).
196 Internal RMR error; information provided to the message
197 transport environment was not valid.
202 Sending was not supported by the underlying message
208 The device is not in a state that can accept the message.
213 The device is not able to accept a message for sending.
214 The user application should attempt to resend.
219 The operation was interrupted by delivery of a signal
220 before the message was sent.
225 The underlying message environment timed out during the
231 The underlying message environment is in a shutdown state.
235 --------------------------------------------------------------------------------------------
239 --------------------------------------------------------------------------------------------
241 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
242 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
243 rmr_rcv_specific(3), rmr_ready(3), rmr_fib(3),
244 rmr_has_str(3), rmr_set_stimeout(3), rmr_tokenise(3),
245 rmr_mk_ring(3), rmr_ring_free(3)