.if false
==================================================================================
	Copyright (c) 2019 Nokia 
	Copyright (c) 2018-2019 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.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under 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
.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

&line_len(6i)

&h1(RMR Library Functions)
&h2(NAME)
	rmr_init

&h2(SYNOPSIS)
&indent
&ex_start
#include <rmr/rmr.h>

void* rmr_init( char* proto_port, int max_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 
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. 

&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 )
&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
&ditem(RMRFL_MTCALL)
	Enable multi-threaded call support. 
&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 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. 
&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)
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 )
&ditem(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.
&half_space

&ditem(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

&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. 
If &cw(rmr_init) is unable to properly initialise the environment, NULL is returned and
errno is set to an appropriate value.

&h2(ERRORS)
The following error values are specifically set by this RMR function. In some cases the
error message of a system call is propagated up, and thus this list might be incomplete.

&beg_dlist(.75i : ^&bold_font )
&di(ENOMEM) Unable to allocate memory.
&end_dlist

&h2(EXAMPLE)
&ex_start
   void*  uh;
   rmr_mbuf* buf = NULL;

   uh = rmr_init( "43086", 4096, 0 );
   buf = rmr_rcv_msg( uh, buf );
&ex_end

&h2(SEE ALSO )
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),
rmr_rcv_specific(3),
rmr_rts_msg(3),
rmr_ready(3),
rmr_fib(3),
rmr_has_str(3),
rmr_tokenise(3),
rmr_mk_ring(3),
rmr_ring_free(3)


.qu