.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.
.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 <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
&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.
+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.
+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.
Code Review / ric-plt / lib / rmr.git / blobdiff