X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=doc%2Fsrc%2Fman%2Frmr_set_stimeout.3.xfm;fp=doc%2Fsrc%2Fman%2Frmr_set_stimeout.3.xfm;h=5550d248d641a5b7a17db0d63588f9a841db3023;hb=e30fc3a978dd2d34b35342273e6601ae6148b4bf;hp=0000000000000000000000000000000000000000;hpb=6efa7aa73ef36cb0c299e34b5457ab0e4ebf88e3;p=ric-plt%2Flib%2Frmr.git

diff --git a/doc/src/man/rmr_set_stimeout.3.xfm b/doc/src/man/rmr_set_stimeout.3.xfm
new file mode 100644
index 0000000..5550d24
--- /dev/null
+++ b/doc/src/man/rmr_set_stimeout.3.xfm
@@ -0,0 +1,127 @@
+.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
+
+.** if formatting with tfm, the roff.im will cause roff output to be generated
+.** if formatting with pfm, then pretty postscript will be generated
+.gv e LIB lib
+.if pfm
+    .im &{lib}/generic_ps.im
+.ei
+    .gv e OUTPUT_RST use_rst
+    .if .ev &use_rst 1 =
+    	.im &{lib}/rst.im
+    .ei
+    	.im &{lib}/roff.im
+    .fi
+.fi
+
+&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
+
+
+.qu
+