docs/rmr_wh_call.3.rst

   1
   2
   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.
   8
   9
  10 ============================================================================================
  11 Man Page: rmr_wh_call
  12 ============================================================================================
  13
  14 RMR Library Functions
  15 ============================================================================================
  16
  17
  18 NAME
  19 --------------------------------------------------------------------------------------------
  20
  21 rmr_wh_call
  22
  23 SYNOPSIS
  24 --------------------------------------------------------------------------------------------
  25
  26
  27 ::
  28
  29  #include <rmr/rmr.h>
  30  rmr_mbuf_t* rmr_wh_call( void* vctx, rmr_whid_t whid, rmr_mbuf_t* msg, int call_id, int max_wait )
  31
  32
  33
  34 DESCRIPTION
  35 --------------------------------------------------------------------------------------------
  36
  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.
  44
  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.
  59
  60 Retries
  61 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  62
  63 The send operations in RMR will retry *soft* send failures
  64 until one of three conditions occurs:
  65
  66
  67
  68 1.
  69
  70   The message is sent without error
  71
  72
  73 2.
  74
  75   The underlying transport reports a *hard* failure
  76
  77
  78 3.
  79
  80   The maximum number of retry loops has been attempted
  81
  82
  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.
  91
  92 Transport Level Blocking
  93 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  94
  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.
 104
 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.
 113
 114 RETURN VALUE
 115 --------------------------------------------------------------------------------------------
 116
 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.
 121
 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.
 128
 129 ERRORS
 130 --------------------------------------------------------------------------------------------
 131
 132 The following values may be passed back in the *state* field
 133 of the returned message buffer.
 134
 135
 136
 137 RMR_ERR_WHID
 138
 139   The wormhole ID passed in was not associated with an open
 140   wormhole, or was out of range for a valid ID.
 141
 142 RMR_ERR_NOWHOPEN
 143
 144   No wormholes exist, further attempt to validate the ID are
 145   skipped.
 146
 147 RMR_ERR_BADARG
 148
 149   The message buffer pointer did not refer to a valid
 150   message.
 151
 152 RMR_ERR_NOHDR
 153
 154   The header in the message buffer was not valid or
 155   corrupted.
 156
 157
 158 EXAMPLE
 159 --------------------------------------------------------------------------------------------
 160
 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
 164 clarity.
 165
 166
 167 ::
 168
 169  #include <rmr/rmr.h>    // system headers omitted for clarity
 170  int main() {
 171     rmr_whid_t whid = -1;   // wormhole id for sending
 172     void* mrc;      //msg router context
 173          int i;
 174     rmr_mbuf_t*  sbuf;      // send buffer
 175     int     count = 0;
 176     int     norm_msg_size = 1500;    // most messages fit in this size
 177     mrc = rmr_init( "43086", norm_msg_size, RMRFL_NONE );
 178     if( mrc == NULL ) {
 179        fprintf( stderr, "[FAIL] unable to initialise RMR environment\\n" );
 180        exit( 1 );
 181     }
 182     while( ! rmr_ready( mrc ) ) {        // wait for routing table info
 183        sleep( 1 );
 184     }
 185     sbuf = rmr_alloc_msg( mrc, 2048 );
 186     while( 1 ) {
 187       if( whid < 0 ) {
 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
 195             } else {
 196               sprintf( stderr, "response not received, or send error\\n" );
 197             }
 198          }
 199        }
 200        sleep( 5 );
 201     }
 202  }
 203
 204
 205
 206 SEE ALSO
 207 --------------------------------------------------------------------------------------------
 208
 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),
 214 rmr_wh_state(3)