doc/src/man/rmr_set_stimeout.3.xfm

   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 .if false
  20     Mnemonic    rmr_set_stimeout.xfm
  21     Abstract    The manual page for the rmr_set_stimeout function.
  22     Author      E. Scott Daniels
  23     Date        28 January 2019
  24 .fi
  25
  26 .gv e LIB lib
  27 .im &{lib}/man/setup.im
  28
  29 &line_len(6i)
  30
  31 &h1(RMR Library Functions)
  32 &h2(NAME)
  33     rmr_set_stimeout
  34
  35 &h2(SYNOPSIS )
  36 &indent
  37 &ex_start
  38 #include <rmr/rmr.h>
  39
  40 rmr_mbuf_t* rmr_set_stimeout( void* vctx, int rloops );
  41
  42 &ex_end
  43 &uindent
  44
  45 &h2(DESCRIPTION)
  46 The &cw(rmr_set_stimeout) function sets the configuration for how RMr will retry
  47 message send operations which complete with either a &ital(timeout)  or &ital(again)
  48 completion value.  (Send operations include all of the possible message send
  49 functions: &ital(rmr_send_msg(), rmr_call(), rmr_rts_msg()) and &ital(rmr_wh_send_msg().)
  50 The &ital(rloops) parameter sets the maximum number of retry loops
  51 that will be attempted before giving up and returning the unsuccessful state to the user
  52 application.
  53 Each retry loop is approximately 1000 attempts, and RMr does &bold(not) invoke any sleep
  54 function between retries in the loop; a small, 1 mu-sec, sleep is executed between loop
  55 sets if the &ital(rloops) value is greater than 1.
  56
  57 .sp
  58 &h3(Disabling Retries)
  59 By default, the send operations will execute with an &ital(rloop) setting of 1; each send
  60 operation will attempt to resend the message approximately 1000 times before giving up.
  61 If the user application does not want to have send operations retry when the underlying
  62 transport mechanism indicates &ital(timeout) or &ital(again,) the application should
  63 invoke this function and pass a value of 0 (zero) for &ital(rloops.)
  64 With this setting, all RMr send operations will attempt a send operation only &bold(once,)
  65 returning immediately to the caller with the state of that single attempt.
  66
  67
  68 &h2(RETURN VALUE)
  69 This function returns a -1 to indicate that the &ital(rloops) value could not be set, and
  70 the value &ital(RMR_OK) to indicate success.
  71
  72
  73 &h2(ERRORS)
  74 Currently errno is &bold(not) set by this function; the only cause of a failure is an
  75 invalid context ( .sm &ital(vctx) .sm ) pointer.
  76
  77 &h2(EXAMPLE)
  78 The following is a simple example of how the &cw(rmr_set_stimeout) function is called.
  79
  80 &space
  81 &ex_start
  82     #define NO_FLAGS    0
  83
  84     char* port = "43086";     // port for message router listen
  85     int   max_size = 4096;    // max message size for default allocations
  86     void* mr_context;         // message router context
  87
  88     mr_context = rmr_init( port, max_size, NO_FLAGS );
  89     if( mr_context != NULL ) {
  90         rmr_set_stimeout( mr_context, 0 );    // turn off retries
  91     }
  92
  93 &ex_end
  94
  95
  96 &h2(SEE ALSO )
  97 .ju off
  98 rmr_alloc_msg(3),
  99 rmr_call(3),
 100 rmr_free_msg(3),
 101 rmr_init(3),
 102 rmr_payload_size(3),
 103 rmr_rcv_msg(3),
 104 rmr_rcv_specific(3),
 105 rmr_rts_msg(3),
 106 rmr_ready(3),
 107 rmr_mk_ring(3),
 108 rmr_ring_free(3),
 109 rmr_send_msg(3),
 110 rmr_torcv_rcv(3),
 111 rmr_wh_send_msg(3)
 112 .ju on