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 norm_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(norm_msg_size) parameter is used to allocate receive buffers and should be
  55 set to what the user application expects to be a size which will hold the vast majority
  56 of expected messages.
  57 When computing the size, the application should consider the usual payload size &bold(and)
  58 the maximum trace data size that will be used.
  59 This value is also used as the default message size when allocating message buffers (when
  60 a zero size is given to rmr_alloc_msg(); see the rmr_alloc_msg() manual page).
  61 Messages arriving which are longer than the given normal size will cause RMR to allocate
  62 a new buffer which is large enough for the arriving message.
  63
  64 &space
  65 Starting with version 3.8.0 RMR no longer places a maximum buffer size for received
  66 messages.
  67 The underlying system memory manager might impose such a limit and the attempt to
  68 allocate a buffer larger than that limit will likely result in an application abort.
  69 Other than the potential performance impact from extra memory allocation and release,
  70 there is no penality to the user programme for specifyning a normal buffer size which
  71 is usually smaller than received buffers.
  72 Similarly, the only penality to the application for over specifying the normal buffer
  73 size might be a larger memory footprint.
  74
  75 &space
  76 &ital(Flags) allows for selection of some RMr options at the time of initialisation.
  77 These are set by ORing &cw(RMRFL) constants from the RMr header file. Currently the
  78 following flags are supported:
  79
  80 &half_space
  81 &beg_dlist(1i : &bold_font )
  82 &ditem(RMRFL_NONE)
  83     No flags are set.
  84
  85 &half_space
  86 &ditem(RMRFL_NOTHREAD)
  87     The route table collector thread is not to be started. This should only be used
  88     by the route table generator application if it is based on RMr.
  89
  90 &half_space
  91 &ditem(RMRFL_MTCALL)
  92     Enable multi-threaded call support.
  93
  94 &half_space
  95 &ditem(RMRFL_NOLOCK)
  96     Some underlying transport providers (e.g. SI95) enable locking to be turned off
  97     if the user application is single threaded, or otherwise can guarantee that RMR
  98     functions will not be invoked concurrently from different threads. Turning off
  99     locking can help make message receipt more efficient.
 100     If this flag is set when the underlying transport does not support disabling
 101     locks, it will be ignored.
 102 &end_dlist
 103
 104 &h3(Multi-threaded Calling)
 105 The support for an application to issue a &ital(blocking call) by the &cw(rmr_call()) function
 106 was limited such that only user applications which were operating in a single thread
 107 could safely use the function.
 108 Further, timeouts were message count based and not time unit based.
 109 Multi-threaded call support adds the ability for a user application with multiple threads
 110 to invoke a blocking call function with the guarantee that the correct response message
 111 is delivered to the thread.
 112 The additional support is implemented with the &ital(rmr_mt_call()) and &ital(rmr_mt_rcv())
 113 function calls.
 114 &space
 115
 116 Multi-threaded call support requires the user application to specifically enable it
 117 when RMr is initialised.
 118 This is necessary because a second, dedicated, receiver thread  must be started, and
 119 requires all messages to be examined and queued by this thread.
 120 The additional overhead is minimal, queuing information is all in the RMr message
 121 header, but as an additional process is necessary the user application must "opt in"
 122 to this approach.
 123
 124 &space
 125 &h2(ENVIRONMENT)
 126 As a part of the initialisation process &cw(rmr_init) reads
 127 environment variables to configure itself.
 128 The following variables are used if found.
 129 &half_space
 130
 131 .** the list of environment vars supported
 132 .im &{lib}/man/env_var_list.im
 133
 134 &h2(RETURN VALUE)
 135 The &cw(rmr_init) function returns a void pointer (a contex if you will) that is passed
 136 as the first parameter to nearly all other RMR functions.
 137 If &cw(rmr_init) is unable to properly initialise the environment, NULL is returned and
 138 errno is set to an appropriate value.
 139
 140 &h2(ERRORS)
 141 The following error values are specifically set by this RMR function. In some cases the
 142 error message of a system call is propagated up, and thus this list might be incomplete.
 143
 144 &beg_dlist(.75i : ^&bold_font )
 145 &di(ENOMEM) Unable to allocate memory.
 146 &end_dlist
 147
 148 &h2(EXAMPLE)
 149 &ex_start
 150    void*  uh;
 151    rmr_mbuf* buf = NULL;
 152
 153    uh = rmr_init( "43086", 4096, 0 );
 154    buf = rmr_rcv_msg( uh, buf );
 155 &ex_end
 156
 157 &h2(SEE ALSO )
 158 .ju off
 159 rmr_alloc_msg(3),
 160 rmr_call(3),
 161 rmr_free_msg(3),
 162 rmr_get_rcvfd(3),
 163 rmr_mt_call(3),
 164 rmr_mt_rcv(3),
 165 rmr_payload_size(3),
 166 rmr_send_msg(3),
 167 rmr_rcv_msg(3),
 168 rmr_rcv_specific(3),
 169 rmr_rts_msg(3),
 170 rmr_ready(3),
 171 rmr_fib(3),
 172 rmr_has_str(3),
 173 rmr_tokenise(3),
 174 rmr_mk_ring(3),
 175 rmr_ring_free(3)
 176 .ju on
 177