doc/src/man/retry.im

.if false
==================================================================================
   Copyright (c) 2019 Nokia
   Copyright (c) 2018-2019 AT&T Intellectual Property.

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
==================================================================================
.fi

.if false
    Mnemonic: retry.im
    Abstract: Common text for all send operation functions. This should be imbedded by any
              function which will ultimately use the internal send_msg funciton which
              governs retries in this manner.
    Date:     16 July 2019
.fi

&h3(Retries)
The send operations in RMR will retry &ital(soft) send failures until one of three
conditions occurs:
&half_space
&indent
&beg_dlist( 0.3i : ^&bold_font )
    &di(1.) The message is sent without error
    &half_space

    &di(2.) The underlying transport reports a &ital(hard) failure
    &half_space

    &di(3.) The maximum number of retry loops has been attempted
    &end_dlist
&uindent

&space
A retry loop consists of approximately 1000 send attempts &bold(without) any intervening
calls to &ital(sleep()) or &ital(usleep().)
The number of retry loops defaults to 1, thus a maximum of 1000 send attempts is performed
before returning to the user application.
This value can be set at any point after RMr initialisation using the &ital(rmr_set_stimeout())
function allowing the user application to completely disable retires (set to 0), or to
increase the number of retry loops.

&h3(Transport Level Blocking)
The underlying transport mechanism used to send messages is configured in &ital(non-blocking)
mode.
This means that if a message cannot be sent immediately the transport mechanism will &bold(not)
pause with the assumption that the inability to send will clear quickly (within a few milliseconds).
This means that when the retry loop is completely disabled (set to 0), that the failure to
accept a message for sending by the underlying mechanisms (software or hardware) will be
reported immediately to the user application.

&space
It should be noted that depending on the underlying transport mechanism being used, it is
extremely likely that retry conditions will happen during normal operations.
These are completely out of RMR's control, and there is nothing that RMR can do to avoid or mitigate
these other than by allowing RMR to retry the send operation, and even then it is possible
(e.g., during connection reattempts), that a single retry loop is not enough to guarantee a
successful send.