2 ==================================================================================
3 Copyright (c) 2019-2020 Nokia
4 Copyright (c) 2018-2020 AT&T Intellectual Property.
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
10 http://www.apache.org/licenses/LICENSE-2.0
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 ==================================================================================
22 Abstract: This is the main module for the base RMR user documentation.
24 Author: E. Scott Daniels
27 .dv textfont Helvetica
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
38 .** setup will do the right thing with the index configuration
39 .dv index_snare_file index_snatch.im
42 .dv mtsid message type and subscription ID
43 .dv Mtsid Message type and subscription ID
48 .** --------------------------------------------------------------------------------------
50 &line_len( &line_size )
53 The RIC Message Router (RMR) is a library for peer-to-peer
54 communication. Applications use the library to send and receive
55 messages where the message routing and endpoint selection is based on
56 the message type rather than DNS host name-IP port combinations.
57 The library provides the following major features:
62 &li Routing and endpoint selection is based on &ital(message type.)
65 &li Application is insulated from the underlying transport mechanism and/or protocols.
68 &li Message distribution (round robin or fanout) is selectable by message type.
71 &li Route management updates are received and processed
72 asynchronously and without overt application involvement.
78 RMR's main purpose is to provide an application with the ability to
79 send and receive messages to/from other peer applications with minimal
80 effort on the application's part. To achieve this, RMR manages all
81 endpoint information, connections, and routing information necessary
82 to establish and maintain communication. From the application's point
83 of view, all that is required to send a message is to allocate (via
84 RMR) a message buffer, add the payload data, and set the message type.
85 To receive a message, the application needs only to invoke the receive
86 function; when a message arrives a message buffer will be returned as
90 Applications are required to place a message type into a message
91 before sending, and may optionally add a subscription ID when
92 appropriate. The combination of message type, and subscription ID are
93 refered to as the &ital(message key,) and is used to match an entry in
94 a routing table which provides the possible endpoints expecting to
95 receive messages with the matching key.
97 &h3(Round Robin Delivery)
98 An endpoint from RMR's perspective is an application to which RMR may
99 establish a connection, and expect to send messages with one or more
100 defined message keys. Each entry in the route table consists of one
101 or more endpoint groups, called round robin groups. When a message
102 matches a specific entry, the entry's groups are used to select the
103 destination of the message. A message is sent once to each group,
104 with messages being &ital(balanced) across the endpoints of a group
105 via round robin selection. Care should be taken when defining
106 multiple groups for a message type as there is extra overhead required
107 and thus the overall message latency is somewhat increased.
109 &h3(Routing Table Updates)
110 Route table information is made available to RMR a static file (loaded
111 once), or by updates sent from a separate route manager application.
112 If a static table is provided, it is loaded during RMR initialization
113 and will remain in use until an external process connects and delivers
114 a route table update (often referred to as a dynamic update). Dynamic
115 updates are listened for in a separate process thread and applied
116 automatically; the application does not need to allow for, or trigger,
119 &h2(Latency And Throughput)
120 While providing insulation from the underlying message transport
121 mechanics, RMR must also do so in such a manner that message latency
122 and throughput are not impacted. In general, the RMR induced
123 overhead, incurred due to the process of selecting an endpoint for
124 each message, is minimal and should not impact the overall latency or
125 throughput of the application. This impact has been measured with
126 test applications running on the same physical host and the average
127 latency through RMR for a message was on the order of 0.02
131 As an application's throughput increases, it becomes easy for the
132 application to overrun the underlying transport mechanism (e.g. NNG),
133 consume all available TCP transmit buffers, or otherwise find itself
134 in a situation where a send might not immediately complete. RMR
135 offers different &ital(modes) which allow the application to manage
136 these states based on the overall needs of the application. These
137 modes are discussed in the &ital(Configuration) section of this
141 .** snarf in the major sections (to avoid one huge source document and maybe to promote reuse)
149 .** show all column/foot notes
160 &h1(Appendix &qr_appendix -- Quick Reference)
161 Please refer to the RMR manual pages on the Read the Docs site
163 https://docs.o-ran-sc.org/projects/o-ran-sc-ric-plt-lib-rmr/en/latest/index.html
180 .** if pfm and index was setup, include it now
188 .** capture all interesting variables to be used as forward references during pass 2
189 .ca expand start p1var_setup.ca
190 .** pass 1 variable settings -- do NOT commit to repo
192 .dv qr_appendix &qr_appendix
193 .dv mbuf_appendix &mbuf_appendix
194 .dv gloss_appendix &gloss_appendix
195 .dv code_appendix &code_appendix