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_wh_send_msg
12 ============================================================================================
15 ============================================================================================
19 --------------------------------------------------------------------------------------------
24 --------------------------------------------------------------------------------------------
30 rmr_mbuf_t* rmr_wh_send_msg( void* vctx, rmr_whid_t id, rmr_mbuf_t* msg );
35 --------------------------------------------------------------------------------------------
37 The rmr_wh_send_msg function accepts a message buffer from
38 the user application and attempts to send it using the
39 wormhole ID provided (id). Unlike *rmr_send_msg,* this
40 function attempts to send the message directly to a process
41 at the other end of a wormhole which was created with
42 *rmr_wh_open().* When sending message via wormholes, the
43 normal RMR routing based on message type is ignored, and the
44 caller may leave the message type unspecified in the message
45 buffer (unless it is needed by the receiving process).
47 The message buffer (msg) used to send is the same format as
48 used for regular RMR send and reply to sender operations,
49 thus any buffer allocated by these means, or calls to
50 *rmr_rcv_msg()* can be passed to this function.
53 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
55 The send operations in RMR will retry *soft* send failures
56 until one of three conditions occurs:
62 The message is sent without error
67 The underlying transport reports a *hard* failure
72 The maximum number of retry loops has been attempted
75 A retry loop consists of approximately 1000 send attempts
76 **without** any intervening calls to *sleep()* or *usleep().*
77 The number of retry loops defaults to 1, thus a maximum of
78 1000 send attempts is performed before returning to the user
79 application. This value can be set at any point after RMr
80 initialisation using the *rmr_set_stimeout()* function
81 allowing the user application to completely disable retires
82 (set to 0), or to increase the number of retry loops.
84 Transport Level Blocking
85 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
87 The underlying transport mechanism used to send messages is
88 configured in *non-blocking* mode. This means that if a
89 message cannot be sent immediately the transport mechanism
90 will **not** pause with the assumption that the inability to
91 send will clear quickly (within a few milliseconds). This
92 means that when the retry loop is completely disabled (set to
93 0), that the failure to accept a message for sending by the
94 underlying mechanisms (software or hardware) will be reported
95 immediately to the user application.
97 It should be noted that depending on the underlying transport
98 mechanism being used, it is extremely likely that retry
99 conditions will happen during normal operations. These are
100 completely out of RMR's control, and there is nothing that
101 RMR can do to avoid or mitigate these other than by allowing
102 RMR to retry the send operation, and even then it is possible
103 (e.g., during connection reattempts), that a single retry
104 loop is not enough to guarantee a successful send.
107 --------------------------------------------------------------------------------------------
109 On success, a new message buffer, with an empty payload, is
110 returned for the application to use for the next send. The
111 state in this buffer will reflect the overall send operation
112 state and should be RMR_OK.
114 If the state in the returned buffer is anything other than
115 RMR_OK, the user application may need to attempt a
116 retransmission of the message, or take other action depending
117 on the setting of errno as described below.
119 In the event of extreme failure, a nil pointer is returned.
120 In this case the value of errno might be of some use, for
121 documentation, but there will be little that the user
122 application can do other than to move on.
125 --------------------------------------------------------------------------------------------
127 The following values may be passed back in the *state* field
128 of the returned message buffer.
134 The wormhole ID passed in was not associated with an open
135 wormhole, or was out of range for a valid ID.
139 No wormholes exist, further attempt to validate the ID are
144 The message buffer pointer did not refer to a valid
149 The header in the message buffer was not valid or
153 The following values may be assigned to errno on failure.
158 Parameter(s) passed to the function were not valid, or the
159 underlying message processing environment was unable to
160 interpret the message.
165 The header information in the message buffer was invalid.
170 No known endpoint for the message could be found.
175 The underlying transport refused to accept the message
176 because of a size value issue (message was not attempted
182 The message referenced by the message buffer is corrupt
183 (nil pointer or bad internal length).
188 Internal RMR error; information provided to the message
189 transport environment was not valid.
194 Sending was not supported by the underlying message
200 The device is not in a state that can accept the message.
205 The device is not able to accept a message for sending.
206 The user application should attempt to resend.
211 The operation was interrupted by delivery of a signal
212 before the message was sent.
217 The underlying message environment timed out during the
223 The underlying message environment is in a shutdown state.
227 --------------------------------------------------------------------------------------------
229 The following is a simple example of how the a wormhole is
230 created (rmr_wh_open) and then how rmr_wh_send_msg function
231 is used to send messages. Some error checking is omitted for
237 #include <rmr/rmr.h> // system headers omitted for clarity
239 rmr_whid_t whid = -1; // wormhole id for sending
240 void* mrc; //msg router context
242 rmr_mbuf_t* sbuf; // send buffer
244 int norm_msg_size = 1500; // most msg fit in this size
245 mrc = rmr_init( "43086", norm_msg_size, RMRFL_NONE );
247 fprintf( stderr, "[FAIL] unable to initialise RMR environment\\n" );
250 while( ! rmr_ready( mrc ) ) { // wait for routing table info
253 sbuf = rmr_alloc_msg( mrc, 2048 );
256 whid = rmr_wh_open( mrc, "localhost:6123" ); // open fails if endpoint refuses conn
257 if( RMR_WH_CONNECTED( wh ) ) {
258 snprintf( sbuf->payload, 1024, "periodic update from sender: %d", count++ );
259 sbuf->len = strlen( sbuf->payload );
260 sbuf = rmr_wh_send_msg( mrc, whid, sbuf );
270 --------------------------------------------------------------------------------------------
272 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
273 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
274 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
275 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
276 rmr_set_stimeout(3), rmr_wh_open(3), rmr_wh_close(3),