docs/rmr_set_stimeout.3.rst

   1
   2
   3 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   4 .. SPDX-License-Identifier: CC-BY-4.0
   5 .. CAUTION: this document is generated from source in doc/src/rtd.
   6 .. To make changes edit the source and recompile the document.
   7 .. Do NOT make changes directly to .rst or .md files.
   8
   9
  10 ============================================================================================
  11 Man Page: rmr_set_stimeout
  12 ============================================================================================
  13
  14 RMR Library Functions
  15 ============================================================================================
  16
  17
  18 NAME
  19 --------------------------------------------------------------------------------------------
  20
  21 rmr_set_stimeout
  22
  23 SYNOPSIS
  24 --------------------------------------------------------------------------------------------
  25
  26
  27 ::
  28
  29  #include <rmr/rmr.h>
  30  rmr_mbuf_t* rmr_set_stimeout( void* vctx, int rloops );
  31
  32
  33
  34 DESCRIPTION
  35 --------------------------------------------------------------------------------------------
  36
  37 The rmr_set_stimeout function sets the configuration for how
  38 RMR will retry message send operations which complete with
  39 either a *timeout* or *again* completion value. (Send
  40 operations include all of the possible message send
  41 functions: *rmr_send_msg(), rmr_call(), rmr_rts_msg()* and
  42 *rmr_wh_send_msg().* The *rloops* parameter sets the maximum
  43 number of retry loops that will be attempted before giving up
  44 and returning the unsuccessful state to the user application.
  45 Each retry loop is approximately 1000 attempts, and RMR does
  46 **not** invoke any sleep function between retries in the
  47 loop; a small, 1 mu-sec, sleep is executed between loop sets
  48 if the *rloops* value is greater than 1.
  49
  50
  51 Disabling Retries
  52 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  53
  54 By default, the send operations will execute with an *rloop*
  55 setting of 1; each send operation will attempt to resend the
  56 message approximately 1000 times before giving up. If the
  57 user application does not want to have send operations retry
  58 when the underlying transport mechanism indicates *timeout*
  59 or *again,* the application should invoke this function and
  60 pass a value of 0 (zero) for *rloops.* With this setting, all
  61 RMR send operations will attempt a send operation only
  62 **once,** returning immediately to the caller with the state
  63 of that single attempt.
  64
  65 RETURN VALUE
  66 --------------------------------------------------------------------------------------------
  67
  68 This function returns a -1 to indicate that the *rloops*
  69 value could not be set, and the value *RMR_OK* to indicate
  70 success.
  71
  72 ERRORS
  73 --------------------------------------------------------------------------------------------
  74
  75 Currently errno is **not** set by this function; the only
  76 cause of a failure is an invalid context (*vctx*) pointer.
  77
  78 EXAMPLE
  79 --------------------------------------------------------------------------------------------
  80
  81 The following is a simple example of how the rmr_set_stimeout
  82 function is called.
  83
  84
  85 ::
  86
  87      #define NO_FLAGS    0
  88      char* port = "43086";     // port for message router listen
  89      int   max_size = 4096;    // max message size for default allocations
  90      void* mr_context;         // message router context
  91      mr_context = rmr_init( port, max_size, NO_FLAGS );
  92      if( mr_context != NULL ) {
  93          rmr_set_stimeout( mr_context, 0 );    // turn off retries
  94      }
  95
  96
  97
  98 SEE ALSO
  99 --------------------------------------------------------------------------------------------
 100
 101 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
 102 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
 103 rmr_rts_msg(3), rmr_ready(3), rmr_mk_ring(3),
 104 rmr_ring_free(3), rmr_send_msg(3), rmr_torcv_rcv(3),
 105 rmr_wh_send_msg(3)