docs/rmr_set_stimeout.3.rst

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