X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=doc%2Fsrc%2Fman%2Frmr_init.3.xfm;h=5e53e63d999e192606a2e038f1aa4be73313d1cc;hb=a1575dacc478b945ea63f5d0cc3db3d66dcb5983;hp=408c95487a80af68acdbfff189ec619e9ab7214f;hpb=fd9cc7a5b3355146388ebdf4d558cb284c66c5f1;p=ric-plt%2Flib%2Frmr.git diff --git a/doc/src/man/rmr_init.3.xfm b/doc/src/man/rmr_init.3.xfm index 408c954..5e53e63 100644 --- a/doc/src/man/rmr_init.3.xfm +++ b/doc/src/man/rmr_init.3.xfm @@ -1,7 +1,7 @@ .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. @@ -24,19 +24,8 @@ 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 +.im &{lib}/man/setup.im &line_len(6i) @@ -62,9 +51,64 @@ send messages. &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. +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. + +&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) +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 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()) +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) @@ -74,7 +118,7 @@ The following variables will be used when found. &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. @@ -82,7 +126,7 @@ However, in some situations where a bootstrap table is necessary, this is the me 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. @@ -113,10 +157,13 @@ error message of a system call is propagated up, and thus this list might be inc &ex_end &h2(SEE ALSO ) +.ju off 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), @@ -128,7 +175,5 @@ rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3) - - -.qu +.ju on