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_wh_call( void* vctx, rmr_whid_t whid, rmr_mbuf_t* msg, int call_id, int max_wait )
41 The ``rmr_wh_call`` function accepts a message buffer (msg)
42 from the user application and attempts to send it using the
43 wormhole ID provided (whid). If the send is successful, the
44 call will block until either a response message is received,
45 or the ``max_wait`` number of milliseconds has passed. In
46 order for the response to be recognised as a response, the
47 remote process **must** use ``rmr_rts_msg()`` to send their
50 Like *rmr_wh_send_msg,* this function attempts to send the
51 message directly to a process at the other end of a wormhole
52 which was created with *rmr_wh_open().* When sending message
53 via wormholes, the normal RMR routing based on message type
54 is ignored, and the caller may leave the message type
55 unspecified in the message buffer (unless it is needed by the
56 receiving process). The ``call_id`` parameter is a number in
57 the range of 2 through 255 and is used to identify the
58 calling thread in order to properly match a response message
59 when it arrives. Providing this value, and ensuring the
60 proper uniqueness, is the responsibility of the user
61 application and as such the ability to use the
62 ``rmr_wh_call()`` function from potentially non-threaded
63 concurrent applications (such as Go's goroutines) is
70 The send operations in RMR will retry *soft* send failures
71 until one of three conditions occurs:
74 * The message is sent without error
76 * The underlying transport reports a *hard* failure
78 * The maximum number of retry loops has been attempted
81 A retry loop consists of approximately 1000 send attempts
82 **without** any intervening calls to *sleep()* or *usleep().*
83 The number of retry loops defaults to 1, thus a maximum of
84 1000 send attempts is performed before returning to the user
85 application. This value can be set at any point after RMR
86 initialisation using the *rmr_set_stimeout()* function
87 allowing the user application to completely disable retires
88 (set to 0), or to increase the number of retry loops.
91 Transport Level Blocking
92 ------------------------
94 The underlying transport mechanism used to send messages is
95 configured in *non-blocking* mode. This means that if a
96 message cannot be sent immediately the transport mechanism
97 will **not** pause with the assumption that the inability to
98 send will clear quickly (within a few milliseconds). This
99 means that when the retry loop is completely disabled (set to
100 0), that the failure to accept a message for sending by the
101 underlying mechanisms (software or hardware) will be reported
102 immediately to the user application.
104 It should be noted that depending on the underlying transport
105 mechanism being used, it is extremely likely that retry
106 conditions will happen during normal operations. These are
107 completely out of RMR's control, and there is nothing that
108 RMR can do to avoid or mitigate these other than by allowing
109 RMR to retry the send operation, and even then it is possible
110 (e.g., during connection reattempts), that a single retry
111 loop is not enough to guarantee a successful send.
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.
133 The following values may be passed back in the *state* field
134 of the returned message buffer.
144 The wormhole ID passed in was not associated with an open
145 wormhole, or was out of range for a valid ID.
147 * - **RMR_ERR_NOWHOPEN**
149 No wormholes exist, further attempt to validate the ID are
152 * - **RMR_ERR_BADARG**
154 The message buffer pointer did not refer to a valid message.
156 * - **RMR_ERR_NOHDR**
158 The header in the message buffer was not valid or corrupted.
166 The following is a simple example of how the a wormhole is
167 created (rmr_wh_open) and then how ``rmr_wh_send_msg``
168 function is used to send messages. Some error checking is
175 #include <rmr/rmr.h> // system headers omitted for clarity
178 rmr_whid_t whid = -1; // wormhole id for sending
179 void* mrc; //msg router context
181 rmr_mbuf_t* sbuf; // send buffer
183 int norm_msg_size = 1500; // most messages fit in this size
185 mrc = rmr_init( "43086", norm_msg_size, RMRFL_NONE );
187 fprintf( stderr, "[FAIL] unable to initialise RMR environment\\n" );
191 while( ! rmr_ready( mrc ) ) { // wait for routing table info
195 sbuf = rmr_alloc_msg( mrc, 2048 );
199 whid = rmr_wh_open( mrc, "localhost:6123" ); // open fails if endpoint refuses conn
200 if( RMR_WH_CONNECTED( wh ) ) {
201 snprintf( sbuf->payload, 1024, "periodic update from sender: %d", count++ );
202 sbuf->len = strlen( sbuf->payload );
203 sbuf = rmr_wh_call( mrc, whid, sbuf, 1000 ); // expect a response in 1s or less
204 if( sbuf != NULL && sbuf->state = RMR_OK ) {
205 sprintf( stderr, "response: %s\\n", sbuf->payload ); // assume they sent a string
207 sprintf( stderr, "response not received, or send error\\n" );
221 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
222 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
223 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
224 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
225 rmr_set_stimeout(3), rmr_wh_open(3), rmr_wh_close(3),