doc/src/man/rmr.7.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 .if false
  20     Mnemonic    rmr.7.xfm
  21     Abstract    The manual page for the whole RMR library
  22     Author      E. Scott Daniels
  23     Date        29 January 2019
  24 .fi
  25
  26 .gv e LIB lib
  27 .im &{lib}/man/setup.im
  28
  29 &line_len(6i)
  30
  31 &h1(RMR Library)
  32 &h2(NAME)
  33     RMR -- Ric Message Router Library
  34
  35 &h2(DESCRIPTION)
  36 RMR is a library which provides  a user application with the ability
  37 to send and receive messages to/from  other RMR based applications
  38 without having to understand the underlying messaging transport environment (e.g., SI95)
  39 and without needing to know which other endpoint applications are currently
  40 available and accepting messages.
  41 To do this, RMR depends on a routing table generated by an external source.
  42 This table is used to determine the destination endpoint of each message sent by mapping the
  43 message type T (supplied by the user application) to an endpoint entry.
  44 Once determined, the message is sent directly to the endpoint.
  45 The user application is unaware of which endpoint actually receives the
  46 message, and in some cases whether that message was sent to multiple
  47 applications.
  48
  49 &space
  50 RMR functions do provide for the ability to respond to the specific source
  51 instance of a message allowing for either a request response, or call
  52 response relationship when needed.
  53
  54
  55 &h3(The Route Table)
  56 The library must be given a route table which maps message numbers to
  57 endpoint groups such that each time a message of type T is sent, the message
  58 is delivered to one member of each group associated with T.
  59 For example, message type 2 might route to two different groups where
  60 group A consists of worker1 and worker2, while group B consists only of
  61 logger1.
  62
  63 &space
  64 It is the responsibility of the route table generator to know which endpoints
  65 belong to which groups, and which groups accept which message types.
  66 Once understood, the route table generator publishes a table that is ingested
  67 by RMR and used for mapping messages to end points.
  68
  69 .sp
  70 The following is a simple route table which causes message types 0 through 9 to
  71 be routed to specific applications:
  72
  73 &ex_start
  74 newrt|start
  75    mse|0|-1| %meid
  76    mse|1|-1|app10:4560,app11:4560
  77    mse|2|-1|app12:4560
  78    mse|3|-1|app14:4560
  79    mse|4|-1|app18:4560
  80    mse|5|-1|app01:4560
  81    mse|6|-1|app02:4560
  82    mse|7|-1|app03:4560
  83    mse|8|-1|app04:4560
  84    mse|9|-1|app05:4560
  85 newrt|end
  86 &ex_end
  87 &space
  88 The special endpoint "%meid" indicates that the message type (0 in this case) is
  89 to be routed to the endpoint which has been listed as the "owner" for the meid
  90 appearing in the message.
  91 MEID ownership is communicated to RMR using the same Route Table Manager interface
  92 and by supplying a "table" such as the one below:
  93
  94 &ex_start
  95 meid_map | start
  96    mme_ar | control1 | meid000 meid001 meid002 meid003 meid004 meid005
  97    mme_ar | control2 | meid100 meid101 meid102 meid103
  98 meid_map | end | 2
  99 &ex_end
 100
 101 This table indicates that the application (endpoint) &ital(control1) "owns" 6 MEIDs
 102 and &ital(control2) owns 4.
 103 When message type 0 is sent, the MEID in the message will be used to select the
 104 endpoint via this table.
 105
 106 &space
 107 The MEID table will update the existing owner relationships, and add new ones; it
 108 is necessary to send only the changes with the add/replace (mme_ar) entries in
 109 the table.
 110 When necessary, MEIDs can be deleted by adding an &cw(mme_del) record to the table.
 111 The following example illustrates how this might look:
 112
 113 &ex_start
 114 meid_map | start
 115    mme_ar | control1 | meid000 meid001 meid002 meid003 meid004 meid005
 116    mme_ar | control2 | meid100 meid101 meid102 meid103
 117    mme_del| meid200 meid401
 118 meid_map | end | 3
 119 &ex_end
 120
 121 &h3(Route Table Syntax)
 122 The following illustrates the syntax for both the route table.
 123
 124 &space
 125 &ex_start
 126 newrt | start
 127 mse | <message-type>[,<sender-endpoint>] | <sub-id> <roud-robin-grp>[;<round-robin-grp>]...
 128 newrt | end
 129 &ex_end
 130 &space
 131 A round robin group is one or more endpoints from which one will be selected to receive
 132 the message.
 133 When multiple endpoints are given in a group, they must be separated with a comma.
 134 An endpoint is the IP address and port (e.g. 192.158.4.30:8219) or DNS name and port of the
 135 application that should receive the message type.
 136 If multiple round-robin groups are given, they must be separated by a semicolon, and
 137
 138 &h3(MEID Map Syntax)
 139 The MEID map is similar to the route table.
 140 Entries are used to add or replace the ownership of one or more MEIDs (mme_ar) or to
 141 delete one or more MEIDs (mme_del).
 142 The following is the syntax for the MEID map.
 143
 144 &space
 145 &ex_start
 146 meid_map | start
 147 mme_ar | <owner-endpoint> | <meid> [<meid>...]
 148 mme_del | <meid> [<meid>...]
 149 meid_map | end | <count> [| <md5sum>
 150 &ex_end
 151
 152 &space
 153 The <count> on the end record indicates the number of mme_ar and mme_del records
 154 which were sent; if the count does not match the whole map is refused and dropped.
 155 The <owner-endpoint> is the endpoint which should receive the message when a message
 156 is routed based on the MEID it contains.
 157 A MEID may be "owned" by only one endpoint, and if supplied multiple times, the last
 158 observed relationship is used.
 159 Each of the lists of MEIDs are blank separated.
 160
 161 &space
 162 The optional <md5sum> on the &ital(end) record should be the computed MD5 hash for all
 163 records which appear between the start and and records.
 164 This allows for a tighter verification that all data was received exactly as the
 165 route manager transmitted them.
 166
 167
 168 &h3(Environment)
 169 To enable configuration of the library behaviour outside of direct user application
 170 control, RMR supports a number of environment variables which provide information
 171 to the library.
 172 The following is a list of the various environment variables, what they control
 173 and the defaults which RMR uses if undefined.
 174
 175 &space
 176 .** the list of environment vars supported
 177 .im &{lib}/man/env_var_list.im
 178
 179
 180 &h2(SEE ALSO )
 181 .ju off
 182 rmr_alloc_msg(3),
 183 rmr_tralloc_msg(3),
 184 rmr_call(3),
 185 rmr_free_msg(3),
 186 rmr_init(3),
 187 rmr_init_trace(3),
 188 rmr_get_meid(3),
 189 rmr_get_src(3),
 190 rmr_get_srcip(3),
 191 rmr_get_trace(3),
 192 rmr_get_trlen(3),
 193 rmr_get_xact(3),
 194 rmr_payload_size(3),
 195 rmr_rcv_msg(3),
 196 rmr_rcv_specific(3),
 197 rmr_rts_msg(3),
 198 rmr_ready(3),
 199 rmr_fib(3),
 200 rmr_has_str(3),
 201 rmr_tokenise(3),
 202 rmr_mk_ring(3),
 203 rmr_realloc_payload(3),
 204 rmr_ring_free(3),
 205 rmr_set_trace(3),
 206 rmr_torcv_msg(3),
 207 rmr_wh_open(3),
 208 rmr_wh_send_msg(3)
 209 .ju on
 210
 211