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