docs/rmr_init.3.rst

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