.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    rmr_set_stimeout.xfm
    Abstract    The manual page for the rmr_set_stimeout function.
    Author      E. Scott Daniels
    Date        28 January 2019
.fi

.gv e LIB lib
.im &{lib}/man/setup.im

&line_len(6i)

&h1(RMR Library Functions)
&h2(NAME)
    rmr_set_stimeout

&h2(SYNOPSIS )
&indent
&ex_start
#include <rmr/rmr.h>

rmr_mbuf_t* rmr_set_stimeout( void* vctx, int rloops );

&ex_end
&uindent

&h2(DESCRIPTION)
The &cw(rmr_set_stimeout) function sets the configuration for how RMr will retry
message send operations which complete with either a &ital(timeout)  or &ital(again)
completion value.  (Send operations include all of the possible message send
functions: &ital(rmr_send_msg(), rmr_call(), rmr_rts_msg()) and &ital(rmr_wh_send_msg().)
The &ital(rloops) parameter sets the maximum number of retry loops
that will be attempted before giving up and returning the unsuccessful state to the user
application.
Each retry loop is approximately 1000 attempts, and RMr does &bold(not) invoke any sleep
function between retries in the loop; a small, 1 mu-sec, sleep is executed between loop
sets if the &ital(rloops) value is greater than 1.

.sp
&h3(Disabling Retries)
By default, the send operations will execute with an &ital(rloop) setting of 1; each send
operation will attempt to resend the message approximately 1000 times before giving up.
If the user application does not want to have send operations retry when the underlying
transport mechanism indicates &ital(timeout) or &ital(again,) the application should
invoke this function and pass a value of 0 (zero) for &ital(rloops.)
With this setting, all RMr send operations will attempt a send operation only &bold(once,)
returning immediately to the caller with the state of that single attempt.


&h2(RETURN VALUE)
This function returns a -1 to indicate that the &ital(rloops) value could not be set, and
the value &ital(RMR_OK) to indicate success.


&h2(ERRORS)
Currently errno is &bold(not) set by this function; the only cause of a failure is an
invalid context ( .sm &ital(vctx) .sm ) pointer.

&h2(EXAMPLE)
The following is a simple example of how the &cw(rmr_set_stimeout) function is called.

&space
&ex_start
    #define NO_FLAGS    0

    char* port = "43086";     // port for message router listen
    int   max_size = 4096;    // max message size for default allocations
    void* mr_context;         // message router context

    mr_context = rmr_init( port, max_size, NO_FLAGS );
    if( mr_context != NULL ) {
        rmr_set_stimeout( mr_context, 0 );    // turn off retries
    }

&ex_end


&h2(SEE ALSO )
.ju off
rmr_alloc_msg(3),
rmr_call(3),
rmr_free_msg(3),
rmr_init(3),
rmr_payload_size(3),
rmr_rcv_msg(3),
rmr_rcv_specific(3),
rmr_rts_msg(3),
rmr_ready(3),
rmr_mk_ring(3),
rmr_ring_free(3),
rmr_send_msg(3),
rmr_torcv_rcv(3),
rmr_wh_send_msg(3)
.ju on