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_wh_call( void* vctx, rmr_whid_t whid, rmr_mbuf_t* msg, int call_id, int max_wait )
35 --------------------------------------------------------------------------------------------
37 The rmr_wh_call function accepts a message buffer (msg) from
38 the user application and attempts to send it using the
39 wormhole ID provided (whid). If the send is successful, the
40 call will block until either a response message is received,
41 or the max_wait number of milliseconds has passed. In order
42 for the response to be recognised as a response, the remote
43 process **must** use rmr_rts_msg() to send their response.
45 Like *rmr_wh_send_msg,* this function attempts to send the
46 message directly to a process at the other end of a wormhole
47 which was created with *rmr_wh_open().* When sending message
48 via wormholes, the normal RMR routing based on message type
49 is ignored, and the caller may leave the message type
50 unspecified in the message buffer (unless it is needed by the
51 receiving process). The call_id parameter is a number in the
52 range of 2 through 255 and is used to identify the calling
53 thread in order to properly match a response message when it
54 arrives. Providing this value, and ensuring the proper
55 uniqueness, is the responsibility of the user application and
56 as such the ability to use the rmr_wh_call() function from
57 potentially non-threaded concurrent applications (such as
58 Go's goroutines) is possible.
61 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
63 The send operations in RMR will retry *soft* send failures
64 until one of three conditions occurs:
70 The message is sent without error
75 The underlying transport reports a *hard* failure
80 The maximum number of retry loops has been attempted
83 A retry loop consists of approximately 1000 send attempts
84 **without** any intervening calls to *sleep()* or *usleep().*
85 The number of retry loops defaults to 1, thus a maximum of
86 1000 send attempts is performed before returning to the user
87 application. This value can be set at any point after RMR
88 initialisation using the *rmr_set_stimeout()* function
89 allowing the user application to completely disable retires
90 (set to 0), or to increase the number of retry loops.
92 Transport Level Blocking
93 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
95 The underlying transport mechanism used to send messages is
96 configured in *non-blocking* mode. This means that if a
97 message cannot be sent immediately the transport mechanism
98 will **not** pause with the assumption that the inability to
99 send will clear quickly (within a few milliseconds). This
100 means that when the retry loop is completely disabled (set to
101 0), that the failure to accept a message for sending by the
102 underlying mechanisms (software or hardware) will be reported
103 immediately to the user application.
105 It should be noted that depending on the underlying transport
106 mechanism being used, it is extremely likely that retry
107 conditions will happen during normal operations. These are
108 completely out of RMR's control, and there is nothing that
109 RMR can do to avoid or mitigate these other than by allowing
110 RMR to retry the send operation, and even then it is possible
111 (e.g., during connection reattempts), that a single retry
112 loop is not enough to guarantee a successful send.
115 --------------------------------------------------------------------------------------------
117 On success, new message buffer, with the payload containing
118 the response from the remote endpoint is returned. The state
119 in this buffer will reflect the overall send operation state
120 and should be RMR_OK.
122 If a message is returned with a state which is anything other
123 than RMR_OK, the indication is that the send was not
124 successful. The user application must check the state and
125 determine the course of action. If the return value is NULL,
126 no message, the indication is that there was no response
127 received within the timeout (max_wait) period of time.
130 --------------------------------------------------------------------------------------------
132 The following values may be passed back in the *state* field
133 of the returned message buffer.
139 The wormhole ID passed in was not associated with an open
140 wormhole, or was out of range for a valid ID.
144 No wormholes exist, further attempt to validate the ID are
149 The message buffer pointer did not refer to a valid
154 The header in the message buffer was not valid or
159 --------------------------------------------------------------------------------------------
161 The following is a simple example of how the a wormhole is
162 created (rmr_wh_open) and then how rmr_wh_send_msg function
163 is used to send messages. Some error checking is omitted for
169 #include <rmr/rmr.h> // system headers omitted for clarity
171 rmr_whid_t whid = -1; // wormhole id for sending
172 void* mrc; //msg router context
174 rmr_mbuf_t* sbuf; // send buffer
176 int norm_msg_size = 1500; // most messages fit in this size
177 mrc = rmr_init( "43086", norm_msg_size, RMRFL_NONE );
179 fprintf( stderr, "[FAIL] unable to initialise RMR environment\\n" );
182 while( ! rmr_ready( mrc ) ) { // wait for routing table info
185 sbuf = rmr_alloc_msg( mrc, 2048 );
188 whid = rmr_wh_open( mrc, "localhost:6123" ); // open fails if endpoint refuses conn
189 if( RMR_WH_CONNECTED( wh ) ) {
190 snprintf( sbuf->payload, 1024, "periodic update from sender: %d", count++ );
191 sbuf->len = strlen( sbuf->payload );
192 sbuf = rmr_wh_call( mrc, whid, sbuf, 1000 ); // expect a response in 1s or less
193 if( sbuf != NULL && sbuf->state = RMR_OK ) {
194 sprintf( stderr, "response: %s\\n", sbuf->payload ); // assume they sent a string
196 sprintf( stderr, "response not received, or send error\\n" );
207 --------------------------------------------------------------------------------------------
209 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
210 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
211 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
212 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
213 rmr_set_stimeout(3), rmr_wh_open(3), rmr_wh_close(3),