doc/src/man/retry.im

   1 .if false
   2 ==================================================================================
   3    Copyright (c) 2019 Nokia
   4    Copyright (c) 2018-2019 AT&T Intellectual Property.
   5
   6    Licensed under the Apache License, Version 2.0 (the "License");
   7    you may not use this file except in compliance with the License.
   8    You may obtain a copy of the License at
   9
  10        http://www.apache.org/licenses/LICENSE-2.0
  11
  12    Unless required by applicable law or agreed to in writing, software
  13    distributed under the License is distributed on an "AS IS" BASIS,
  14    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15    See the License for the specific language governing permissions and
  16    limitations under the License.
  17 ==================================================================================
  18 .fi
  19
  20 .if false
  21     Mnemonic: retry.im
  22     Abstract: Common text for all send operation functions. This should be imbedded by any
  23               function which will ultimately use the internal send_msg funciton which
  24               governs retries in this manner.
  25     Date:     16 July 2019
  26 .fi
  27
  28 &h3(Retries)
  29 The send operations in RMR will retry &ital(soft) send failures until one of three
  30 conditions occurs:
  31 &half_space
  32 &indent
  33 &beg_dlist( 0.3i : ^&bold_font )
  34     &di(1.) The message is sent without error
  35     &half_space
  36
  37     &di(2.) The underlying transport reports a &ital(hard) failure
  38     &half_space
  39
  40     &di(3.) The maximum number of retry loops has been attempted
  41     &end_dlist
  42 &uindent
  43
  44 &space
  45 A retry loop consists of approximately 1000 send attempts &bold(without) any intervening
  46 calls to &ital(sleep()) or &ital(usleep().)
  47 The number of retry loops defaults to 1, thus a maximum of 1000 send attempts is performed
  48 before returning to the user application.
  49 This value can be set at any point after RMr initialisation using the &ital(rmr_set_stimeout())
  50 function allowing the user application to completely disable retires (set to 0), or to
  51 increase the number of retry loops.
  52
  53 &h3(Transport Level Blocking)
  54 The underlying transport mechanism used to send messages is configured in &ital(non-blocking)
  55 mode.
  56 This means that if a message cannot be sent immediately the transport mechanism will &bold(not)
  57 pause with the assumption that the inability to send will clear quickly (within a few milliseconds).
  58 This means that when the retry loop is completely disabled (set to 0), that the failure to
  59 accept a message for sending by the underlying mechanisms (software or hardware) will be
  60 reported immediately to the user application.
  61
  62 &space
  63 It should be noted that depending on the underlying transport mechanism being used, it is
  64 extremely likely that retry conditions will happen during normal operations.
  65 These are completely out of RMR's control, and there is nothing that RMR can do to avoid or mitigate
  66 these other than by allowing RMR to retry the send operation, and even then it is possible
  67 (e.g., during connection reattempts), that a single retry loop is not enough to guarantee a
  68 successful send.
  69