docs/rmr_wh_send_msg.3.rst

   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.
   6
   7 ============================================================================================
   8 Man Page: rmr_wh_send_msg
   9 ============================================================================================
  10
  11
  12
  13
  14 RMR LIBRARY FUNCTIONS
  15 =====================
  16
  17
  18
  19 NAME
  20 ----
  21
  22 rmr_wh_send_msg
  23
  24
  25 SYNOPSIS
  26 --------
  27
  28
  29 ::
  30
  31  #include <rmr/rmr.h>
  32
  33  rmr_mbuf_t* rmr_wh_send_msg( void* vctx, rmr_whid_t id, rmr_mbuf_t* msg );
  34
  35
  36
  37 DESCRIPTION
  38 -----------
  39
  40 The ``rmr_wh_send_msg`` function accepts a message buffer
  41 from the user application and attempts to send it using the
  42 wormhole ID provided (id). Unlike *rmr_send_msg,* this
  43 function attempts to send the message directly to a process
  44 at the other end of a wormhole which was created with
  45 *rmr_wh_open().* When sending message via wormholes, the
  46 normal RMR routing based on message type is ignored, and the
  47 caller may leave the message type unspecified in the message
  48 buffer (unless it is needed by the receiving process).
  49
  50 The message buffer (msg) used to send is the same format as
  51 used for regular RMR send and reply to sender operations,
  52 thus any buffer allocated by these means, or calls to
  53 *rmr_rcv_msg()* can be passed to this function.
  54
  55
  56 Retries
  57 -------
  58
  59 The send operations in RMR will retry *soft* send failures
  60 until one of three conditions occurs:
  61
  62
  63  &item The message is sent without error
  64
  65  &item The underlying transport reports a *hard* failure
  66
  67  &item The maximum number of retry loops has been attempted
  68
  69
  70 A retry loop consists of approximately 1000 send attempts
  71 **without** any intervening calls to *sleep()* or *usleep().*
  72 The number of retry loops defaults to 1, thus a maximum of
  73 1000 send attempts is performed before returning to the user
  74 application. This value can be set at any point after RMR
  75 initialisation using the *rmr_set_stimeout()* function
  76 allowing the user application to completely disable retires
  77 (set to 0), or to increase the number of retry loops.
  78
  79
  80 Transport Level Blocking
  81 ------------------------
  82
  83 The underlying transport mechanism used to send messages is
  84 configured in *non-blocking* mode. This means that if a
  85 message cannot be sent immediately the transport mechanism
  86 will **not** pause with the assumption that the inability to
  87 send will clear quickly (within a few milliseconds). This
  88 means that when the retry loop is completely disabled (set to
  89 0), that the failure to accept a message for sending by the
  90 underlying mechanisms (software or hardware) will be reported
  91 immediately to the user application.
  92
  93 It should be noted that depending on the underlying transport
  94 mechanism being used, it is extremely likely that retry
  95 conditions will happen during normal operations. These are
  96 completely out of RMR's control, and there is nothing that
  97 RMR can do to avoid or mitigate these other than by allowing
  98 RMR to retry the send operation, and even then it is possible
  99 (e.g., during connection reattempts), that a single retry
 100 loop is not enough to guarantee a successful send.
 101
 102
 103 RETURN VALUE
 104 ------------
 105
 106 On success, a new message buffer, with an empty payload, is
 107 returned for the application to use for the next send. The
 108 state in this buffer will reflect the overall send operation
 109 state and should be ``RMR_OK.``
 110
 111 If the state in the returned buffer is anything other than
 112 ``RMR_OK,`` the user application may need to attempt a
 113 retransmission of the message, or take other action depending
 114 on the setting of ``errno`` as described below.
 115
 116 In the event of extreme failure, a nil pointer is returned.
 117 In this case the value of ``errno`` might be of some use, for
 118 documentation, but there will be little that the user
 119 application can do other than to move on.
 120
 121
 122 ERRORS
 123 ------
 124
 125 The following values may be passed back in the *state* field
 126 of the returned message buffer.
 127
 128
 129    .. list-table::
 130      :widths: auto
 131      :header-rows: 0
 132      :class: borderless
 133
 134      * - **RMR_ERR_WHID**
 135        -
 136          The wormhole ID passed in was not associated with an open
 137          wormhole, or was out of range for a valid ID.
 138
 139      * - **RMR_ERR_NOWHOPEN**
 140        -
 141          No wormholes exist, further attempt to validate the ID are
 142          skipped.
 143
 144      * - **RMR_ERR_BADARG**
 145        -
 146          The message buffer pointer did not refer to a valid message.
 147
 148      * - **RMR_ERR_NOHDR**
 149        -
 150          The header in the message buffer was not valid or corrupted.
 151
 152
 153
 154 The following values may be assigned to ``errno`` on failure.
 155
 156    .. list-table::
 157      :widths: auto
 158      :header-rows: 0
 159      :class: borderless
 160
 161      * - **INVAL**
 162        -
 163          Parameter(s) passed to the function were not valid, or the
 164          underlying message processing environment was unable to
 165          interpret the message.
 166
 167      * - **ENOKEY**
 168        -
 169          The header information in the message buffer was invalid.
 170
 171      * - **ENXIO**
 172        -
 173          No known endpoint for the message could be found.
 174
 175      * - **EMSGSIZE**
 176        -
 177          The underlying transport refused to accept the message
 178          because of a size value issue (message was not attempted to
 179          be sent).
 180
 181      * - **EFAULT**
 182        -
 183          The message referenced by the message buffer is corrupt (nil
 184          pointer or bad internal length).
 185
 186      * - **EBADF**
 187        -
 188          Internal RMR error; information provided to the message
 189          transport environment was not valid.
 190
 191      * - **ENOTSUP**
 192        -
 193          Sending was not supported by the underlying message
 194          transport.
 195
 196      * - **EFSM**
 197        -
 198          The device is not in a state that can accept the message.
 199
 200      * - **EAGAIN**
 201        -
 202          The device is not able to accept a message for sending. The
 203          user application should attempt to resend.
 204
 205      * - **EINTR**
 206        -
 207          The operation was interrupted by delivery of a signal before
 208          the message was sent.
 209
 210      * - **ETIMEDOUT**
 211        -
 212          The underlying message environment timed out during the send
 213          process.
 214
 215      * - **ETERM**
 216        -
 217          The underlying message environment is in a shutdown state.
 218
 219
 220
 221
 222 EXAMPLE
 223 -------
 224
 225 The following is a simple example of how the a wormhole is
 226 created (rmr_wh_open) and then how ``rmr_wh_send_msg``
 227 function is used to send messages. Some error checking is
 228 omitted for clarity.
 229
 230
 231 ::
 232
 233
 234  #include <rmr/rmr.h>    // system headers omitted for clarity
 235
 236  int main() {
 237     rmr_whid_t whid = -1;   // wormhole id for sending
 238     void* mrc;      //msg router context
 239          int i;
 240     rmr_mbuf_t*  sbuf;      // send buffer
 241     int     count = 0;
 242     int     norm_msg_size = 1500;  // most msg fit in this size
 243
 244     mrc = rmr_init( "43086", norm_msg_size, RMRFL_NONE );
 245     if( mrc == NULL ) {
 246        fprintf( stderr, "[FAIL] unable to initialise RMR environment\\n" );
 247        exit( 1 );
 248     }
 249
 250     while( ! rmr_ready( mrc ) ) {        // wait for routing table info
 251        sleep( 1 );
 252     }
 253
 254     sbuf = rmr_alloc_msg( mrc, 2048 );
 255
 256     while( 1 ) {
 257       if( whid < 0 ) {
 258         whid = rmr_wh_open( mrc, "localhost:6123" );  // open fails if endpoint refuses conn
 259            if( RMR_WH_CONNECTED( wh ) ) {
 260             snprintf( sbuf->payload, 1024, "periodic update from sender: %d", count++ );
 261             sbuf->len =  strlen( sbuf->payload );
 262             sbuf = rmr_wh_send_msg( mrc, whid, sbuf );
 263          }
 264       }
 265
 266       sleep( 5 );
 267     }
 268  }
 269
 270
 271
 272 SEE ALSO
 273 --------
 274
 275 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
 276 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
 277 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
 278 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
 279 rmr_set_stimeout(3), rmr_wh_open(3), rmr_wh_close(3),
 280 rmr_wh_state(3)