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_RTG_SVC**
 202         -
 203           The value of this variable depends on the Route Manager in
 204           use.
 205
 206           When the Route Manager is expecting to connect to an xAPP and
 207           push route tables, this variable must indicate the
 208           ``port`` which RMR should use to listen for these
 209           connections.
 210
 211           When the Route Manager is expecting RMR to connect and
 212           request a table update during initialisation, the variable
 213           should be the ``host`` of the Route Manager process.
 214
 215           The ``RMR_CTL_PORT`` variable (added with the support of
 216           sending table update requests to Route manager), controls the
 217           behaviour if this variable is not set. See the description of
 218           that variable for details.
 219
 220       * - **RMR_HR_LOG**
 221         -
 222           By default RMR writes messages to standard error (incorrectly
 223           referred to as log messages) in human readable format. If
 224           this environment variable is set to 0, the format of standard
 225           error messages might be written in some format not easily
 226           read by humans. If missing, a value of 1 is assumed.
 227
 228       * - **RMR_LOG_VLEVEL**
 229         -
 230           This is a numeric value which corresponds to the verbosity
 231           level used to limit messages written to standard error. The
 232           lower the number the less chatty RMR functions are during
 233           execution. The following is the current relationship between
 234           the value set on this variable and the messages written:
 235
 236
 237               .. list-table::
 238                 :widths: auto
 239                 :header-rows: 0
 240                 :class: borderless
 241
 242                 * - **0**
 243                   -
 244                     Off; no messages of any sort are written.
 245
 246                 * - **1**
 247                   -
 248                     Only critical messages are written (default if this variable
 249                     does not exist)
 250
 251                 * - **2**
 252                   -
 253                     Errors and all messages written with a lower value.
 254
 255                 * - **3**
 256                   -
 257                     Warnings and all messages written with a lower value.
 258
 259                 * - **4**
 260                   -
 261                     Informational and all messages written with a lower value.
 262
 263                 * - **5**
 264                   -
 265                     Debugging mode -- all messages written, however this requires
 266                     RMR to have been compiled with debugging support enabled.
 267
 268
 269
 270       * - **RMR_RTG_ISRAW**
 271         -
 272           **Deprecated.** Should be set to 1 if the route table
 273           generator is sending "plain" messages (not using RMR to send
 274           messages), 0 if the RTG is using RMR to send. The default is
 275           1 as we don't expect the RTG to use RMR.
 276
 277           This variable is only recognised when using the NNG transport
 278           library as it is not possible to support NNG "raw"
 279           communications with other transport libraries. It is also
 280           necessary to match the value of this variable with the
 281           capabilities of the Route Manager; at some point in the
 282           future RMR will assume that all Route Manager messages will
 283           arrive via an RMR connection and will ignore this variable.
 284
 285       * - **RMR_SEED_RT**
 286         -
 287           This is used to supply a static route table which can be used
 288           for debugging, testing, or if no route table generator
 289           process is being used to supply the route table. If not
 290           defined, no static table is used and RMR will not report
 291           *ready* until a table is received. The static route table may
 292           contain both the route table (between newrt start and end
 293           records), and the MEID map (between meid_map start and end
 294           records).
 295
 296       * - **RMR_SRC_ID**
 297         -
 298           This is either the name or IP address which is placed into
 299           outbound messages as the message source. This will used when
 300           an RMR based application uses the rmr_rts_msg() function to
 301           return a response to the sender. If not supplied RMR will use
 302           the hostname which in some container environments might not
 303           be routable.
 304
 305           The value of this variable is also used for Route Manager
 306           messages which are sent via an RMR connection.
 307
 308       * - **RMR_VCTL_FILE**
 309         -
 310           This supplies the name of a verbosity control file. The core
 311           RMR functions do not produce messages unless there is a
 312           critical failure. However, the route table collection thread,
 313           not a part of the main message processing component, can
 314           write additional messages to standard error. If this variable
 315           is set, RMR will extract the verbosity level for these
 316           messages (0 is silent) from the first line of the file.
 317           Changes to the file are detected and thus the level can be
 318           changed dynamically, however RMR will only suss out this
 319           variable during initialisation, so it is impossible to enable
 320           verbosity after startup.
 321
 322       * - **RMR_WARNINGS**
 323         -
 324           If set to 1, RMR will write some warnings which are
 325           non-performance impacting. If the variable is not defined, or
 326           set to 0, RMR will not write these additional warnings.
 327
 328
 329
 330
 331 RETURN VALUE
 332 ------------
 333
 334 The ``rmr_init`` function returns a void pointer (a context
 335 if you will) that is passed as the first parameter to nearly
 336 all other RMR functions. If ``rmr_init`` is unable to
 337 properly initialise the environment, NULL is returned and
 338 errno is set to an appropriate value.
 339
 340
 341 ERRORS
 342 ------
 343
 344 The following error values are specifically set by this RMR
 345 function. In some cases the error message of a system call is
 346 propagated up, and thus this list might be incomplete.
 347
 348     .. list-table::
 349       :widths: auto
 350       :header-rows: 0
 351       :class: borderless
 352
 353       * - **ENOMEM**
 354         -
 355           Unable to allocate memory.
 356
 357
 358
 359
 360 EXAMPLE
 361 -------
 362
 363
 364 ::
 365
 366      void*  uh;
 367      rmr_mbuf* buf = NULL;
 368
 369      uh = rmr_init( "43086", 4096, 0 );
 370      buf = rmr_rcv_msg( uh, buf );
 371
 372
 373
 374 SEE ALSO
 375 --------
 376
 377 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
 378 rmr_get_rcvfd(3), rmr_mt_call(3), rmr_mt_rcv(3),
 379 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
 380 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
 381 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
 382 rmr_ring_free(3)