docs/rmr_init.3.rst

   1
   2
   3 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   4 .. SPDX-License-Identifier: CC-BY-4.0
   5 .. CAUTION: this document is generated from source in doc/src/rtd.
   6 .. To make changes edit the source and recompile the document.
   7 .. Do NOT make changes directly to .rst or .md files.
   8
   9
  10 ============================================================================================
  11 Man Page: rmr_init
  12 ============================================================================================
  13
  14 RMR Library Functions
  15 ============================================================================================
  16
  17
  18 NAME
  19 --------------------------------------------------------------------------------------------
  20
  21 rmr_init
  22
  23 SYNOPSIS
  24 --------------------------------------------------------------------------------------------
  25
  26
  27 ::
  28
  29  #include <rmr/rmr.h>
  30  void* rmr_init( char* proto_port, int norm_msg_size, int flags );
  31
  32
  33
  34 DESCRIPTION
  35 --------------------------------------------------------------------------------------------
  36
  37 The rmr_init function prepares the environment for sending
  38 and receiving messages. It does so by establishing a worker
  39 thread (pthread) which subscribes to a route table generator
  40 which provides the necessary routing information for the RMR
  41 library to send messages.
  42
  43 *Port* is used to listen for connection requests from other
  44 RMR based applications. The *norm_msg_size* parameter is used
  45 to allocate receive buffers and should be set to what the
  46 user application expects to be a size which will hold the
  47 vast majority of expected messages. When computing the size,
  48 the application should consider the usual payload size
  49 **and** the maximum trace data size that will be used. This
  50 value is also used as the default message size when
  51 allocating message buffers (when a zero size is given to
  52 rmr_alloc_msg(); see the rmr_alloc_msg() manual page).
  53 Messages arriving which are longer than the given normal size
  54 will cause RMR to allocate a new buffer which is large enough
  55 for the arriving message.
  56
  57 Starting with version 3.8.0 RMR no longer places a maximum
  58 buffer size for received messages. The underlying system
  59 memory manager might impose such a limit and the attempt to
  60 allocate a buffer larger than that limit will likely result
  61 in an application abort. Other than the potential performance
  62 impact from extra memory allocation and release, there is no
  63 penality to the user programme for specifyning a normal
  64 buffer size which is usually smaller than received buffers.
  65 Similarly, the only penality to the application for over
  66 specifying the normal buffer size might be a larger memory
  67 footprint.
  68
  69 *Flags* allows for selection of some RMr options at the time
  70 of initialisation. These are set by ORing RMRFL constants
  71 from the RMr header file. Currently the following flags are
  72 supported:
  73
  74
  75
  76 RMRFL_NONE
  77
  78   No flags are set.
  79
  80
  81 RMRFL_NOTHREAD
  82
  83   The route table collector thread is not to be started.
  84   This should only be used by the route table generator
  85   application if it is based on RMr.
  86
  87
  88 RMRFL_MTCALL
  89
  90   Enable multi-threaded call support.
  91
  92
  93 RMRFL_NOLOCK
  94
  95   Some underlying transport providers (e.g. SI95) enable
  96   locking to be turned off if the user application is single
  97   threaded, or otherwise can guarantee that RMR functions
  98   will not be invoked concurrently from different threads.
  99   Turning off locking can help make message receipt more
 100   efficient. If this flag is set when the underlying
 101   transport does not support disabling locks, it will be
 102   ignored.
 103
 104
 105 Multi-threaded Calling
 106 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 107
 108 The support for an application to issue a *blocking call* by
 109 the rmr_call() function was limited such that only user
 110 applications which were operating in a single thread could
 111 safely use the function. Further, timeouts were message count
 112 based and not time unit based. Multi-threaded call support
 113 adds the ability for a user application with multiple threads
 114 to invoke a blocking call function with the guarantee that
 115 the correct response message is delivered to the thread. The
 116 additional support is implemented with the *rmr_mt_call()*
 117 and *rmr_mt_rcv()* function calls.
 118
 119 Multi-threaded call support requires the user application to
 120 specifically enable it when RMr is initialised. This is
 121 necessary because a second, dedicated, receiver thread must
 122 be started, and requires all messages to be examined and
 123 queued by this thread. The additional overhead is minimal,
 124 queuing information is all in the RMr message header, but as
 125 an additional process is necessary the user application must
 126 "opt in" to this approach.
 127
 128
 129 ENVIRONMENT
 130 --------------------------------------------------------------------------------------------
 131
 132 As a part of the initialisation process rmr_init reads
 133 environment variables to configure itself. The following
 134 variables are used if found.
 135
 136
 137
 138 RMR_ASYNC_CONN
 139
 140   Allows the async connection mode to be turned off (by
 141   setting the value to 0). When set to 1, or missing from
 142   the environment, RMR will invoke the connection interface
 143   in the transport mechanism using the non-blocking (async)
 144   mode. This will likely result in many "soft failures"
 145   (retry) until the connection is established, but allows
 146   the application to continue unimpeded should the
 147   connection be slow to set up.
 148
 149
 150 RMR_BIND_IF
 151
 152   This provides the interface that RMR will bind listen
 153   ports to, allowing for a single interface to be used
 154   rather than listening across all interfaces. This should
 155   be the IP address assigned to the interface that RMR
 156   should listen on, and if not defined RMR will listen on
 157   all interfaces.
 158
 159
 160 RMR_CTL_PORT
 161
 162   This variable defines the port that RMR should open for
 163   communications with Route Manager, and other RMR control
 164   applications. If not defined, the port 4561 is assumed.
 165
 166   Previously, the RMR_RTG_SVC (route table generator service
 167   port) was used to define this port. However, a future
 168   version of Route Manager will require RMR to connect and
 169   request tables, thus that variable is now used to supply
 170   the Route Manager's well-known address and port.
 171
 172   To maintain backwards compatibility with the older Route
 173   Manager versions, the presence of this variable in the
 174   environment will shift RMR's behaviour with respect to the
 175   default value used when RMR_RTG_SVC is **not** defined.
 176
 177   When RMR_CTL_PORT is **defined:** RMR assumes that Route
 178   Manager requires RMR to connect and request table updates
 179   is made, and the default well-known address for Route
 180   manager is used (routemgr:4561).
 181
 182   When RMR_CTL_PORT is **undefined:** RMR assumes that Route
 183   Manager will connect and push table updates, thus the
 184   default listen port (4561) is used.
 185
 186   To avoid any possible misinterpretation and/or incorrect
 187   assumptions on the part of RMR, it is recommended that
 188   both the RMR_CTL_PORT and RMR_RTG_SVC be defined. In the
 189   case where both variables are defined, RMR will behave
 190   exactly as is communicated with the variable's values.
 191
 192
 193 RMR_RTG_SVC
 194
 195   The value of this variable depends on the Route Manager in
 196   use.
 197
 198   When the Route Manager is expecting to connect to an xAPP
 199   and push route tables, this variable must indicate the
 200   port which RMR should use to listen for these connections.
 201
 202   When the Route Manager is expecting RMR to connect and
 203   request a table update during initialisation, the variable
 204   should be the host of the Route Manager process.
 205
 206   The RMR_CTL_PORT variable (added with the support of
 207   sending table update requests to Route manager), controls
 208   the behaviour if this variable is not set. See the
 209   description of that variable for details.
 210
 211
 212 RMR_HR_LOG
 213
 214   By default RMR writes messages to standard error
 215   (incorrectly referred to as log messages) in human
 216   readable format. If this environment variable is set to 0,
 217   the format of standard error messages might be written in
 218   some format not easily read by humans. If missing, a value
 219   of 1 is assumed.
 220
 221
 222 RMR_LOG_VLEVEL
 223
 224   This is a numeric value which corresponds to the verbosity
 225   level used to limit messages written to standard error.
 226   The lower the number the less chatty RMR functions are
 227   during execution. The following is the current
 228   relationship between the value set on this variable and
 229   the messages written:
 230
 231
 232 0
 233
 234   Off; no messages of any sort are written.
 235
 236
 237 1
 238
 239   Only critical messages are written (default if this
 240   variable does not exist)
 241
 242
 243 2
 244
 245   Errors and all messages written with a lower value.
 246
 247
 248 3
 249
 250   Warnings and all messages written with a lower value.
 251
 252
 253 4
 254
 255   Informational and all messages written with a lower
 256   value.
 257
 258
 259 5
 260
 261   Debugging mode -- all messages written, however this
 262   requires RMR to have been compiled with debugging
 263   support enabled.
 264
 265
 266
 267 RMR_RTG_ISRAW
 268
 269   **Deprecated.** Should be set to 1 if the route table
 270   generator is sending "plain" messages (not using RMR to
 271   send messages), 0 if the RTG is using RMR to send. The
 272   default is 1 as we don't expect the RTG to use RMR.
 273
 274   This variable is only recognised when using the NNG
 275   transport library as it is not possible to support NNG
 276   "raw" communications with other transport libraries. It is
 277   also necessary to match the value of this variable with
 278   the capabilities of the Route Manager; at some point in
 279   the future RMR will assume that all Route Manager messages
 280   will arrive via an RMR connection and will ignore this
 281   variable.
 282
 283 RMR_SEED_RT
 284
 285   This is used to supply a static route table which can be
 286   used for debugging, testing, or if no route table
 287   generator process is being used to supply the route table.
 288   If not defined, no static table is used and RMR will not
 289   report *ready* until a table is received. The static route
 290   table may contain both the route table (between newrt
 291   start and end records), and the MEID map (between meid_map
 292   start and end records).
 293
 294 RMR_SRC_ID
 295
 296   This is either the name or IP address which is placed into
 297   outbound messages as the message source. This will used
 298   when an RMR based application uses the rmr_rts_msg()
 299   function to return a response to the sender. If not
 300   supplied RMR will use the hostname which in some container
 301   environments might not be routable.
 302
 303   The value of this variable is also used for Route Manager
 304   messages which are sent via an RMR connection.
 305
 306 RMR_VCTL_FILE
 307
 308   This supplies the name of a verbosity control file. The
 309   core RMR functions do not produce messages unless there is
 310   a critical failure. However, the route table collection
 311   thread, not a part of the main message processing
 312   component, can write additional messages to standard
 313   error. If this variable is set, RMR will extract the
 314   verbosity level for these messages (0 is silent) from the
 315   first line of the file. Changes to the file are detected
 316   and thus the level can be changed dynamically, however RMR
 317   will only suss out this variable during initialisation, so
 318   it is impossible to enable verbosity after startup.
 319
 320 RMR_WARNINGS
 321
 322   If set to 1, RMR will write some warnings which are
 323   non-performance impacting. If the variable is not defined,
 324   or set to 0, RMR will not write these additional warnings.
 325
 326
 327 RETURN VALUE
 328 --------------------------------------------------------------------------------------------
 329
 330 The rmr_init function returns a void pointer (a contex if you
 331 will) that is passed as the first parameter to nearly all
 332 other RMR functions. If rmr_init is unable to properly
 333 initialise the environment, NULL is returned and errno is set
 334 to an appropriate value.
 335
 336 ERRORS
 337 --------------------------------------------------------------------------------------------
 338
 339 The following error values are specifically set by this RMR
 340 function. In some cases the error message of a system call is
 341 propagated up, and thus this list might be incomplete.
 342
 343
 344 ENOMEM
 345
 346   Unable to allocate memory.
 347
 348
 349 EXAMPLE
 350 --------------------------------------------------------------------------------------------
 351
 352
 353 ::
 354
 355     void*  uh;
 356     rmr_mbuf* buf = NULL;
 357     uh = rmr_init( "43086", 4096, 0 );
 358     buf = rmr_rcv_msg( uh, buf );
 359
 360
 361
 362 SEE ALSO
 363 --------------------------------------------------------------------------------------------
 364
 365 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
 366 rmr_get_rcvfd(3), rmr_mt_call(3), rmr_mt_rcv(3),
 367 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
 368 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
 369 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
 370 rmr_ring_free(3)