2 ==================================================================================
3 Copyright (c) 2019-2020 Nokia
4 Copyright (c) 2018-2020 AT&T Intellectual Property.
6 Licensed under the Apache License, Version 2.0 (the "License");
7 you may not use this file except in compliance with the License.
8 You may obtain a copy of the License at
10 http://www.apache.org/licenses/LICENSE-2.0
12 Unless required by applicable law or agreed to in writing, software
13 distributed under the License is distributed on an "AS IS" BASIS,
14 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 See the License for the specific language governing permissions and
16 limitations under the License.
17 ==================================================================================
21 Mnemonic rmr_init_man.xfm
22 Abstract The manual page for the rmr_init function.
23 Author E. Scott Daniels
28 .im &{lib}/man/setup.im
32 &h1(RMR Library Functions)
41 void* rmr_init( char* proto_port, int max_msg_size, int flags );
47 The &cw(rmr_init) function prepares the environment for sending and receiving messages.
48 It does so by establishing a worker thread (pthread) which subscribes to a route table
49 generator which provides the necessary routing information for the RMR library to
53 &ital(Port) is used to listen for connection requests from other RMR based applications.
54 The &ital(max_msg_size) parameter is used to allocate receive buffers and is the
55 maximum message size which the application expects to receive.
56 This value is the sum of &bold(both) the maximum payload size &bold(and) the maximum
58 This value is also used as the default message size when allocating message buffers.
59 Messages arriving which are longer than the given maximum will be dropped without
60 notification to the application.
61 A warning is written to standard error for the first message which is too large on
65 &ital(Flags) allows for selection of some RMr options at the time of initialisation.
66 These are set by ORing &cw(RMRFL) constants from the RMr header file. Currently the
67 following flags are supported:
70 &beg_dlist(1i : &bold_font )
75 &ditem(RMRFL_NOTHREAD)
76 The route table collector thread is not to be started. This should only be used
77 by the route table generator application if it is based on RMr.
81 Enable multi-threaded call support.
85 Some underlying transport providers (e.g. SI95) enable locking to be turned off
86 if the user application is single threaded, or otherwise can guarantee that RMR
87 functions will not be invoked concurrently from different threads. Turning off
88 locking can help make message receipt more efficient.
89 If this flag is set when the underlying transport does not support disabling
90 locks, it will be ignored.
93 &h3(Multi-threaded Calling)
94 The support for an application to issue a &ital(blocking call) by the &cw(rmr_call()) function
95 was limited such that only user applications which were operating in a single thread
96 could safely use the function.
97 Further, timeouts were message count based and not time unit based.
98 Multi-threaded call support adds the ability for a user application with multiple threads
99 to invoke a blocking call function with the guarantee that the correct response message
100 is delivered to the thread.
101 The additional support is implemented with the &ital(rmr_mt_call()) and &ital(rmr_mt_rcv())
105 Multi-threaded call support requires the user application to specifically enable it
106 when RMr is initialised.
107 This is necessary because a second, dedicated, receiver thread must be started, and
108 requires all messages to be examined and queued by this thread.
109 The additional overhead is minimal, queuing information is all in the RMr message
110 header, but as an additional process is necessary the user application must "opt in"
115 As a part of the initialisation process &cw(rmr_init) will look into the available
116 environment variables to influence it's setup.
117 The following variables will be used when found.
120 .** the list of environment vars supported
121 .im &{lib}/man/env_var_list.im
124 The &cw(rmr_init) function returns a void pointer (a contex if you will) that is passed
125 as the first parameter to nearly all other RMR functions.
126 If &cw(rmr_init) is unable to properly initialise the environment, NULL is returned and
127 errno is set to an appropriate value.
130 The following error values are specifically set by this RMR function. In some cases the
131 error message of a system call is propagated up, and thus this list might be incomplete.
133 &beg_dlist(.75i : ^&bold_font )
134 &di(ENOMEM) Unable to allocate memory.
140 rmr_mbuf* buf = NULL;
142 uh = rmr_init( "43086", 4096, 0 );
143 buf = rmr_rcv_msg( uh, buf );