doc/src/man/retry.im

   1 .if false
   2 ==================================================================================
   3    Copyright (c) 2019-2020 Nokia
   4    Copyright (c) 2018-2020 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
  34 &beg_list(&lic1)
  35 &item
  36     The message is sent without error
  37
  38 &half_space
  39 &item
  40     The underlying transport reports a &ital(hard) failure
  41
  42 &half_space
  43 &item
  44     The maximum number of retry loops has been attempted
  45 &end_list
  46 &uindent
  47
  48 &space
  49 A retry loop consists of approximately 1000 send attempts &bold(without) any intervening
  50 calls to &ital(sleep()) or &ital(usleep().)
  51 The number of retry loops defaults to 1, thus a maximum of 1000 send attempts is performed
  52 before returning to the user application.
  53 This value can be set at any point after RMR initialisation using the &ital(rmr_set_stimeout())
  54 function allowing the user application to completely disable retires (set to 0), or to
  55 increase the number of retry loops.
  56
  57 &h3(Transport Level Blocking)
  58 The underlying transport mechanism used to send messages is configured in &ital(non-blocking)
  59 mode.
  60 This means that if a message cannot be sent immediately the transport mechanism will &bold(not)
  61 pause with the assumption that the inability to send will clear quickly (within a few milliseconds).
  62 This means that when the retry loop is completely disabled (set to 0), that the failure to
  63 accept a message for sending by the underlying mechanisms (software or hardware) will be
  64 reported immediately to the user application.
  65
  66 &space
  67 It should be noted that depending on the underlying transport mechanism being used, it is
  68 extremely likely that retry conditions will happen during normal operations.
  69 These are completely out of RMR's control, and there is nothing that RMR can do to avoid or mitigate
  70 these other than by allowing RMR to retry the send operation, and even then it is possible
  71 (e.g., during connection reattempts), that a single retry loop is not enough to guarantee a
  72 successful send.
  73