+
.. 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.
.. 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. Nanomsg) and without
+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
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
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 | <message-type>[,<sender-endpoint>] | <sub-id> <roud-robin-grp>[;<round-robin-grp>]...
+ rte | <message-type>[,<sender-endpoint>] | <round-robin-grp>[;<round-robin-grp>]...
+ mse | <message-type>[,<sender-endpoint>] | <sub-id> | <round-robin-grp>[;<round-robin-grp>]...
newrt | end
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)
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.
RMR_ASYNC_CONN
Allows the async connection mode to be turned off (by
- setting the value to 0. When set to 1, or missing from the
- environment, RMR will invoke the connection interface in
- the transport mechanism using the non-blocking (async)
+ setting the value to 0). When set to 1, or missing from
+ the environment, RMR will invoke the connection interface
+ in the transport mechanism using the non-blocking (async)
mode. This will likely result in many "soft failures"
(retry) until the connection is established, but allows
- the application to continue unimpeeded should the
+ the application to continue unimpeded should the
connection be slow to set up.
RMR_BIND_IF
This provides the interface that RMR will bind listen
- ports to allowing for a single interface to be used rather
- than listening across all interfaces. This should be the
- IP address assigned to the interface that RMR should
- listen on, and if not defined RMR will listen on all
- interfaces.
+ ports to, allowing for a single interface to be used
+ rather than listening across all interfaces. This should
+ be the IP address assigned to the interface that RMR
+ should listen on, and if not defined RMR will listen on
+ all interfaces.
RMR_CTL_PORT
port) was used to define this port. However, a future
version of Route Manager will require RMR to connect and
request tables, thus that variable is now used to supply
- the Route Manager well known address and port.
+ the Route Manager's well-known address and port.
- To maintain backwards compatablibility with the older
- Route Manager versions, the presence of this variable in
- the environment will shift RMR's behaviour with respect to
- the default value used when RMR_RTG_SVC is **not**
- defined.
+ To maintain backwards compatibility with the older Route
+ Manager versions, the presence of this variable in the
+ environment will shift RMR's behaviour with respect to the
+ default value used when RMR_RTG_SVC is **not** defined.
When RMR_CTL_PORT is **defined:** RMR assumes that Route
Manager requires RMR to connect and request table updates
- is made, and the default well known address for Route
+ is made, and the default well-known address for Route
manager is used (routemgr:4561).
When RMR_CTL_PORT is **undefined:** RMR assumes that Route
**Deprecated.** Should be set to 1 if the route table
generator is sending "plain" messages (not using RMR to
- send messages, 0 if the rtg is using RMR to send. The
- default is 1 as we don't expect the rtg to use RMR.
+ send messages), 0 if the RTG is using RMR to send. The
+ default is 1 as we don't expect the RTG to use RMR.
This variable is only recognised when using the NNG
transport library as it is not possible to support NNG
report *ready* until a table is received. The static route
table may contain both the route table (between newrt
start and end records), and the MEID map (between meid_map
- start and end records)
+ start and end records).
RMR_SRC_ID
Code Review / ric-plt / lib / rmr.git / blobdiff