doc/src/library/user.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:       user.xfm
  22         Abstract:       This is the main module for the base RMR user documentation.
  23         Date:           30 July 2019
  24         Author:         E. Scott Daniels
  25 .fi
  26
  27 .** setup will do the right thing with the index configuration
  28 .dv index_snare_file index_snatch.im
  29 .im ./setup.im
  30
  31 .** func is a bit odd; if punct needs to be added, it must be supplied as the second
  32 .** parm because we add () to the first. E.g. &func(foo_bar:.) will add a parm
  33 .**
  34 .dv func .ix force ${1} ^:  ^&cw(${1}()$2 )
  35
  36 .dv mtsid message type and subscription ID
  37 .dv Mtsid Message type and subscription ID
  38 .dv mt message type
  39 .dv Mt Message type
  40 .dv mts message types
  41
  42 .dv textfont Helvetica
  43 .dv textsize 10p
  44 .hn off
  45
  46
  47 .gv e XFM_PASS pass
  48 .if &pass 2 =
  49         .** two pass mode -- pull in variables captured during pass 1 for forward references
  50         .im p1var_setup.ca
  51 .fi
  52
  53 .** vars picked up by front_junk as it's a generic module
  54 .dv doc_title RIC Message Router -- RMR
  55 .dv doc_subtitle User's Manual
  56
  57 .if pfm
  58         .** add licence,  a title page, and table of contents
  59         .im front_junk.im
  60 .ei
  61         .** for text based things, nothing more than license
  62         .im license.im
  63 .fi
  64
  65 .if pfm
  66         .pn on noline center f=%d 0
  67 .fi
  68
  69 &mult_space( 5 )
  70 .st 18
  71 &center_start
  72 .sf &bold_font
  73 &doc_title
  74 .br
  75 .st 12
  76 &doc_subtitle
  77 &center_end
  78 .sf &textfont
  79 &mult_space( 2 )
  80 .st &textsize
  81
  82 &h1(Overview)
  83
  84 The RIC Message Router (RMR) is a library for peer-to-peer
  85 communication.  Applications use the library to send and receive
  86 messages where the message routing and endpoint selection is based on
  87 the message type rather than DNS host name-IP port combinations.
  88 The library provides the following major features:
  89
  90 &half_space
  91 &indent
  92 &beg_list( &lic1 )
  93         &li Routing and endpoint selection is based on &ital(message type.)
  94         &half_space
  95
  96         &li Application is insulated from the underlying transport mechanism and/or protocols.
  97         &half_space
  98
  99         &li Message distribution (round robin or fanout) is selectable by message type.
 100         &half_space
 101
 102         &li Route management updates are received and processed
 103                 asynchronously and without overt application involvement.
 104 &end_list
 105 &uindent
 106
 107 &space
 108 &h2(Purpose)
 109 RMR's main purpose is to provide an application with the ability to
 110 send and receive messages to/from other peer applications with minimal
 111 effort on the application's part.  To achieve this, RMR manages all
 112 endpoint information, connections, and routing information necessary
 113 to establish and maintain communication.  From the application's point
 114 of view, all that is required to send a message is to allocate (via
 115 RMR) a message buffer, add the payload data, and set the message type.
 116 To receive a message, the application needs only to invoke the receive
 117 function; when a message arrives a message buffer will be returned as
 118 the function result.
 119
 120 &h2(Message Routing)
 121 Applications are required to place a message type into a message
 122 before sending, and may optionally add a subscription ID when
 123 appropriate.  The combination of message type, and subscription ID are
 124 refered to as the &ital(message key,) and is used to match an entry in
 125 a routing table which provides the possible endpoints expecting to
 126 receive messages with the matching key.
 127
 128 &h3(Round Robin Delivery)
 129 An endpoint from RMR's perspective is an application to which RMR may
 130 establish a connection, and expect to send messages with one or more
 131 defined message keys.  Each entry in the route table consists of one
 132 or more endpoint groups, called round robin groups.  When a message
 133 matches a specific entry, the entry's groups are used to select the
 134 destination of the message.  A message is sent once to each group,
 135 with messages being &ital(balanced) across the endpoints of a group
 136 via round robin selection.  Care should be taken when defining
 137 multiple groups for a message type as there is extra overhead required
 138 and thus the overall message latency is somewhat increased.
 139
 140 &h3(Routing Table Updates)
 141 Route table information is made available to RMR a static file (loaded
 142 once), or by updates sent from a separate route manager application.
 143 If a static table is provided, it is loaded during RMR initialization
 144 and will remain in use until an external process connects and delivers
 145 a route table update (often referred to as a dynamic update).  Dynamic
 146 updates are listened for in a separate process thread and applied
 147 automatically; the application does not need to allow for, or trigger,
 148 updates.
 149
 150 &h2(Latency And Throughput)
 151 While providing insulation from the underlying message transport
 152 mechanics, RMR must also do so in such a manner that message latency
 153 and throughput are not impacted.  In general, the RMR induced
 154 overhead, incurred due to the process of selecting an endpoint for
 155 each message, is minimal and should not impact the overall latency or
 156 throughput of the application.  This impact has been measured with
 157 test applications running on the same physical host and the average
 158 latency through RMR for a message was on the order of 0.02
 159 milliseconds.
 160
 161 &space
 162 As an application's throughput increases, it becomes easy for the
 163 application to overrun the underlying transport mechanism (e.g. NNG),
 164 consume all available TCP transmit buffers, or otherwise find itself
 165 in a situation where a send might not immediately complete.  RMR
 166 offers different &ital(modes) which allow the application to manage
 167 these states based on the overall needs of the application.  These
 168 modes are discussed in the &ital(Configuration) section of this
 169 document.
 170
 171
 172 .** snarf in the major sections (to avoid one huge source document and maybe to promote reuse)
 173 .im general_use.im
 174 .im advanced_use.im
 175 .im failures.im
 176 .im config.im
 177
 178
 179 .if tfm
 180         .** show all column/foot notes
 181         .cn showend
 182         &mult_space( 3 )
 183 .fi
 184
 185
 186
 187 .dv qr_appendix A
 188 .pa
 189 .im api_qref.im
 190
 191 .dv mbuf_appendix B
 192 .pa
 193 .im mbuf.im
 194
 195 .dv gloss_appendix C
 196 .pa
 197 .im glossary.im
 198
 199 .dv code_appendix D
 200 .pa
 201 .im code_appendix.im
 202
 203 .** if pfm and index was setup, include it now
 204 .if index_here
 205         .st 8p
 206         &index_here
 207         .st &textsize
 208 .fi
 209 .pa
 210
 211 .** capture all interesting variables to be used as forward references during pass 2
 212 .ca expand start p1var_setup.ca
 213         .** pass 1 variable settings -- do NOT commit to repo
 214
 215         .dv qr_appendix &qr_appendix
 216         .dv mbuf_appendix &mbuf_appendix
 217         .dv gloss_appendix &gloss_appendix
 218         .dv code_appendix &code_appendix
 219 .ca end
 220
 221 .qu
 222 glossary:
 223 context
 224 endpoint
 225 mt/sid
 226 NNG
 227 push back
 228 route table