X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=docs%2Foverview.rst;h=f4454be078d0138fb74277769104432c5838f7ed;hb=refs%2Ftags%2F4.0.5;hp=8168b9f90785edb7598eeb2cd82d5ab586180b04;hpb=5157a97ada5447efcee4da6192798a3b6799884c;p=ric-plt%2Flib%2Frmr.git diff --git a/docs/overview.rst b/docs/overview.rst old mode 100755 new mode 100644 index 8168b9f..f4454be --- a/docs/overview.rst +++ b/docs/overview.rst @@ -1,4 +1,5 @@ + .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. SPDX-License-Identifier: CC-BY-4.0 .. CAUTION: this document is generated from source in doc/src/rtd. @@ -6,28 +7,29 @@ .. Do NOT make changes directly to .rst or .md files. + RMR Overview ============================================================================================ -RMr Library +RMR Library ============================================================================================ NAME -------------------------------------------------------------------------------------------- -RMr -- Ric Message Router Library +RMR -- Ric Message Router Library DESCRIPTION -------------------------------------------------------------------------------------------- -RMr is a library which provides a user application with the -ability to send and receive messages to/from other RMr based +RMR is a library which provides a user application with the +ability to send and receive messages to/from other RMR based applications without having to understand the underlying messaging transport environment (e.g., SI95) and without needing to know which other endpoint applications are -currently available and accepting messages. To do this, RMr +currently available and accepting messages. To do this, RMR depends on a routing table generated by an external source. This table is used to determine the destination endpoint of each message sent by mapping the message type T (supplied by @@ -37,24 +39,56 @@ application is unaware of which endpoint actually receives the message, and in some cases whether that message was sent to multiple applications. -RMr functions do provide for the ability to respond to the +RMR functions do provide for the ability to respond to the specific source instance of a message allowing for either a request response, or call response relationship when needed. The Route Table -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The library must be given a route table which maps message -numbers to endpoint groups such that each time a message of -type T is sent, the message is delivered to one member of -each group associated with T. For example, message type 2 -might route to two different groups where group A consists of -worker1 and worker2, while group B consists only of logger1. +types (integers) to endpoint groups such that each time a +message of type T is sent, the message is delivered to one +member of each group associated with T. For example, message +type 2 might route to two different groups where group A has +two members, worker1 and worker2, while group B has only one +member, logger1. + +The route table consists of a start record, one or more table +entry records, and an end record. All table records contain +fields separated with vertical bars (|), and allow for +trailing comments with the standard shell comment symbol +(hash, #) provided that the start of the comment is separated +from the last token on the record by one or more spaces. +Leading and trailing white space in each field is ignored. +The route table supports two entry types: *rte* and *mse*. + +A *rte* entry defines a message type, an optional sender +application, and the endpoint(s) which accept the indicated +message type. However, this format is deprecated and may be +removed in a future version. An example record appears next. + +:: + + rte | 1 | app10:4560 + + + +The second type of entry is *mse*. This entry defines a +message type, an optional sender application, a subscription +ID, and a collection of endpoints. An example record appears +next. + +:: + + mse | 1000,forwarder:43086 | 10 | app2:43086 + + It is the responsibility of the route table generator to know which endpoints belong to which groups, and which groups accept which message types. Once understood, the route table -generator publishes a table that is ingested by RMr and used +generator publishes a table that is ingested by RMR and used for mapping messages to end points. The following is a simple route table which causes message @@ -115,16 +149,17 @@ might look: Route Table Syntax -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The following illustrates the syntax for both the route -table. +The following illustrates the syntax for both types of route +table entries. :: newrt | start - mse | [,] | [;]... + rte | [,] | [;]... + mse | [,] | | [;]... newrt | end @@ -132,13 +167,13 @@ table. A round robin group is one or more endpoints from which one will be selected to receive the message. When multiple endpoints are given in a group, they must be separated with a -comma. An endpoint is the IP address and port (e.g. -192.158.4.30:8219) or DNS name and port of the application +comma. An endpoint is an IP address and port (e.g. +192.158.4.30:8219), or DNS name and port, of the application that should receive the message type. If multiple round-robin -groups are given, they must be separated by a semicolon, and +groups are given, they must be separated by a semicolon. MEID Map Syntax -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The MEID map is similar to the route table. Entries are used to add or replace the ownership of one or more MEIDs (mme_ar) @@ -171,13 +206,13 @@ that all data was received exactly as the route manager transmitted them. Environment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To enable configuration of the library behaviour outside of -direct user application control, RMr supports a number of +direct user application control, RMR supports a number of environment variables which provide information to the library. The following is a list of the various environment -variables, what they control and the defaults which RMr uses +variables, what they control and the defaults which RMR uses if undefined.