doc/src/library/user.xfm

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