From 817b89e8e44f2ef717056b4ed3116289735f8565 Mon Sep 17 00:00:00 2001 From: "E. Scott Daniels" Date: Wed, 13 May 2020 09:50:40 -0400 Subject: [PATCH] Add link to RTD index This change adds the link to the main RMR manual page in place of a formal overveiw document. A few other small tweaks were made to the route table document and glossary; the glossary code is shared so the update triggers an update to the user guide .rst as well. The overview source is deleted in this change. Issue-ID: RIC-378 Signed-off-by: E. Scott Daniels Change-Id: I4972683faaab204dd0167b67a7510cb97e01d01a --- doc/src/library/glossary.im | 8 ++--- doc/src/library/rt_tables.xfm | 29 +++++++--------- doc/src/rtd/.gitignore | 1 + doc/src/rtd/overview.xfm | 38 -------------------- docs/config-deploy.rst | 2 +- docs/index.rst | 10 +++--- docs/rt_tables.rst | 81 ++++++++++++++++++++++--------------------- docs/user-guide.rst | 18 ++++++---- 8 files changed, 74 insertions(+), 113 deletions(-) delete mode 100644 doc/src/rtd/overview.xfm diff --git a/doc/src/library/glossary.im b/doc/src/library/glossary.im index 63bc83e..e36957f 100644 --- a/doc/src/library/glossary.im +++ b/doc/src/library/glossary.im @@ -40,7 +40,7 @@ meaning. &ditem(Endpoint) An RMR based application that is defined as being capable of receiving one or more types of - messages (as defined by a &ital(message key.) + messages (as defined by a &ital(routing key.) .sm ) &ditem(Environment variable) A key/value pair which is set externally @@ -88,7 +88,7 @@ meaning. message type, message source, and other information. -&ditem(Messgae type) A signed integer (0-32000) which identifies the +&ditem(Message type) A signed integer (0-32000) which identifies the type of message being transmitted, and is one of the two components of a &ital(routing key.) See &ital(Subscription ID.) @@ -110,7 +110,7 @@ meaning. selected before starting at the head of the list. &ditem(Route table) A series of "rules" which define the possible - &ital(endpoints) for each &ital(message key.) + &ital(endpoints) for each &ital(routing key.) &ditem(Route table manager) An application responsible for building a &ital(route table) and then distributing it to @@ -146,7 +146,7 @@ meaning. manage asynchronous functions such as route table updates. -&Term(Trace information) An optional portion of the message buffer +&ditem(Trace information) An optional portion of the message buffer that the application may populate with data that allows for tracing the progress of the transaction or application activity across diff --git a/doc/src/library/rt_tables.xfm b/doc/src/library/rt_tables.xfm index 0e4b7e6..0b93bdc 100644 --- a/doc/src/library/rt_tables.xfm +++ b/doc/src/library/rt_tables.xfm @@ -273,7 +273,7 @@ The connection between RMR and the &RTMGR is also an RMR session and thus RMR messages will be used to exchange requests and responses. &h2(Table Request) -During initialisation, RMR will establish a wormhole connection to the &RTMGR and sends +During initialisation, RMR establishes a wormhole connection to the &RTMGR and sends a message type of &MT_REQ_TABLE to request a new table. RMR will continue to send table requests until a table is received and accepted; in other words it is fine for the &RTMGR to ignore the requests if it is not ready to respond. @@ -299,23 +299,18 @@ Any other response indicates that RMR did not use the table and has dropped it; table is still in use. +&h2(Using A Static Route Table) +A static route table can be provided to assist with testing, or to provide a bootstrap set of +route information until a dynamic table is received from a routing manager. +The environment variable &cw(RMR_SEED_RT) is checked during RMR initialisation and +if set is expected to reference a file containing a route table. +This table will be loaded and used until overlaid by a table sent by the &RTMGR. +&space - -&h1(Providing A Static Table) -For testing, or possibly bootstrapping purposes, a static route table can be supplied. -During initialisation, RMR will check the &cw(RMR_SEED_RT) environment variable. -If it exists, and references a file, RMR will open and read the file expecting to find -a static route table. -This route table is used until an update is received from a &RTMGR. -Normally, when the RMR initialisation function is invoked, a listener is started to receive route table information from a route -manager process. -During testing it is often useful to supply a static table which is available should no route management process exist, -or to provide a seed table to use before the first table is delivered. -The environment variable &cw(RMR_SEED_RT) can be set to provide the RMR initialisation function with the name -of the static table to use. -If a static table is provided, it will be loaded only once, and will be overlaid if -a dynamically delivered table is received. - +For testing, the static table will be reloaded periodically if the &cw(RMR_RTG_SVC) environment +variable is set to -1. +When this testing feature is enabled RMR will not listen for &RTMGR connections, nor will it attempt to +request a dynamic table. &h1(Routing Using MEID) diff --git a/doc/src/rtd/.gitignore b/doc/src/rtd/.gitignore index 418f8c4..76089b2 100644 --- a/doc/src/rtd/.gitignore +++ b/doc/src/rtd/.gitignore @@ -1,4 +1,5 @@ man_list.im +*.html *.md *.rst *.ps diff --git a/doc/src/rtd/overview.xfm b/doc/src/rtd/overview.xfm deleted file mode 100644 index 2cbd112..0000000 --- a/doc/src/rtd/overview.xfm +++ /dev/null @@ -1,38 +0,0 @@ -.** vim: ts=4 noet sw=4: -.if false -================================================================================== - Copyright (c) 2019 Nokia - Copyright (c) 2018-2019 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. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. -================================================================================== -.fi - - -.if false - Mnemonic: overview.xfm - Abstract: Source for the overview which is just a reformatting of the main - rmr.7 manual page. - Date: 6 November 2019 - Author: E. Scott Daniels -.fi - -.dv GEN_TITLE 1 -.dv doc_title RMR Overview -.im setup.im - -.sp -Please refer to the main RMR manual page for an overview of the library: - -&space -https://docs.o-ran-sc.org/projects/o-ran-sc-ric-plt-lib-rmr/en/latest/index.html diff --git a/docs/config-deploy.rst b/docs/config-deploy.rst index 80029cc..58fff4b 100644 --- a/docs/config-deploy.rst +++ b/docs/config-deploy.rst @@ -5,7 +5,7 @@ .. Do NOT make changes directly to .rst or .md files. ============================================================================================ -RMR Configuration and Deployment +Configuration and Deployment ============================================================================================ diff --git a/docs/index.rst b/docs/index.rst index e1c99a9..487bcfc 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,13 +2,11 @@ .. SPDX-License-Identifier: CC-BY-4.0 -.. who in bloody hell knows what format this should be; guessing! -.. it does seem though that every .rst file in the directory must be listed here -.. or tox will complain and fail. - - RIC Message Router -- RMR -========================== +========================= + +Please refer to the `main RMR manual page `_ +for an overview of the library. .. toctree:: :maxdepth: 1 diff --git a/docs/rt_tables.rst b/docs/rt_tables.rst index 52a3d1e..807c56e 100644 --- a/docs/rt_tables.rst +++ b/docs/rt_tables.rst @@ -17,7 +17,7 @@ Overview Messages sent via the RIC Message Router (RMR) are routed to an endpoint (another application) based on a combination of -the *message type* (MT) and *subscription ID* (SID), supplied +the *message type* (MT) and *subscription ID* (SID) supplied in the message. RMR determines the endpoint by matching the MT and SID combination to an entry in a route table which has been supplied dynamically by a *Route Manager* service, or as @@ -115,12 +115,13 @@ Where: is one or more, comma separated, endpoint descriptions. -space When an application sends a message with the indicated -type, the message will be sent to one endpoint in the group -in a round-robin ordering. If multiple endpoint groups are -given, then the message is sent to a member selected from -each group; 3 groups, then three messages will be sent. The -first group is required. + +When an application sends a message with the indicated type, +the message will be sent to one endpoint in the group in a +round-robin ordering. If multiple endpoint groups are given, +then the message is sent to a member selected from each +group; 3 groups, then three messages will be sent. The first +group is required. Line separation @@ -286,12 +287,12 @@ requests and responses. Table Request ------------- -During initialisation, RMR will establish a wormhole -connection to the *Route Manager* and sends a message type of -21 to request a new table. RMR will continue to send table -requests until a table is received and accepted; in other -words it is fine for the *Route Manager* to ignore the -requests if it is not ready to respond. +During initialisation, RMR establishes a wormhole connection +to the *Route Manager* and sends a message type of 21 to +request a new table. RMR will continue to send table requests +until a table is received and accepted; in other words it is +fine for the *Route Manager* to ignore the requests if it is +not ready to respond. Sending Tables To RMR @@ -325,26 +326,22 @@ that RMR did not use the table and has dropped it; the previous table is still in use. -Providing A Static Table -======================== - -For testing, or possibly bootstrapping purposes, a static -route table can be supplied. During initialisation, RMR will -check the ``RMR_SEED_RT`` environment variable. If it exists, -and references a file, RMR will open and read the file -expecting to find a static route table. This route table is -used until an update is received from a *Route Manager*. -Normally, when the RMR initialisation function is invoked, a -listener is started to receive route table information from a -route manager process. During testing it is often useful to -supply a static table which is available should no route -management process exist, or to provide a seed table to use -before the first table is delivered. The environment variable -``RMR_SEED_RT`` can be set to provide the RMR initialisation -function with the name of the static table to use. If a -static table is provided, it will be loaded only once, and -will be overlaid if a dynamically delivered table is -received. +Using A Static Route Table +-------------------------- + +A static route table can be provided to assist with testing, +or to provide a bootstrap set of route information until a +dynamic table is received from a routing manager. The +environment variable ``RMR_SEED_RT`` is checked during RMR +initialisation and if set is expected to reference a file +containing a route table. This table will be loaded and used +until overlaid by a table sent by the *Route Manager*. + +For testing, the static table will be reloaded periodically +if the ``RMR_RTG_SVC`` environment variable is set to -1. +When this testing feature is enabled RMR will not listen for +*Route Manager* connections, nor will it attempt to request a +dynamic table. Routing Using MEID @@ -485,7 +482,7 @@ reader to understand the intent of meaning. - An RMR based application that is defined as being capable of receiving one or more types of messages (as defined by a - *message key.*) + *routing key.*) * - **Environment variable** - @@ -537,7 +534,7 @@ reader to understand the intent of meaning. payload length, message type, message source, and other information. - * - **Messgae type** + * - **Message type** - A signed integer (0-32000) which identifies the type of message being transmitted, and is one of the two components @@ -565,7 +562,7 @@ reader to understand the intent of meaning. * - **Route table** - A series of "rules" which define the possible *endpoints* for - each *message key.* + each *routing key.* * - **Route table manager** - @@ -611,10 +608,14 @@ reader to understand the intent of meaning. lightweight process which executes in concurrently with the application and shares the same address space. RMR uses threads to manage asynchronous functions such as route table - updates. &Term An optional portion of the message buffer that - the application may populate with data that allows for - tracing the progress of the transaction or application - activity across components. RMR makes no use of this data. + updates. + + * - **Trace information** + - + An optional portion of the message buffer that the + application may populate with data that allows for tracing + the progress of the transaction or application activity + across components. RMR makes no use of this data. * - **Transaction ID** - diff --git a/docs/user-guide.rst b/docs/user-guide.rst index 2aa1f9a..a825c50 100644 --- a/docs/user-guide.rst +++ b/docs/user-guide.rst @@ -1001,7 +1001,7 @@ reader to understand the intent of meaning. - An RMR based application that is defined as being capable of receiving one or more types of messages (as defined by a - *message key.*) + *routing key.*) * - **Environment variable** - @@ -1053,7 +1053,7 @@ reader to understand the intent of meaning. payload length, message type, message source, and other information. - * - **Messgae type** + * - **Message type** - A signed integer (0-32000) which identifies the type of message being transmitted, and is one of the two components @@ -1081,7 +1081,7 @@ reader to understand the intent of meaning. * - **Route table** - A series of "rules" which define the possible *endpoints* for - each *message key.* + each *routing key.* * - **Route table manager** - @@ -1127,10 +1127,14 @@ reader to understand the intent of meaning. lightweight process which executes in concurrently with the application and shares the same address space. RMR uses threads to manage asynchronous functions such as route table - updates. &Term An optional portion of the message buffer that - the application may populate with data that allows for - tracing the progress of the transaction or application - activity across components. RMR makes no use of this data. + updates. + + * - **Trace information** + - + An optional portion of the message buffer that the + application may populate with data that allows for tracing + the progress of the transaction or application activity + across components. RMR makes no use of this data. * - **Transaction ID** - -- 2.16.6