doc/src/man/rmr_init.3.xfm

   1 .if false
   2 ==================================================================================
   3         Copyright (c) 2019-2020 Nokia
   4         Copyright (c) 2018-2020 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 &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
  57 trace data size.
  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
  62 each connection.
  63
  64 &space
  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:
  68
  69 &half_space
  70 &beg_dlist(1i : &bold_font )
  71 &diitem(RMRFL_NONE)
  72         No flags are set.
  73
  74 &half_space
  75 &diitem(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.
  78
  79 &half_space
  80 &diitem(RMRFL_MTCALL)
  81         Enable multi-threaded call support.
  82
  83 &half_space
  84 &ditem(RMRFL_NOLOCK)
  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.
  91 &end_dlist
  92
  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())
 102 function calls.
 103 &space
 104
 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"
 111 to this approach.
 112
 113 &space
 114 &h2(ENVIRONMENT)
 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.
 118 &half_space
 119
 120 &beg_dlist(1i : &bold_font )
 121 &diitem(RMR_SEED_RT)
 122 Assumes this is the filename of the seed route table file to use. In normal situations,
 123 the library will wait for an update from the route table generator (expected within a few seconds
 124 of initialisation) before being able to send messages.
 125 However, in some situations where a bootstrap table is necessary, this is the means to
 126 supply it to the library.
 127 &half_space
 128
 129 &diitem(RMR_RTG_SVC)
 130 The route table generator assumes that RMr is listening on a well known port (4561) by
 131 default, but this environment variable can be used to change the listening port if
 132 needed.
 133 The value of the variable is expected to be just the port.
 134 &end_dlist
 135
 136 &h2(RETURN VALUE)
 137 The &cw(rmr_init) function returns a void pointer (a contex if you will) that is passed
 138 as the first parameter to nearly all other RMR functions.
 139 If &cw(rmr_init) is unable to properly initialise the environment, NULL is returned and
 140 errno is set to an appropriate value.
 141
 142 &h2(ERRORS)
 143 The following error values are specifically set by this RMR function. In some cases the
 144 error message of a system call is propagated up, and thus this list might be incomplete.
 145
 146 &beg_dlist(.75i : ^&bold_font )
 147 &di(ENOMEM) Unable to allocate memory.
 148 &end_dlist
 149
 150 &h2(EXAMPLE)
 151 &ex_start
 152    void*  uh;
 153    rmr_mbuf* buf = NULL;
 154
 155    uh = rmr_init( "43086", 4096, 0 );
 156    buf = rmr_rcv_msg( uh, buf );
 157 &ex_end
 158
 159 &h2(SEE ALSO )
 160 .ju off
 161 rmr_alloc_msg(3),
 162 rmr_call(3),
 163 rmr_free_msg(3),
 164 rmr_get_rcvfd(3),
 165 rmr_mt_call(3),
 166 rmr_mt_rcv(3),
 167 rmr_payload_size(3),
 168 rmr_send_msg(3),
 169 rmr_rcv_msg(3),
 170 rmr_rcv_specific(3),
 171 rmr_rts_msg(3),
 172 rmr_ready(3),
 173 rmr_fib(3),
 174 rmr_has_str(3),
 175 rmr_tokenise(3),
 176 rmr_mk_ring(3),
 177 rmr_ring_free(3)
 178 .ju on
 179