Fix failure when in static only route table mode

[ric-plt/lib/rmr.git] / doc / src / man / rmr_init.3.xfm

diff --git a/doc/src/man/rmr_init.3.xfm b/doc/src/man/rmr_init.3.xfm
index 5e53e63..acace5a 100644 (file)
--- a/doc/src/man/rmr_init.3.xfm
+++ b/doc/src/man/rmr_init.3.xfm
@@ -1,7 +1,7 @@
 .if false
 ==================================================================================
 .if false
 ==================================================================================

-       Copyright (c) 2019-2020 Nokia 
-       Copyright (c) 2018-2020 AT&T Intellectual Property.
+   Copyright (c) 2019-2020 Nokia
+   Copyright (c) 2018-2020 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.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.


@@ -18,27 +18,27 @@
 .fi
 
 .if false
 .fi
 
 .if false

-       Mnemonic        rmr_init_man.xfm
-       Abstract        The manual page for the rmr_init function.
-       Author          E. Scott Daniels
-       Date            28 January 2019
+    Mnemonic    rmr_init_man.xfm
+    Abstract    The manual page for the rmr_init function.
+    Author      E. Scott Daniels
+    Date        28 January 2019

 .fi
 
 .gv e LIB lib
 .fi
 
 .gv e LIB lib

-.im &{lib}/man/setup.im 
+.im &{lib}/man/setup.im

 
 &line_len(6i)
 
 &h1(RMR Library Functions)
 &h2(NAME)
 
 &line_len(6i)
 
 &h1(RMR Library Functions)
 &h2(NAME)

-       rmr_init
+    rmr_init

 
 &h2(SYNOPSIS)
 &indent
 &ex_start
 #include <rmr/rmr.h>
 
 
 &h2(SYNOPSIS)
 &indent
 &ex_start
 #include <rmr/rmr.h>
 

-void* rmr_init( char* proto_port, int max_msg_size, int flags );
+void* rmr_init( char* proto_port, int norm_msg_size, int flags );

 &ex_end
 
 &uindent
 &ex_end
 
 &uindent


@@ -46,96 +46,94 @@ void* rmr_init( char* proto_port, int max_msg_size, int flags );
 &h2(DESCRIPTION)
 The &cw(rmr_init) function prepares the environment for sending and receiving messages.
 It does so by establishing a worker thread (pthread) which subscribes to a route table
 &h2(DESCRIPTION)
 The &cw(rmr_init) function prepares the environment for sending and receiving messages.
 It does so by establishing a worker thread (pthread) which subscribes to a route table

-generator which provides the necessary routing information for the RMR library to 
+generator which provides the necessary routing information for the RMR library to

 send messages.
 
 &space
 &ital(Port) is used to listen for connection requests from other RMR based applications.
 send messages.
 
 &space
 &ital(Port) is used to listen for connection requests from other RMR based applications.

-The &ital(max_msg_size) parameter is used to allocate receive buffers and is the
-maximum message size which the application expects to receive. 
-This value is the sum of &bold(both) the maximum payload size &bold(and) the maximum
-trace data size. 
-This value is also used as the default message size when allocating message buffers.
-Messages arriving which are longer than the given maximum will be dropped without 
-notification to the application. 
-A warning is written to standard error for the first message which is too large on
-each connection.
+The &ital(norm_msg_size) parameter is used to allocate receive buffers and should be
+set to what the user application expects to be a size which will hold the vast majority
+of expected messages.
+When computing the size, the application should consider the usual payload size &bold(and)
+the maximum trace data size that will be used.
+This value is also used as the default message size when allocating message buffers (when
+a zero size is given to rmr_alloc_msg(); see the rmr_alloc_msg() manual page).
+Messages arriving which are longer than the given normal size will cause RMR to allocate
+a new buffer which is large enough for the arriving message.

 
 &space
 
 &space

-&ital(Flags) allows for selection of some RMr options at the time of initialisation. 
-These are set by ORing &cw(RMRFL) constants from the RMr header file. Currently the 
+Starting with version 3.8.0 RMR no longer places a maximum buffer size for received
+messages.
+The underlying system memory manager might impose such a limit and the attempt to
+allocate a buffer larger than that limit will likely result in an application abort.
+Other than the potential performance impact from extra memory allocation and release,
+there is no penality to the user programme for specifyning a normal buffer size which
+is usually smaller than received buffers.
+Similarly, the only penality to the application for over specifying the normal buffer
+size might be a larger memory footprint.
+
+&space
+&ital(Flags) allows for selection of some RMr options at the time of initialisation.
+These are set by ORing &cw(RMRFL) constants from the RMr header file. Currently the

 following flags are supported:
 
 &half_space
 &beg_dlist(1i : &bold_font )
 following flags are supported:
 
 &half_space
 &beg_dlist(1i : &bold_font )

-&diitem(RMRFL_NONE) 
-       No flags are set.
+&ditem(RMRFL_NONE)
+    No flags are set.

 
 &half_space
 
 &half_space

-&diitem(RMRFL_NOTHREAD)
-       The route table collector thread is not to be started. This should only be used
-       by the route table generator application if it is based on RMr.
+&ditem(RMRFL_NOTHREAD)
+    The route table collector thread is not to be started. This should only be used
+    by the route table generator application if it is based on RMr.

 
 &half_space
 
 &half_space

-&diitem(RMRFL_MTCALL)
-       Enable multi-threaded call support. 
+&ditem(RMRFL_MTCALL)
+    Enable multi-threaded call support.

 
 &half_space
 &ditem(RMRFL_NOLOCK)
 
 &half_space
 &ditem(RMRFL_NOLOCK)

-       Some underlying transport providers (e.g. SI95) enable locking to be turned off
-       if the user application is single threaded, or otherwise can guarantee that RMR
-       functions will not be invoked concurrently from different threads. Turning off
-       locking can help make message receipt more efficient. 
-       If this flag is set when the underlying transport does not support disabling
-       locks, it will be ignored.
+    Some underlying transport providers (e.g. SI95) enable locking to be turned off
+    if the user application is single threaded, or otherwise can guarantee that RMR
+    functions will not be invoked concurrently from different threads. Turning off
+    locking can help make message receipt more efficient.
+    If this flag is set when the underlying transport does not support disabling
+    locks, it will be ignored.

 &end_dlist
 
 &h3(Multi-threaded Calling)
 The support for an application to issue a &ital(blocking call) by the &cw(rmr_call()) function
 was limited such that only user applications which were operating in a single thread
 could safely use the function.
 &end_dlist
 
 &h3(Multi-threaded Calling)
 The support for an application to issue a &ital(blocking call) by the &cw(rmr_call()) function
 was limited such that only user applications which were operating in a single thread
 could safely use the function.

-Further, timeouts were message count based and not time unit based. 
+Further, timeouts were message count based and not time unit based.

 Multi-threaded call support adds the ability for a user application with multiple threads
 Multi-threaded call support adds the ability for a user application with multiple threads

-to invoke a blocking call function with the guarantee that the correct response message 
-is delivered to the thread.  
+to invoke a blocking call function with the guarantee that the correct response message
+is delivered to the thread.

 The additional support is implemented with the &ital(rmr_mt_call()) and &ital(rmr_mt_rcv())
 The additional support is implemented with the &ital(rmr_mt_call()) and &ital(rmr_mt_rcv())

-function calls. 
+function calls.

 &space
 
 Multi-threaded call support requires the user application to specifically enable it
 &space
 
 Multi-threaded call support requires the user application to specifically enable it

-when RMr is initialised. 
-This is necessary because a second, dedicated, receiver thread  must be started, and 
+when RMr is initialised.
+This is necessary because a second, dedicated, receiver thread  must be started, and

 requires all messages to be examined and queued by this thread.
 The additional overhead is minimal, queuing information is all in the RMr message
 requires all messages to be examined and queued by this thread.
 The additional overhead is minimal, queuing information is all in the RMr message

-header, but as an additional process is necessary the user application must "opt in" 
+header, but as an additional process is necessary the user application must "opt in"

 to this approach.
 
 &space
 &h2(ENVIRONMENT)
 to this approach.
 
 &space
 &h2(ENVIRONMENT)

-As a part of the initialisation process &cw(rmr_init) will look into the available 
-environment variables to influence it's setup. 
-The following variables will be used when found.
-&half_space 
-
-&beg_dlist(1i : &bold_font )
-&diitem(RMR_SEED_RT) 
-Assumes this is the filename of the seed route table file to use. In normal situations,
-the library will wait for an update from the route table generator (expected within a few seconds
-of initialisation) before being able to send messages.
-However, in some situations where a bootstrap table is necessary, this is the means to 
-supply it to the library.
+As a part of the initialisation process &cw(rmr_init) reads
+environment variables to configure itself.
+The following variables are used if found.

 &half_space
 
 &half_space
 

-&diitem(RMR_RTG_SVC) 
-The route table generator assumes that RMr is listening on a well known port (4561) by 
-default, but this environment variable can be used to change the listening port if 
-needed. 
-The value of the variable is expected to be just the port.
-&end_dlist
+.** the list of environment vars supported
+.im &{lib}/man/env_var_list.im

 
 &h2(RETURN VALUE)
 The &cw(rmr_init) function returns a void pointer (a contex if you will) that is passed
 
 &h2(RETURN VALUE)
 The &cw(rmr_init) function returns a void pointer (a contex if you will) that is passed

-as the first parameter to nearly all other RMR functions. 
+as the first parameter to nearly all other RMR functions.

 If &cw(rmr_init) is unable to properly initialise the environment, NULL is returned and
 errno is set to an appropriate value.
 
 If &cw(rmr_init) is unable to properly initialise the environment, NULL is returned and
 errno is set to an appropriate value.