doc/src/man/rmr_init.3.xfm

   1 .if false
   2 ==================================================================================
   3         Copyright (c) 2019 Nokia
   4         Copyright (c) 2018-2019 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 .** if formatting with tfm, the roff.im will cause roff output to be generated
  28 .** if formatting with pfm, then pretty postscript will be generated
  29 .gv e LIB lib
  30 .if pfm
  31         .im &{lib}/generic_ps.im
  32 .ei
  33         .gv e OUTPUT_RST use_rst
  34         .if .ev &use_rst 1 =
  35                 .im &{lib}/rst.im
  36         .ei
  37                 .im &{lib}/roff.im
  38         .fi
  39 .fi
  40
  41 &line_len(6i)
  42
  43 &h1(RMR Library Functions)
  44 &h2(NAME)
  45         rmr_init
  46
  47 &h2(SYNOPSIS)
  48 &indent
  49 &ex_start
  50 #include <rmr/rmr.h>
  51
  52 void* rmr_init( char* proto_port, int max_msg_size, int flags );
  53 &ex_end
  54
  55 &uindent
  56
  57 &h2(DESCRIPTION)
  58 The &cw(rmr_init) function prepares the environment for sending and receiving messages.
  59 It does so by establishing a worker thread (pthread) which subscribes to a route table
  60 generator which provides the necessary routing information for the RMR library to
  61 send messages.
  62
  63 &space
  64 &ital(Port) is used to listen for connection requests from other RMR based applications.
  65 The value of &ital(max_msg_size) will be used when allocating zero copy send buffers
  66 which must be allocated, possibly, prior to the application knowing the actual size of
  67 a specific message.
  68
  69 &space
  70 &ital(Flags) allows for selection of some RMr options at the time of initialisation.
  71 These are set by ORing &cw(RMRFL_) constants from the RMr header file. Currently the
  72 following flags are supported:
  73
  74 &half_space
  75 &beg_dlist(1i : &bold_font )
  76 &ditem(RMRFL_NONE)
  77         No flags are set.
  78
  79 &half_space
  80 &ditem(RMRFL_NOTHREAD)
  81         The route table collector thread is not to be started. This should only be used
  82         by the route table generator application if it is based on RMr.
  83
  84 &half_space
  85 &ditem(RMRFL_MTCALL)
  86         Enable multi-threaded call support.
  87 &end_dlist
  88
  89 &h3(Multi-threaded Calling)
  90 The support for an application to issue a &ital(blocking call) by the &cw(rmr_call()) function
  91 was limited such that only user applications which were operating in a single thread
  92 could safely use the function.
  93 Further, timeouts were message count based and not time unit based.
  94 Multi-threaded call support adds the ability for a user application with multiple threads
  95 to invoke a blocking call function with the guarentee that the correct response message
  96 is delivered to the thread.
  97 The additional support is implemented with the &ital( rmr_mt_call() ) and &ital( rmr_mt_rcv() )
  98 function calls.
  99 &space
 100
 101 Multi-threaded call support requires the user application to specifically enable it
 102 when RMr is initialised.
 103 This is necessary because a second, dedicated, receiver thread  must be started, and
 104 requires all messages to be examined and queued by this thread.
 105 The additional overhead is minimal, queuing information is all in the RMr message
 106 header, but as an additional process is necessary the user application must "opt in"
 107 to this approach.
 108
 109 &space
 110 &h2(ENVIRONMENT)
 111 As a part of the initialisation process &cw(rmr_init) will look into the available
 112 environment variables to influence it's setup.
 113 The following variables will be used when found.
 114 &half_space
 115
 116 &beg_dlist(1i : &bold_font )
 117 &ditem(RMR_SEED_RT)
 118 Assumes this is the filename of the seed route table file to use. In normal situations,
 119 the library will wait for an update from the route table generator (expected within a few seconds
 120 of initialisation) before being able to send messages.
 121 However, in some situations where a bootstrap table is necessary, this is the means to
 122 supply it to the library.
 123 &half_space
 124
 125 &ditem(RMR_RTG_SVC)
 126 The route table generator assumes that RMr is listening on a well known port (4561) by
 127 default, but this environment variable can be used to change the listening port if
 128 needed.
 129 The value of the variable is expected to be just the port.
 130 &end_dlist
 131
 132 &h2(RETURN VALUE)
 133 The &cw(rmr_init) function returns a void pointer (a contex if you will) that is passed
 134 as the first parameter to nearly all other RMR functions.
 135 If &cw(rmr_init) is unable to properly initialise the environment, NULL is returned and
 136 errno is set to an appropriate value.
 137
 138 &h2(ERRORS)
 139 The following error values are specifically set by this RMR function. In some cases the
 140 error message of a system call is propagated up, and thus this list might be incomplete.
 141
 142 &beg_dlist(.75i : ^&bold_font )
 143 &di(ENOMEM) Unable to allocate memory.
 144 &end_dlist
 145
 146 &h2(EXAMPLE)
 147 &ex_start
 148    void*  uh;
 149    rmr_mbuf* buf = NULL;
 150
 151    uh = rmr_init( "43086", 4096, 0 );
 152    buf = rmr_rcv_msg( uh, buf );
 153 &ex_end
 154
 155 &h2(SEE ALSO )
 156 rmr_alloc_msg(3),
 157 rmr_call(3),
 158 rmr_free_msg(3),
 159 rmr_get_rcvfd(3),
 160 rmr_mt_call(3),
 161 rmr_mt_rcv(3),
 162 rmr_payload_size(3),
 163 rmr_send_msg(3),
 164 rmr_rcv_msg(3),
 165 rmr_rcv_specific(3),
 166 rmr_rts_msg(3),
 167 rmr_ready(3),
 168 rmr_fib(3),
 169 rmr_has_str(3),
 170 rmr_tokenise(3),
 171 rmr_mk_ring(3),
 172 rmr_ring_free(3)
 173
 174
 175 .qu
 176