.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
Author: E. Scott Daniels
.fi
+.dv textfont Helvetica
+.dv textsize 10p
+.gv e XFM_PASS pass
+
+.** vars picked up by front_junk or gen_title as it's a generic module
+.dv doc_title RIC Message Router -- RMR
+.dv doc_subtitle User's Guide
+.dv orig_date 30 July 2019
+.** must reverse titles when generating rst to disambiguate in the doc list
+.dv reverse_titles 1
+
.** setup will do the right thing with the index configuration
+.dv toc_file user.toc
.dv index_snare_file index_snatch.im
.im ./setup.im
-.** func is a bit odd; if punct needs to be added, it must be supplied as the second
-.** parm because we add () to the first. E.g. &func(foo_bar:.) will add a parm
-.**
-.dv func .ix force ${1} ^: ^&cw(${1}()$2 )
-
.dv mtsid message type and subscription ID
.dv Mtsid Message type and subscription ID
.dv mt message type
.dv Mt Message type
.dv mts message types
-.dv textfont Helvetica
-.dv textsize 10p
-.hn off
-
-
-.gv e XFM_PASS pass
-.if &pass 2 =
- .** two pass mode -- pull in variables captured during pass 1 for forward references
- .im p1var_setup.ca
-.fi
-
-.** vars picked up by front_junk as it's a generic module
-.dv doc_title RIC Message Router -- RMR
-.dv doc_subtitle User's Manual
-
-.if pfm
- .** add licence, a title page, and talbe of contents
- .im front_junk.im
-.ei
- .** for text based things, nothing more than license
- .im license.im
-.fi
-
-.if pfm
- .pn on noline center f=%d 0
-.fi
-
-&mult_space( 5 )
-.st 18
-¢er_start
-.sf &bold_font
-&doc_title
-.br
-.st 12
-&doc_subtitle
-¢er_end
-.sf &textfont
-&mult_space( 2 )
-.st &textsize
+.** --------------------------------------------------------------------------------------
+&line_len( &line_size )
&h1(Overview)
-The RIC Message Router (a.k.a. RMR) is a thin library which provides a latency sensitive application with the ability
-to send and receive messages with other RMR based applications.
+
+The RIC Message Router (RMR) is a library for peer-to-peer
+communication. Applications use the library to send and receive
+messages where the message routing and endpoint selection is based on
+the message type rather than DNS host name-IP port combinations.
The library provides the following major features:
&half_space
&indent
-&beg_list( &lic1 )
+&beg_list(&lic1)
&li Routing and endpoint selection is based on &ital(message type.)
&half_space
&li Message distribution (round robin or fanout) is selectable by message type.
&half_space
- &li Route management updates are received and processed asynchronously and without overt
- application involvement.
+ &li Route management updates are received and processed
+ asynchronously and without overt application involvement.
&end_list
&uindent
&space
&h2(Purpose)
-RMR's main purpose is to provide an application with the ability to send and receive messages to/from other
-peer applications with minimal effort on the application's part.
-To achieve this, RMR manages manages all endpoint information, connections, and routing information necessary
-to establish and maintain communication.
-From the application's point of view, all that is required to send a message is to allocate (via RMR) a message
-buffer, add the payload data, and set the message type.
-To receive a message, the application needs only to invoke the receive function; when a message
-arrives a message buffer will be returned as the function result.
-
+RMR's main purpose is to provide an application with the ability to
+send and receive messages to/from other peer applications with minimal
+effort on the application's part. To achieve this, RMR manages all
+endpoint information, connections, and routing information necessary
+to establish and maintain communication. From the application's point
+of view, all that is required to send a message is to allocate (via
+RMR) a message buffer, add the payload data, and set the message type.
+To receive a message, the application needs only to invoke the receive
+function; when a message arrives a message buffer will be returned as
+the function result.
&h2(Message Routing)
-Applications are required to place a message type into a message before sending, and may optionally add a
-subscription ID when appropriate.
-The combination of message type, and subscription ID are refered to as the &ital(message key,)
-and is used to match an entry in a routing table which provides the possible endpoints expecting
-to receive messages with the matching key.
+Applications are required to place a message type into a message
+before sending, and may optionally add a subscription ID when
+appropriate. The combination of message type, and subscription ID are
+refered to as the &ital(message key,) and is used to match an entry in
+a routing table which provides the possible endpoints expecting to
+receive messages with the matching key.
&h3(Round Robin Delivery)
-An endpoint from RMR's perspective is an application to which RMR may establish a connection, and expect to
-send messages with one or more defined message keys.
-Each entry in the route table consists of one or more endpoint groups, called round robin groups.
-When a message matches a specific entry, the entry's groups are used to select the destination of the message.
-A message is sent once to each group, with messages being &ital(balanced) across the endpoints of a group
-via round robin selection.
-Care should be taken when defining multiple groups for a message type as there is extra overhead required
-and thus the overall message latency is somewhat reduced.
+An endpoint from RMR's perspective is an application to which RMR may
+establish a connection, and expect to send messages with one or more
+defined message keys. Each entry in the route table consists of one
+or more endpoint groups, called round robin groups. When a message
+matches a specific entry, the entry's groups are used to select the
+destination of the message. A message is sent once to each group,
+with messages being &ital(balanced) across the endpoints of a group
+via round robin selection. Care should be taken when defining
+multiple groups for a message type as there is extra overhead required
+and thus the overall message latency is somewhat increased.
&h3(Routing Table Updates)
-Route table information is made available to RMR a static file (loaded once), or by updates sent from a
-separate route manager application.
-If a static table is provided, it is loaded during RMR initialisation and will remain in use until
-an external process connects and delivers a route table update (often referred to as a dynamic update).
-Dynamic updates are listened for in a separate process thread and applied automatically; the application does not
-need to allow for, or trigger, updates.
+Route table information is made available to RMR a static file (loaded
+once), or by updates sent from a separate route manager application.
+If a static table is provided, it is loaded during RMR initialization
+and will remain in use until an external process connects and delivers
+a route table update (often referred to as a dynamic update). Dynamic
+updates are listened for in a separate process thread and applied
+automatically; the application does not need to allow for, or trigger,
+updates.
&h2(Latency And Throughput)
-While providing insulation from the underlying message transport mechanics, RMR must also do so in such a
-manner that message latency and throughput are not impacted.
-In general, the RMR induced overhead, incurred due to the process of selecting an endpoint for each message,
-is minimal and should not impact the overall latency or throughput of the application.
-This impact has been measured with test applications running on the same physical host and the average
-latency through RMR for a message was on the order of 0.02 milliseconds.
+While providing insulation from the underlying message transport
+mechanics, RMR must also do so in such a manner that message latency
+and throughput are not impacted. In general, the RMR induced
+overhead, incurred due to the process of selecting an endpoint for
+each message, is minimal and should not impact the overall latency or
+throughput of the application. This impact has been measured with
+test applications running on the same physical host and the average
+latency through RMR for a message was on the order of 0.02
+milliseconds.
&space
-As an application's throughput increases, it becomes easy for the application to overrun the underlying
-transport mechanism (e.g. NNG), consume all available TCP transmit buffers, or otherwise find itself
-in a situation where a send might not immediately complete.
-RMR offers different &ital(modes) which allow the application to manage these states based on the
-overall needs of the application.
-These modes are discussed in the &ital(Configuration) section of this document.
+As an application's throughput increases, it becomes easy for the
+application to overrun the underlying transport mechanism (e.g. NNG),
+consume all available TCP transmit buffers, or otherwise find itself
+in a situation where a send might not immediately complete. RMR
+offers different &ital(modes) which allow the application to manage
+these states based on the overall needs of the application. These
+modes are discussed in the &ital(Configuration) section of this
+document.
.** snarf in the major sections (to avoid one huge source document and maybe to promote reuse)
.if tfm
.** show all column/foot notes
+ &h1(Notes)
.cn showend
&mult_space( 3 )
.fi
.dv qr_appendix A
.pa
-.im api_qref.im
+.if "&ot" "rst" =
+&h1(Appendix &qr_appendix -- Quick Reference)
+ Please refer to the RMR manual pages on the Read the Docs site
+ &space
+ https://docs.o-ran-sc.org/projects/o-ran-sc-ric-plt-lib-rmr/en/latest/index.html
+.ei
+ .im api_qref.im
+.fi
.dv mbuf_appendix B
.pa
Code Review / ric-plt / lib / rmr.git / blobdiff