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