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)