docs/rmr_rts_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_rts_msg
   9 ============================================================================================
  10
  11
  12
  13
  14 RMR LIBRARY FUNCTIONS
  15 =====================
  16
  17
  18
  19 NAME
  20 ----
  21
  22 rmr_rts_msg
  23
  24
  25 SYNOPSIS
  26 --------
  27
  28
  29 ::
  30
  31  #include <rmr/rmr.h>
  32
  33  rmr_mbuf_t*  rmr_rts_msg( void* vctx, rmr_mbuf_t* msg );
  34
  35
  36
  37 DESCRIPTION
  38 -----------
  39
  40 The ``rmr_rts_msg`` function sends a message returning it to
  41 the endpoint which sent the message rather than selecting an
  42 endpoint based on the message type and routing table. Other
  43 than this small difference, the behaviour is exactly the same
  44 as ``rmr_send_msg.``
  45
  46
  47 Retries
  48 -------
  49
  50 The send operations in RMR will retry *soft* send failures
  51 until one of three conditions occurs:
  52
  53
  54  &item The message is sent without error
  55
  56  &item The underlying transport reports a *hard* failure
  57
  58  &item The maximum number of retry loops has been attempted
  59
  60
  61 A retry loop consists of approximately 1000 send attempts
  62 **without** any intervening calls to *sleep()* or *usleep().*
  63 The number of retry loops defaults to 1, thus a maximum of
  64 1000 send attempts is performed before returning to the user
  65 application. This value can be set at any point after RMR
  66 initialisation using the *rmr_set_stimeout()* function
  67 allowing the user application to completely disable retires
  68 (set to 0), or to increase the number of retry loops.
  69
  70
  71 Transport Level Blocking
  72 ------------------------
  73
  74 The underlying transport mechanism used to send messages is
  75 configured in *non-blocking* mode. This means that if a
  76 message cannot be sent immediately the transport mechanism
  77 will **not** pause with the assumption that the inability to
  78 send will clear quickly (within a few milliseconds). This
  79 means that when the retry loop is completely disabled (set to
  80 0), that the failure to accept a message for sending by the
  81 underlying mechanisms (software or hardware) will be reported
  82 immediately to the user application.
  83
  84 It should be noted that depending on the underlying transport
  85 mechanism being used, it is extremely likely that retry
  86 conditions will happen during normal operations. These are
  87 completely out of RMR's control, and there is nothing that
  88 RMR can do to avoid or mitigate these other than by allowing
  89 RMR to retry the send operation, and even then it is possible
  90 (e.g., during connection reattempts), that a single retry
  91 loop is not enough to guarantee a successful send.
  92
  93
  94 PAYLOAD SIZE
  95 ------------
  96
  97 When crafting a response based on a received message, the
  98 user application must take care not to write more bytes to
  99 the message payload than the allocated message has. In the
 100 case of a received message, it is possible that the response
 101 needs to be larger than the payload associated with the
 102 inbound message. In order to use the return to sender
 103 function, the source information in the original message must
 104 be present in the response; information which cannot be added
 105 to a message buffer allocated through the standard RMR
 106 allocation function. To allocate a buffer with a larger
 107 payload, and which retains the necessary sender data needed
 108 by this function, the *rmr_realloc_payload()* function must
 109 be used to extend the payload to a size suitable for the
 110 response.
 111
 112
 113 RETURN VALUE
 114 ------------
 115
 116 On success, a new message buffer, with an empty payload, is
 117 returned for the application to use for the next send. The
 118 state in this buffer will reflect the overall send operation
 119 state and should be ``RMR_OK.``
 120
 121 If the state in the returned buffer is anything other than
 122 ``RMR_OK,`` the user application may need to attempt a
 123 retransmission of the message, or take other action depending
 124 on the setting of ``errno`` as described below.
 125
 126 In the event of extreme failure, a nil pointer is returned.
 127 In this case the value of ``errno`` might be of some use, for
 128 documentation, but there will be little that the user
 129 application can do other than to move on.
 130
 131
 132 ERRORS
 133 ------
 134
 135 The following values may be passed back in the *state* field
 136 of the returned message buffer.
 137
 138
 139    .. list-table::
 140      :widths: auto
 141      :header-rows: 0
 142      :class: borderless
 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      * - **RMR_ERR_NOENDPT**
 153        -
 154          The message type in the message buffer did not map to a known
 155          endpoint.
 156
 157      * - **RMR_ERR_SENDFAILED**
 158        -
 159          The send failed; ``errno`` has the possible reason.
 160
 161
 162
 163 The following values may be assigned to ``errno`` on failure.
 164
 165    .. list-table::
 166      :widths: auto
 167      :header-rows: 0
 168      :class: borderless
 169
 170      * - **INVAL**
 171        -
 172          Parameter(s) passed to the function were not valid, or the
 173          underlying message processing environment was unable to
 174          interpret the message.
 175
 176      * - **ENOKEY**
 177        -
 178          The header information in the message buffer was invalid.
 179
 180      * - **ENXIO**
 181        -
 182          No known endpoint for the message could be found.
 183
 184      * - **EMSGSIZE**
 185        -
 186          The underlying transport refused to accept the message
 187          because of a size value issue (message was not attempted to
 188          be sent).
 189
 190      * - **EFAULT**
 191        -
 192          The message referenced by the message buffer is corrupt (nil
 193          pointer or bad internal length).
 194
 195      * - **EBADF**
 196        -
 197          Internal RMR error; information provided to the message
 198          transport environment was not valid.
 199
 200      * - **ENOTSUP**
 201        -
 202          Sending was not supported by the underlying message
 203          transport.
 204
 205      * - **EFSM**
 206        -
 207          The device is not in a state that can accept the message.
 208
 209      * - **EAGAIN**
 210        -
 211          The device is not able to accept a message for sending. The
 212          user application should attempt to resend.
 213
 214      * - **EINTR**
 215        -
 216          The operation was interrupted by delivery of a signal before
 217          the message was sent.
 218
 219      * - **ETIMEDOUT**
 220        -
 221          The underlying message environment timed out during the send
 222          process.
 223
 224      * - **ETERM**
 225        -
 226          The underlying message environment is in a shutdown state.
 227
 228
 229
 230
 231 EXAMPLE
 232 -------
 233
 234
 235
 236 SEE ALSO
 237 --------
 238
 239 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
 240 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
 241 rmr_rcv_specific(3), rmr_ready(3), rmr_fib(3),
 242 rmr_has_str(3), rmr_set_stimeout(3), rmr_tokenise(3),
 243 rmr_mk_ring(3), rmr_ring_free(3)