Fix large message bug in SI95 data callback

[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 3871d03..5e53e63 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 Nokia 
-       Copyright (c) 2018-2019 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.


@@ -51,28 +51,43 @@ 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 value of &ital(max_msg_size) will be used when allocating zero copy send buffers
-which must be allocated, possibly, prior to the application knowing the actual size of
-a specific message. 
+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.

 
 &space
 &ital(Flags) allows for selection of some RMr options at the time of initialisation. 
 
 &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 
+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 )

-&ditem(RMRFL_NONE) 
+&diitem(RMRFL_NONE) 

        No flags are set.
 
 &half_space
        No flags are set.
 
 &half_space

-&ditem(RMRFL_NOTHREAD)
+&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.
 
 &half_space
        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

-&ditem(RMRFL_MTCALL)
+&diitem(RMRFL_MTCALL)

        Enable multi-threaded call support. 
        Enable multi-threaded call support. 

+
+&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.

 &end_dlist
 
 &h3(Multi-threaded Calling)
 &end_dlist
 
 &h3(Multi-threaded Calling)


@@ -81,9 +96,9 @@ was limited such that only user applications which were operating in a single th
 could safely use the function.
 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
 could safely use the function.
 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

-to invoke a blocking call function with the guarentee that the correct response message 
+to invoke a blocking call function with the guarantee that the correct response message 

 is delivered to the thread.  
 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. 
 &space
 
 function calls. 
 &space
 


@@ -103,7 +118,7 @@ The following variables will be used when found.
 &half_space 
 
 &beg_dlist(1i : &bold_font )
 &half_space 
 
 &beg_dlist(1i : &bold_font )

-&ditem(RMR_SEED_RT) 
+&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.
 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.


@@ -111,7 +126,7 @@ However, in some situations where a bootstrap table is necessary, this is the me
 supply it to the library.
 &half_space
 
 supply it to the library.
 &half_space
 

-&ditem(RMR_RTG_SVC) 
+&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 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. 


@@ -142,6 +157,7 @@ error message of a system call is propagated up, and thus this list might be inc
 &ex_end
 
 &h2(SEE ALSO )
 &ex_end
 
 &h2(SEE ALSO )

+.ju off

 rmr_alloc_msg(3),
 rmr_call(3),
 rmr_free_msg(3),
 rmr_alloc_msg(3),
 rmr_call(3),
 rmr_free_msg(3),


@@ -159,7 +175,5 @@ rmr_has_str(3),
 rmr_tokenise(3),
 rmr_mk_ring(3),
 rmr_ring_free(3)
 rmr_tokenise(3),
 rmr_mk_ring(3),
 rmr_ring_free(3)

-
-
-.qu
+.ju on