docs/rmr_wh_send_msg.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_send_msg
  12 ============================================================================================
  13
  14 RMR Library Functions
  15 ============================================================================================
  16
  17
  18 NAME
  19 --------------------------------------------------------------------------------------------
  20
  21 rmr_wh_send_msg
  22
  23 SYNOPSIS
  24 --------------------------------------------------------------------------------------------
  25
  26
  27 ::
  28
  29  #include <rmr/rmr.h>
  30  rmr_mbuf_t* rmr_wh_send_msg( void* vctx, rmr_whid_t id, rmr_mbuf_t* msg );
  31
  32
  33
  34 DESCRIPTION
  35 --------------------------------------------------------------------------------------------
  36
  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).
  46
  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.
  51
  52 Retries
  53 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  54
  55 The send operations in RMR will retry *soft* send failures
  56 until one of three conditions occurs:
  57
  58
  59
  60 1.
  61
  62   The message is sent without error
  63
  64
  65 2.
  66
  67   The underlying transport reports a *hard* failure
  68
  69
  70 3.
  71
  72   The maximum number of retry loops has been attempted
  73
  74
  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.
  83
  84 Transport Level Blocking
  85 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  86
  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.
  96
  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.
 105
 106 RETURN VALUE
 107 --------------------------------------------------------------------------------------------
 108
 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.
 113
 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.
 118
 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.
 123
 124 ERRORS
 125 --------------------------------------------------------------------------------------------
 126
 127 The following values may be passed back in the *state* field
 128 of the returned message buffer.
 129
 130
 131
 132 RMR_ERR_WHID
 133
 134   The wormhole ID passed in was not associated with an open
 135   wormhole, or was out of range for a valid ID.
 136
 137 RMR_ERR_NOWHOPEN
 138
 139   No wormholes exist, further attempt to validate the ID are
 140   skipped.
 141
 142 RMR_ERR_BADARG
 143
 144   The message buffer pointer did not refer to a valid
 145   message.
 146
 147 RMR_ERR_NOHDR
 148
 149   The header in the message buffer was not valid or
 150   corrupted.
 151
 152
 153 The following values may be assigned to errno on failure.
 154
 155
 156 INVAL
 157
 158   Parameter(s) passed to the function were not valid, or the
 159   underlying message processing environment was unable to
 160   interpret the message.
 161
 162
 163 ENOKEY
 164
 165   The header information in the message buffer was invalid.
 166
 167
 168 ENXIO
 169
 170   No known endpoint for the message could be found.
 171
 172
 173 EMSGSIZE
 174
 175   The underlying transport refused to accept the message
 176   because of a size value issue (message was not attempted
 177   to be sent).
 178
 179
 180 EFAULT
 181
 182   The message referenced by the message buffer is corrupt
 183   (nil pointer or bad internal length).
 184
 185
 186 EBADF
 187
 188   Internal RMR error; information provided to the message
 189   transport environment was not valid.
 190
 191
 192 ENOTSUP
 193
 194   Sending was not supported by the underlying message
 195   transport.
 196
 197
 198 EFSM
 199
 200   The device is not in a state that can accept the message.
 201
 202
 203 EAGAIN
 204
 205   The device is not able to accept a message for sending.
 206   The user application should attempt to resend.
 207
 208
 209 EINTR
 210
 211   The operation was interrupted by delivery of a signal
 212   before the message was sent.
 213
 214
 215 ETIMEDOUT
 216
 217   The underlying message environment timed out during the
 218   send process.
 219
 220
 221 ETERM
 222
 223   The underlying message environment is in a shutdown state.
 224
 225
 226 EXAMPLE
 227 --------------------------------------------------------------------------------------------
 228
 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
 232 clarity.
 233
 234
 235 ::
 236
 237  #include <rmr/rmr.h>    // system headers omitted for clarity
 238  int main() {
 239     rmr_whid_t whid = -1;   // wormhole id for sending
 240     void* mrc;      //msg router context
 241          int i;
 242     rmr_mbuf_t*  sbuf;      // send buffer
 243     int     count = 0;
 244     int     norm_msg_size = 1500;  // most msg fit in this size
 245     mrc = rmr_init( "43086", norm_msg_size, RMRFL_NONE );
 246     if( mrc == NULL ) {
 247        fprintf( stderr, "[FAIL] unable to initialise RMR environment\\n" );
 248        exit( 1 );
 249     }
 250     while( ! rmr_ready( mrc ) ) {        // wait for routing table info
 251        sleep( 1 );
 252     }
 253     sbuf = rmr_alloc_msg( mrc, 2048 );
 254     while( 1 ) {
 255       if( whid < 0 ) {
 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 );
 261          }
 262       }
 263       sleep( 5 );
 264     }
 265  }
 266
 267
 268
 269 SEE ALSO
 270 --------------------------------------------------------------------------------------------
 271
 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),
 277 rmr_wh_state(3)