Merge "Removig committer Chris"

[ric-plt/lib/rmr.git] / doc / src / library / user.xfm

diff --git a/doc/src/library/user.xfm b/doc/src/library/user.xfm
index 6a2371b..a704eec 100644 (file)
--- a/doc/src/library/user.xfm
+++ b/doc/src/library/user.xfm
@@ -1,7 +1,7 @@
 .if false
 ==================================================================================
 .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.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.


@@ -24,69 +24,41 @@
        Author:         E. Scott Daniels
 .fi
 
        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 index_snare_file index_snatch.im
 .im ./setup.im
 
 .** setup will do the right thing with the index configuration
 .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 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
-&center_start
-.sf &bold_font
-&doc_title
-.br
-.st 12
-&doc_subtitle
-&center_end
-.sf &textfont
-&mult_space( 2 )
-.st &textsize
+.** --------------------------------------------------------------------------------------

 
 

+&line_len( &line_size )

 &h1(Overview)
 &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
 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 Routing and endpoint selection is based on &ital(message type.)
        &half_space
 


@@ -96,63 +68,74 @@ The library provides the following major features:
        &li Message distribution (round robin or fanout) is selectable by 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)
 &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)
 
 &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)
 
 &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)
 
 &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)
 
 &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
 
 &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)
 
 
 .** snarf in the major sections (to avoid one huge source document and maybe to promote reuse)


@@ -164,6 +147,7 @@ These modes are discussed in the &ital(Configuration) section of this document.
 
 .if tfm
        .** show all column/foot notes
 
 .if tfm
        .** show all column/foot notes

+       &h1(Notes)

        .cn showend
        &mult_space( 3 )
 .fi
        .cn showend
        &mult_space( 3 )
 .fi


@@ -172,7 +156,14 @@ These modes are discussed in the &ital(Configuration) section of this document.
 
 .dv qr_appendix A
 .pa
 
 .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
 
 .dv mbuf_appendix B
 .pa