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 talbe 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 The RIC Message Router (a.k.a. RMR) is a thin library which provides a latency sensitive application with the ability
  84 to send and receive messages with other RMR based applications.
  85 The library provides the following major features:
  86
  87 &half_space
  88 &indent
  89 &beg_list( &lic1 )
  90         &li Routing and endpoint selection is based on &ital(message type.)
  91         &half_space
  92
  93         &li Application is insulated from the underlying transport mechanism and/or protocols.
  94         &half_space
  95
  96         &li Message distribution (round robin or fanout) is selectable by message type.
  97         &half_space
  98
  99         &li Route management updates are received and processed asynchronously and without overt
 100                 application involvement.
 101 &end_list
 102 &uindent
 103
 104 &space
 105 &h2(Purpose)
 106 RMR's main purpose is to provide an application with the ability to send and receive messages to/from other
 107 peer applications with minimal effort on the application's part.
 108 To achieve this, RMR manages manages all endpoint information, connections, and routing information necessary
 109 to establish and maintain communication.
 110 From the application's point of view, all that is required to send a message is to allocate (via RMR) a message
 111 buffer, add the payload data, and set the message type.
 112 To receive a message, the application needs only to invoke the receive function; when a message
 113 arrives a message buffer will be returned as the function result.
 114
 115
 116 &h2(Message Routing)
 117 Applications are required to place a message type into a message before sending, and may optionally add a
 118 subscription ID when appropriate.
 119 The combination of message type, and subscription ID are refered to as the &ital(message key,)
 120 and is used to match an entry in a routing table which provides the possible endpoints expecting
 121 to receive messages with the matching key.
 122
 123 &h3(Round Robin Delivery)
 124 An endpoint from RMR's perspective is an application to which RMR may establish a connection, and expect to
 125 send messages with one or more defined message keys.
 126 Each entry in the route table consists of one or more endpoint groups, called round robin groups.
 127 When a message matches a specific entry, the entry's  groups are used to select the destination of the message.
 128 A message is sent once to each group, with messages being &ital(balanced) across the endpoints of a group
 129 via round robin selection.
 130 Care should be taken when defining multiple groups for a message type as there is extra overhead required
 131 and thus the overall message latency is somewhat reduced.
 132
 133 &h3(Routing Table Updates)
 134 Route table information is made available  to RMR a static file (loaded once), or by updates sent from a
 135 separate route manager application.
 136 If a static table is provided, it is loaded during RMR initialisation and will remain in use until
 137 an external process connects and delivers a route table update (often referred to as a dynamic update).
 138 Dynamic updates are listened for in a separate process thread and applied automatically; the application does not
 139 need to allow for, or trigger, updates.
 140
 141 &h2(Latency And Throughput)
 142 While providing insulation from the underlying message transport mechanics, RMR must also do so in such a
 143 manner that message latency and throughput are not impacted.
 144 In general, the RMR induced overhead, incurred due to the process of selecting an endpoint for each message,
 145 is minimal and should not impact the overall latency or throughput of the application.
 146 This impact has been measured with test applications running on the same physical host and the average
 147 latency through RMR for a message was on the order of 0.02 milliseconds.
 148
 149 &space
 150 As an application's throughput increases, it becomes easy for the application to overrun the underlying
 151 transport mechanism (e.g. NNG), consume all available TCP transmit buffers, or otherwise find itself
 152 in a situation where a send might not immediately complete.
 153 RMR offers different &ital(modes) which allow the application to manage these states based on the
 154 overall needs of the application.
 155 These modes are discussed in the &ital(Configuration) section of this document.
 156
 157
 158 .** snarf in the major sections (to avoid one huge source document and maybe to promote reuse)
 159 .im general_use.im
 160 .im advanced_use.im
 161 .im failures.im
 162 .im config.im
 163
 164
 165 .if tfm
 166         .** show all column/foot notes
 167         .cn showend
 168         &mult_space( 3 )
 169 .fi
 170
 171
 172
 173 .dv qr_appendix A
 174 .pa
 175 .im api_qref.im
 176
 177 .dv mbuf_appendix B
 178 .pa
 179 .im mbuf.im
 180
 181 .dv gloss_appendix C
 182 .pa
 183 .im glossary.im
 184
 185 .dv code_appendix D
 186 .pa
 187 .im code_appendix.im
 188
 189 .** if pfm and index was setup, include it now
 190 .if index_here
 191         .st 8p
 192         &index_here
 193         .st &textsize
 194 .fi
 195 .pa
 196
 197 .** capture all interesting variables to be used as forward references during pass 2
 198 .ca expand start p1var_setup.ca
 199         .** pass 1 variable settings -- do NOT commit to repo
 200
 201         .dv qr_appendix &qr_appendix
 202         .dv mbuf_appendix &mbuf_appendix
 203         .dv gloss_appendix &gloss_appendix
 204         .dv code_appendix &code_appendix
 205 .ca end
 206
 207 .qu
 208 glossary:
 209 context
 210 endpoint
 211 mt/sid
 212 NNG
 213 push back
 214 route table