Documentation changes needed to support RTD
[ric-plt/lib/rmr.git] / doc / src / man / rmr_init.3.xfm
1 .if false
2 ==================================================================================
3         Copyright (c) 2019 Nokia 
4         Copyright (c) 2018-2019 AT&T Intellectual Property.
5
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
9
10        http://www.apache.org/licenses/LICENSE-2.0
11
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 ==================================================================================
18 .fi
19
20 .if false
21         Mnemonic        rmr_init_man.xfm
22         Abstract        The manual page for the rmr_init function.
23         Author          E. Scott Daniels
24         Date            28 January 2019
25 .fi
26
27 .gv e LIB lib
28 .im &{lib}/man/setup.im 
29
30 &line_len(6i)
31
32 &h1(RMR Library Functions)
33 &h2(NAME)
34         rmr_init
35
36 &h2(SYNOPSIS)
37 &indent
38 &ex_start
39 #include <rmr/rmr.h>
40
41 void* rmr_init( char* proto_port, int max_msg_size, int flags );
42 &ex_end
43
44 &uindent
45
46 &h2(DESCRIPTION)
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 
50 send messages.
51
52 &space
53 &ital(Port) is used to listen for connection requests from other RMR based applications.
54 The value of &ital(max_msg_size) will be used when allocating zero copy send buffers
55 which must be allocated, possibly, prior to the application knowing the actual size of
56 a specific message. 
57
58 &space
59 &ital(Flags) allows for selection of some RMr options at the time of initialisation. 
60 These are set by ORing &cw(RMRFL_) constants from the RMr header file. Currently the 
61 following flags are supported:
62
63 &half_space
64 &beg_dlist(1i : &bold_font )
65 &diitem(RMRFL_NONE) 
66         No flags are set.
67
68 &half_space
69 &diitem(RMRFL_NOTHREAD)
70         The route table collector thread is not to be started. This should only be used
71         by the route table generator application if it is based on RMr.
72
73 &half_space
74 &diitem(RMRFL_MTCALL)
75         Enable multi-threaded call support. 
76 &end_dlist
77
78 &h3(Multi-threaded Calling)
79 The support for an application to issue a &ital(blocking call) by the &cw(rmr_call()) function
80 was limited such that only user applications which were operating in a single thread
81 could safely use the function.
82 Further, timeouts were message count based and not time unit based. 
83 Multi-threaded call support adds the ability for a user application with multiple threads
84 to invoke a blocking call function with the guarentee that the correct response message 
85 is delivered to the thread.  
86 The additional support is implemented with the &ital( rmr_mt_call() ) and &ital( rmr_mt_rcv() )
87 function calls. 
88 &space
89
90 Multi-threaded call support requires the user application to specifically enable it
91 when RMr is initialised. 
92 This is necessary because a second, dedicated, receiver thread  must be started, and 
93 requires all messages to be examined and queued by this thread.
94 The additional overhead is minimal, queuing information is all in the RMr message
95 header, but as an additional process is necessary the user application must "opt in" 
96 to this approach.
97
98 &space
99 &h2(ENVIRONMENT)
100 As a part of the initialisation process &cw(rmr_init) will look into the available 
101 environment variables to influence it's setup. 
102 The following variables will be used when found.
103 &half_space 
104
105 &beg_dlist(1i : &bold_font )
106 &diitem(RMR_SEED_RT) 
107 Assumes this is the filename of the seed route table file to use. In normal situations,
108 the library will wait for an update from the route table generator (expected within a few seconds
109 of initialisation) before being able to send messages.
110 However, in some situations where a bootstrap table is necessary, this is the means to 
111 supply it to the library.
112 &half_space
113
114 &diitem(RMR_RTG_SVC) 
115 The route table generator assumes that RMr is listening on a well known port (4561) by 
116 default, but this environment variable can be used to change the listening port if 
117 needed. 
118 The value of the variable is expected to be just the port.
119 &end_dlist
120
121 &h2(RETURN VALUE)
122 The &cw(rmr_init) function returns a void pointer (a contex if you will) that is passed
123 as the first parameter to nearly all other RMR functions. 
124 If &cw(rmr_init) is unable to properly initialise the environment, NULL is returned and
125 errno is set to an appropriate value.
126
127 &h2(ERRORS)
128 The following error values are specifically set by this RMR function. In some cases the
129 error message of a system call is propagated up, and thus this list might be incomplete.
130
131 &beg_dlist(.75i : ^&bold_font )
132 &di(ENOMEM) Unable to allocate memory.
133 &end_dlist
134
135 &h2(EXAMPLE)
136 &ex_start
137    void*  uh;
138    rmr_mbuf* buf = NULL;
139
140    uh = rmr_init( "43086", 4096, 0 );
141    buf = rmr_rcv_msg( uh, buf );
142 &ex_end
143
144 &h2(SEE ALSO )
145 .ju off
146 rmr_alloc_msg(3),
147 rmr_call(3),
148 rmr_free_msg(3),
149 rmr_get_rcvfd(3),
150 rmr_mt_call(3),
151 rmr_mt_rcv(3),
152 rmr_payload_size(3),
153 rmr_send_msg(3),
154 rmr_rcv_msg(3),
155 rmr_rcv_specific(3),
156 rmr_rts_msg(3),
157 rmr_ready(3),
158 rmr_fib(3),
159 rmr_has_str(3),
160 rmr_tokenise(3),
161 rmr_mk_ring(3),
162 rmr_ring_free(3)
163 .ju on
164