Release 2.0.0

[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 408c954..5413beb 100644 (file)
--- a/doc/src/man/rmr_init.3.xfm
+++ b/doc/src/man/rmr_init.3.xfm
@@ -24,19 +24,8 @@
        Date            28 January 2019
 .fi
 
        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
 .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
+.im &{lib}/man/setup.im 

 
 &line_len(6i)
 
 
 &line_len(6i)
 


@@ -66,6 +55,46 @@ The value of &ital(max_msg_size) will be used when allocating zero copy send buf
 which must be allocated, possibly, prior to the application knowing the actual size of
 a specific message. 
 
 which must be allocated, possibly, prior to the application knowing the actual size of
 a specific message. 
 

+&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 )
+&diitem(RMRFL_NONE) 
+       No flags are set.
+
+&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.
+
+&half_space
+&diitem(RMRFL_MTCALL)
+       Enable multi-threaded call support. 
+&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. 
+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 
+is delivered to the thread.  
+The additional support is implemented with the &ital(rmr_mt_call()) and &ital(rmr_mt_rcv())
+function calls. 
+&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 
+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" 
+to this approach.
+

 &space
 &h2(ENVIRONMENT)
 As a part of the initialisation process &cw(rmr_init) will look into the available 
 &space
 &h2(ENVIRONMENT)
 As a part of the initialisation process &cw(rmr_init) will look into the available 


@@ -74,7 +103,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.


@@ -82,7 +111,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. 


@@ -113,10 +142,13 @@ 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_get_rcvfd(3),
 rmr_alloc_msg(3),
 rmr_call(3),
 rmr_free_msg(3),
 rmr_get_rcvfd(3),

+rmr_mt_call(3),
+rmr_mt_rcv(3),

 rmr_payload_size(3),
 rmr_send_msg(3),
 rmr_rcv_msg(3),
 rmr_payload_size(3),
 rmr_send_msg(3),
 rmr_rcv_msg(3),


@@ -128,7 +160,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