Re-enable RMR libary's module tests
[ric-plt/lib/rmr.git] / doc / src / man / rmr_init.3.xfm
index 99d28bc..05c9603 100644 (file)
@@ -38,7 +38,7 @@
 &ex_start
 #include <rmr/rmr.h>
 
 &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
@@ -51,19 +51,30 @@ send messages.
 
 &space
 &ital(Port) is used to listen for connection requests from other RMR based applications.
 
 &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
 following flags are supported:
 
 &half_space
@@ -74,7 +85,7 @@ following flags are supported:
 &half_space
 &ditem(RMRFL_NOTHREAD)
     The route table collector thread is not to be started. This should only be used
 &half_space
 &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.
+    by the route table generator application if it is based on RMR.
 
 &half_space
 &ditem(RMRFL_MTCALL)
 
 &half_space
 &ditem(RMRFL_MTCALL)
@@ -103,10 +114,10 @@ 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.
+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.
 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
+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"
 to this approach.
 
 header, but as an additional process is necessary the user application must "opt in"
 to this approach.
 
@@ -121,7 +132,7 @@ The following variables are used if found.
 .im &{lib}/man/env_var_list.im
 
 &h2(RETURN VALUE)
 .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
+The &cw(rmr_init) function returns a void pointer (a context if you will) that is passed
 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.
 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.
@@ -131,7 +142,7 @@ The following error values are specifically set by this RMR function. In some ca
 error message of a system call is propagated up, and thus this list might be incomplete.
 
 &beg_dlist(.75i : ^&bold_font )
 error message of a system call is propagated up, and thus this list might be incomplete.
 
 &beg_dlist(.75i : ^&bold_font )
-&di(ENOMEM) Unable to allocate memory.
+&ditem(ENOMEM) Unable to allocate memory.
 &end_dlist
 
 &h2(EXAMPLE)
 &end_dlist
 
 &h2(EXAMPLE)