X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=doc%2Fsrc%2Fman%2Frmr_init.3.xfm;h=f4ed0467a73ff15ad07fad8f868b9a95c20609fb;hb=5a9d175bb17fcc71aa19fc23458e485830b97e0a;hp=488e6d2f9f0c730d66b1d32cbb2d70c4e6cfd59f;hpb=392168d467d7949f391602f53f9fd62d2a64d12b;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 488e6d2..f4ed046 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. @@ -18,27 +18,27 @@ .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 -.im &{lib}/man/setup.im +.im &{lib}/man/setup.im &line_len(6i) &h1(RMR Library Functions) &h2(NAME) - rmr_init + rmr_init &h2(SYNOPSIS) &indent &ex_start #include -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 @@ -46,81 +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 -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. -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(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 -&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 ) -&diitem(RMRFL_NONE) - No flags are set. +&ditem(RMRFL_NONE) + No flags are set. + +&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. &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_MTCALL) + Enable multi-threaded call support. &half_space -&diitem(RMRFL_MTCALL) - Enable multi-threaded call support. +&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. +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. +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 +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" +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 -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 -&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 -as the first parameter to nearly all other RMR functions. +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.