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 ============================================================================================
11 Man Page: rmr_send_msg
12 ============================================================================================
15 ============================================================================================
19 --------------------------------------------------------------------------------------------
24 --------------------------------------------------------------------------------------------
30 rmr_mbuf_t* rmr_send_msg( void* vctx, rmr_mbuf_t* msg );
35 --------------------------------------------------------------------------------------------
37 The rmr_send_msg function accepts a message buffer from the
38 user application and attempts to send it. The destination of
39 the message is selected based on the message type specified
40 in the message buffer, and the matching information in the
41 routing tables which are currently in use by the RMR library.
42 This may actually result in the sending of the message to
43 multiple destinations which could degrade expected overall
44 performance of the user application. (Limiting excessive
45 sending of messages is the responsibility of the
46 application(s) responsible for building the routing table
47 used by the RMR library, and not the responsibility of the
51 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
53 The send operations in RMR will retry *soft* send failures
54 until one of three conditions occurs:
60 The message is sent without error
65 The underlying transport reports a *hard* failure
70 The maximum number of retry loops has been attempted
73 A retry loop consists of approximately 1000 send attempts
74 **without** any intervening calls to *sleep()* or *usleep().*
75 The number of retry loops defaults to 1, thus a maximum of
76 1000 send attempts is performed before returning to the user
77 application. This value can be set at any point after RMR
78 initialisation using the *rmr_set_stimeout()* function
79 allowing the user application to completely disable retires
80 (set to 0), or to increase the number of retry loops.
82 Transport Level Blocking
83 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
85 The underlying transport mechanism used to send messages is
86 configured in *non-blocking* mode. This means that if a
87 message cannot be sent immediately the transport mechanism
88 will **not** pause with the assumption that the inability to
89 send will clear quickly (within a few milliseconds). This
90 means that when the retry loop is completely disabled (set to
91 0), that the failure to accept a message for sending by the
92 underlying mechanisms (software or hardware) will be reported
93 immediately to the user application.
95 It should be noted that depending on the underlying transport
96 mechanism being used, it is extremely likely that retry
97 conditions will happen during normal operations. These are
98 completely out of RMR's control, and there is nothing that
99 RMR can do to avoid or mitigate these other than by allowing
100 RMR to retry the send operation, and even then it is possible
101 (e.g., during connection reattempts), that a single retry
102 loop is not enough to guarantee a successful send.
105 --------------------------------------------------------------------------------------------
107 On success, a new message buffer, with an empty payload, is
108 returned for the application to use for the next send. The
109 state in this buffer will reflect the overall send operation
110 state and will be RMR_OK when the send was successful.
112 When the message cannot be successfully sent this function
113 will return the unsent (original) message buffer with the
114 state set to indicate the reason for failure. The value of
115 *errno* may also be set to reflect a more detailed failure
116 reason if it is known.
118 In the event of extreme failure, a nil pointer is returned.
119 In this case the value of errno might be of some use, for
120 documentation, but there will be little that the user
121 application can do other than to move on.
123 **CAUTION:** In some cases it is extremely likely that the
124 message returned by the send function does **not** reference
125 the same memory structure. Thus is important for the user
126 programme to capture the new pointer for future use or to be
127 passed to rmr_free(). If you are experiencing either double
128 free errors or segment faults in either rmr_free() or
129 rmr_send_msg(), ensure that the return value from this
130 function is being captured and used.
133 --------------------------------------------------------------------------------------------
135 The following values may be passed back in the *state* field
136 of the returned message buffer.
142 The message could not be sent, but the underlying
143 transport mechanism indicates that the failure is
144 temporary. If the send operation is tried again it might
149 The send operation was not successful and the underlying
150 transport mechanism indicates a permanent (hard) failure;
151 retrying the send is not possible.
155 The message buffer pointer did not refer to a valid
160 The header in the message buffer was not valid or
165 The message type in the message buffer did not map to a
169 The following values may be assigned to errno on failure.
174 Parameter(s) passed to the function were not valid, or the
175 underlying message processing environment was unable to
176 interpret the message.
181 The header information in the message buffer was invalid.
186 No known endpoint for the message could be found.
191 The underlying transport refused to accept the message
192 because of a size value issue (message was not attempted
198 The message referenced by the message buffer is corrupt
199 (nil pointer or bad internal length).
204 Internal RMR error; information provided to the message
205 transport environment was not valid.
210 Sending was not supported by the underlying message
216 The device is not in a state that can accept the message.
221 The device is not able to accept a message for sending.
222 The user application should attempt to resend.
227 The operation was interrupted by delivery of a signal
228 before the message was sent.
233 The underlying message environment timed out during the
239 The underlying message environment is in a shutdown state.
243 --------------------------------------------------------------------------------------------
245 The following is a simple example of how the rmr_send_msg
246 function is called. In this example, the send message buffer
247 is saved between calls and reused eliminating alloc/free
253 static rmr_mbuf_t* send_msg = NULL; // message to send; reused on each call
254 msg_t* send_pm; // payload for send
255 msg_t* pm; // our message format in the received payload
256 if( send_msg == NULL ) {
257 send_msg = rmr_alloc_msg( mr, MAX_SIZE ); // new buffer to send
259 // reference payload and fill in message type
260 pm = (msg_t*) send_msg->payload;
261 send_msg->mtype = MT_ANSWER;
262 msg->len = generate_data( pm ); // something that fills the payload in
263 msg = rmr_send_msg( mr, send_msg ); // ensure new pointer used after send
267 if( msg->state != RMR_OK ) {
268 // check for RMR_ERR_RETRY, and resend if needed
277 --------------------------------------------------------------------------------------------
279 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
280 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
281 rmr_rts_msg(3), rmr_ready(3), rmr_mk_ring(3),
282 rmr_ring_free(3), rmr_torcv_rcv(3), rmr_wh_send_msg(3)