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