-
-
-Where:
-
-
- .. list-table::
- :widths: 25,70
- :header-rows: 0
- :class: borderless
-
- * - **mse, rte**
- -
- is the table entry type
-
- * - **<msg-type>**
- -
- is the integer message type
-
- * - **<sender-endpoint>**
- -
- is the endpoint description of the message sender; only that
- sender will read the entry from the table, so a single table
- may be used for all senders when a common message type is
- delivered to varying endpoints based on senders. If the
- sender endpoint is omitted from the entry, then the entry
- will be used by all applications.
-
- * - **<sub-id>**
- -
- is the subscription id (integer) for subscription-based
- messages, or -1 if the message type is not
- subscription-based. An *mse* entry with a sub-id of -1 is the
- **same** as an *rte* entry with the same message type.
-
- * - **<endpoint-group>**
- -
- is one or more, comma separated, endpoint descriptions.
-
-
-
-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.
+
+
+Where:
+
+
+ .. list-table::
+ :widths: 25,70
+ :header-rows: 0
+ :class: borderless
+
+ * - **mse, rte**
+ -
+ is the table entry type
+
+ * - **<msg-type>**
+ -
+ is the integer message type
+
+ * - **<sender-endpoint>**
+ -
+ is the endpoint description of the message sender; only that
+ sender will read the entry from the table, so a single table
+ may be used for all senders when a common message type is
+ delivered to varying endpoints based on senders. If the
+ sender endpoint is omitted from the entry, then the entry
+ will be used by all applications.
+
+ * - **<sub-id>**
+ -
+ is the subscription id (integer) for subscription-based
+ messages, or -1 if the message type is not
+ subscription-based. An *mse* entry with a sub-id of -1 is the
+ **same** as an *rte* entry with the same message type.
+
+ * - **<endpoint-group>**
+ -
+ is one or more, comma separated, endpoint descriptions.
+
+
+
+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.
-Whether a table is read from a file on disk, or is received
-from a *Route Manager* service, RMR parses the records to
-build an internal route table keeping only the relevant
-information. Entries are read in the order they appear (from
-the file or in messages received), and RMR will use only one
-entry for each MT/SID pair.
-
-For most tables, the ordering of entries is not important,
-but when there are entries which duplicate the MT/SID pair
-ordering becomes significant. RMR will use the **last** valid
-entry for a MT/SID pair that it encounters. An entry is
-considered valid if there is no sender identified with the
-message type (line 3), and when the sender (host and port)
-match the the applications' location and the port provided to
-RMR for listening.
-
-Using the table in figure 3 as an example, there are two
-entries which match the MT/SID pair of 1000/10. When this
-table is parsed on any host, RMR will recognise and add the
-first entry (line 3) to the internal representation; this
-entry is valid for all applications. The second 1000/10 entry
-(line 4) is valid when the table is parsed on the *forwarder*
-host, and only by the application which is listening on port
-43086. For this application the entry will override the more
-generic entry for the MT/SID combination.
-
-As a rule, the ordering of entries for a given MT/SID pair
-should be from most generic to most specific.
+Whether a table is read from a file on disk, or is received
+from a *Route Manager* service, RMR parses the records to
+build an internal route table keeping only the relevant
+information. Entries are read in the order they appear (from
+the file or in messages received), and RMR will use only one
+entry for each MT/SID pair.
+
+For most tables, the ordering of entries is not important,
+but when there are entries which duplicate the MT/SID pair
+ordering becomes significant. RMR will use the **last** valid
+entry for a MT/SID pair that it encounters. An entry is
+considered valid if there is no sender identified with the
+message type (line 3), and when the sender (host and port)
+match the the applications' location and the port provided to
+RMR for listening.
+
+Using the table in figure 3 as an example, there are two
+entries which match the MT/SID pair of 1000/10. When this
+table is parsed on any host, RMR will recognise and add the
+first entry (line 3) to the internal representation; this
+entry is valid for all applications. The second 1000/10 entry
+(line 4) is valid when the table is parsed on the *forwarder*
+host, and only by the application which is listening on port
+43086. For this application the entry will override the more
+generic entry for the MT/SID combination.
+
+As a rule, the ordering of entries for a given MT/SID pair
+should be from most generic to most specific.
-Starting with version 1.13.0, RMR provides the ability to
-select the endpoint for a message based on the MEID (managed
-entity ID) in the message, rather than selecting the endpoint
-from the round-robin list for the matching route table entry.
-When the MEID is used, the message is sent to the endpoint
-which *owns,* or is responsible for the managed entity.
-Should the *owner* change messages will be routed to the new
-owner when the route table is updated. To make use of MEID
-routing, there must be one or more route table entries which
-list the special endpoint name ``%meid`` instead of providing
-a round robin list. As an example, consider the following
-route table entry:
-
-
-::
-
- mse| 1000,forwarder:43086 | 10 | %meid
-
-Figure 4: Sample route entry with the meid flag.
-
-The final field of the entry doesn't specify a round-robin
-group which means that when an application attempts to send a
-message with type 1000, and the subscription ID of 10, the
-MEID in the message will be used to select the endpoint.
+Starting with version 1.13.0, RMR provides the ability to
+select the endpoint for a message based on the MEID (managed
+entity ID) in the message, rather than selecting the endpoint
+from the round-robin list for the matching route table entry.
+When the MEID is used, the message is sent to the endpoint
+which *owns,* or is responsible for the managed entity.
+Should the *owner* change messages will be routed to the new
+owner when the route table is updated. To make use of MEID
+routing, there must be one or more route table entries which
+list the special endpoint name ``%meid`` instead of providing
+a round robin list. As an example, consider the following
+route table entry:
+
+
+::
+
+ mse| 1000,forwarder:43086 | 10 | %meid
+
+Figure 4: Sample route entry with the meid flag.
+
+The final field of the entry doesn't specify a round-robin
+group which means that when an application attempts to send a
+message with type 1000, and the subscription ID of 10, the
+MEID in the message will be used to select the endpoint.
-To select an endpoint for the message based on the MEID in a
-message, RMR must know which endpoint owns the MEID. This
-information, known as an MEID map, is provided by the *Route
-Manager* over the same communication path as the route table
-is supplied. The following is the syntax for an MEID map.
-
-
-::
-
- meid_map | start | <table-id>
- mme_ar | <owner-endpoint> | <meid> [<meid>...]
- mme_del | <meid> [<meid>...]
- meid_map | end | <count> [| <md5sum> ]
-
-Figure 5: Meid map table.
-
-The mme_ar records are add/update records and allow for the
-list of MEIDs to be associated with (owned by) the indicated
-endpoint. The <owner-endpoint> is the hostname:port, or IP
-address and port, of the application which owns the MEID and
-thus should receive any messages which are routed based on a
-route table entry with %meid as the round-robin group. The
-mme_del records allow for MEIDs to be deleted from RMR's
-view. Finally, the <count> is the number of add/replace and
-delete records which were sent; if RMR does not match the
-<count> value to the number of records, then it will not add
-the data to the table. Updates only need to list the
-ownership changes that are necessary; in other words, the
-*Route Manager* does not need to supply all of the MEID
-relationships with each update.
-
-The optional <md5sum> field on the end record should be the
-MD5 hash of all of the records between the start and end
-records. This allows for a precise verification that the
-transmitted data was correctly received.
-
-If a static seed file is being used for the route table, a
-second section can be given which supplies the MEID map. The
-following is a small example of a seed file:
-
-
-::
-
- newrt|start | id-64306
- mse|0|-1| %meid
- mse|1|-1|172.19.0.2:4560
- mse|2|-1|172.19.0.2:4560
- mse|3|-1|172.19.0.2:4560
- mse|4|-1|172.19.0.2:4560
- mse|5|-1|172.19.0.2:4560
- newrt|end
-
- meid_map | start | id-028919
- mme_ar| 172.19.0.2:4560 | meid000 meid001 meid002 meid003 meid004 meid005
- mme_ar| 172.19.0.42:4560 | meid100 meid101 meid102 meid103
- mme_del | meid1000
- meid_map | end | 1
-
-Figure 6: Illustration of both a route table and meid map in
-the same file.
-
-The tables above will route all messages with a message type
-of 0 based on the MEID. There are 10 meids which are owned by
-two different endpoints. The table also deletes the MEID
-meid1000 from RMR's view.
+To select an endpoint for the message based on the MEID in a
+message, RMR must know which endpoint owns the MEID. This
+information, known as an MEID map, is provided by the *Route
+Manager* over the same communication path as the route table
+is supplied. The following is the syntax for an MEID map.
+
+
+::
+
+ meid_map | start | <table-id>
+ mme_ar | <owner-endpoint> | <meid> [<meid>...]
+ mme_del | <meid> [<meid>...]
+ meid_map | end | <count> [| <md5sum> ]
+
+Figure 5: Meid map table.
+
+The mme_ar records are add/update records and allow for the
+list of MEIDs to be associated with (owned by) the indicated
+endpoint. The <owner-endpoint> is the hostname:port, or IP
+address and port, of the application which owns the MEID and
+thus should receive any messages which are routed based on a
+route table entry with %meid as the round-robin group. The
+mme_del records allow for MEIDs to be deleted from RMR's
+view. Finally, the <count> is the number of add/replace and
+delete records which were sent; if RMR does not match the
+<count> value to the number of records, then it will not add
+the data to the table. Updates only need to list the
+ownership changes that are necessary; in other words, the
+*Route Manager* does not need to supply all of the MEID
+relationships with each update.
+
+The optional <md5sum> field on the end record should be the
+MD5 hash of all of the records between the start and end
+records. This allows for a precise verification that the
+transmitted data was correctly received.
+
+If a static seed file is being used for the route table, a
+second section can be given which supplies the MEID map. The
+following is a small example of a seed file:
+
+
+::
+
+ newrt|start | id-64306
+ mse|0|-1| %meid
+ mse|1|-1|172.19.0.2:4560
+ mse|2|-1|172.19.0.2:4560
+ mse|3|-1|172.19.0.2:4560
+ mse|4|-1|172.19.0.2:4560
+ mse|5|-1|172.19.0.2:4560
+ newrt|end
+
+ meid_map | start | id-028919
+ mme_ar| 172.19.0.2:4560 | meid000 meid001 meid002 meid003 meid004 meid005
+ mme_ar| 172.19.0.42:4560 | meid100 meid101 meid102 meid103
+ mme_del | meid1000
+ meid_map | end | 1
+
+Figure 6: Illustration of both a route table and meid map in
+the same file.
+
+The tables above will route all messages with a message type
+of 0 based on the MEID. There are 10 meids which are owned by
+two different endpoints. The table also deletes the MEID
+meid1000 from RMR's view.
-Many terms in networking can be interpreted with multiple
-meanings, and several terms used in various RMR documentation
-are RMR specific. The following definitions are the meanings
-of terms used within RMR documentation and should help the
-reader to understand the intent of meaning.
-
- .. list-table::
- :widths: 25,70
- :header-rows: 0
- :class: borderless
-
- * - **application**
- -
- A programme which uses RMR to send and/or receive messages
- to/from another RMR based application.
-
- * - **Critical error**
- -
- An error that RMR has encountered which will prevent further
- successful processing by RMR. Critical errors usually
- indicate that the application should abort.
-
- * - **Endpoint**
- -
- An RMR based application that is defined as being capable of
- receiving one or more types of messages (as defined by a
- *routing key.*)
-
- * - **Environment variable**
- -
- A key/value pair which is set externally to the application,
- but which is available to the application (and referenced
- libraries) through the ``getenv`` system call. Environment
- variables are the main method of communicating information
- such as port numbers to RMR.
-
- * - **Error**
- -
- An abnormal condition that RMR has encountered, but will not
- affect the overall processing by RMR, but may impact certain
- aspects such as the ability to communicate with a specific
- endpoint. Errors generally indicate that something, usually
- external to RMR, must be addressed.
-
- * - **Host name**
- -
- The name of the host as returned by the ``gethostbyname``
- system call. In a containerised environment this might be the
- container or service name depending on how the container is
- started. From RMR's point of view, a host name can be used to
- resolve an *endpoint* definition in a *route* table.)
-
- * - **IP**
- -
- Internet protocol. A low level transmission protocol which
- governs the transmission of datagrams across network
- boundaries.
-
- * - **Listen socket**
- -
- A *TCP* socket used to await incoming connection requests.
- Listen sockets are defined by an interface and port number
- combination where the port number is unique for the
- interface.
-
- * - **Message**
- -
- A series of bytes transmitted from the application to another
- RMR based application. A message is comprised of RMR specific
- data (a header), and application data (a payload).
-
- * - **Message buffer**
- -
- A data structure used to describe a message which is to be
- sent or has been received. The message buffer includes the
- payload length, message type, message source, and other
- information.
-
- * - **Message type**
- -
- A signed integer (0-32000) which identifies the type of
- message being transmitted, and is one of the two components
- of a *routing key.* See *Subscription ID.*
-
- * - **Payload**
- -
- The portion of a message which holds the user data to be
- transmitted to the remote *endpoint.* The payload contents
- are completely application defined.
-
- * - **RMR context**
- -
- A set of information which defines the current state of the
- underlying transport connections that RMR is managing. The
- application will be give a context reference (pointer) that
- is supplied to most RMR functions as the first parameter.
-
- * - **Round robin**
- -
- The method of selecting an *endpoint* from a list such that
- all *endpoints* are selected before starting at the head of
- the list.
-
- * - **Route table**
- -
- A series of "rules" which define the possible *endpoints* for
- each *routing key.*
-
- * - **Route table manager**
- -
- An application responsible for building a *route table* and
- then distributing it to all applicable RMR based
- applications.
-
- * - **Routing**
- -
- The process of selecting an *endpoint* which will be the
- recipient of a message.
-
- * - **Routing key**
- -
- A combination of *message type* and *subscription ID* which
- RMR uses to select the destination *endpoint* when sending a
- message.
-
- * - **Source**
- -
- The sender of a message.
-
- * - **Subscription ID**
- -
- A signed integer value (0-32000) which identifies the
- subscription characteristic of a message. It is used in
- conjunction with the *message type* to determine the *routing
- key.*
-
- * - **Target**
- -
- The *endpoint* selected to receive a message.
-
- * - **TCP**
- -
- Transmission Control Protocol. A connection based internet
- protocol which provides for lossless packet transportation,
- usually over IP.
-
- * - **Thread**
- -
- Also called a *process thread, or pthread.* This is a
- 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.
-
- * - **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**
- -
- A fixed number of bytes in the *message* buffer) which the
- application may populate with information related to the
- transaction. RMR makes use of the transaction ID for matching
- response messages with the &c function is used to send a
- message.
-
- * - **Transient failure**
- -
- An error state that is believed to be short lived and that
- the operation, if retried by the application, might be
- successful. C programmers will recognise this as
- ``EAGAIN.``
-
- * - **Warning**
- -
- A warning occurs when RMR has encountered something that it
- believes isn't correct, but has a defined work round.
-
- * - **Wormhole**
- -
- A direct connection managed by RMR between the user
- application and a remote, RMR based, application.
-
-
-
+Many terms in networking can be interpreted with multiple
+meanings, and several terms used in various RMR documentation
+are RMR specific. The following definitions are the meanings
+of terms used within RMR documentation and should help the
+reader to understand the intent of meaning.
+
+ .. list-table::
+ :widths: 25,70
+ :header-rows: 0
+ :class: borderless
+
+ * - **application**
+ -
+ A programme which uses RMR to send and/or receive messages
+ to/from another RMR based application.
+
+ * - **Critical error**
+ -
+ An error that RMR has encountered which will prevent further
+ successful processing by RMR. Critical errors usually
+ indicate that the application should abort.
+
+ * - **Endpoint**
+ -
+ An RMR based application that is defined as being capable of
+ receiving one or more types of messages (as defined by a
+ *routing key.*)
+
+ * - **Environment variable**
+ -
+ A key/value pair which is set externally to the application,
+ but which is available to the application (and referenced
+ libraries) through the ``getenv`` system call. Environment
+ variables are the main method of communicating information
+ such as port numbers to RMR.
+
+ * - **Error**
+ -
+ An abnormal condition that RMR has encountered, but will not
+ affect the overall processing by RMR, but may impact certain
+ aspects such as the ability to communicate with a specific
+ endpoint. Errors generally indicate that something, usually
+ external to RMR, must be addressed.
+
+ * - **Host name**
+ -
+ The name of the host as returned by the ``gethostbyname``
+ system call. In a containerised environment this might be the
+ container or service name depending on how the container is
+ started. From RMR's point of view, a host name can be used to
+ resolve an *endpoint* definition in a *route* table.)
+
+ * - **IP**
+ -
+ Internet protocol. A low level transmission protocol which
+ governs the transmission of datagrams across network
+ boundaries.
+
+ * - **Listen socket**
+ -
+ A *TCP* socket used to await incoming connection requests.
+ Listen sockets are defined by an interface and port number
+ combination where the port number is unique for the
+ interface.
+
+ * - **Message**
+ -
+ A series of bytes transmitted from the application to another
+ RMR based application. A message is comprised of RMR specific
+ data (a header), and application data (a payload).
+
+ * - **Message buffer**
+ -
+ A data structure used to describe a message which is to be
+ sent or has been received. The message buffer includes the
+ payload length, message type, message source, and other
+ information.
+
+ * - **Message type**
+ -
+ A signed integer (0-32000) which identifies the type of
+ message being transmitted, and is one of the two components
+ of a *routing key.* See *Subscription ID.*
+
+ * - **Payload**
+ -
+ The portion of a message which holds the user data to be
+ transmitted to the remote *endpoint.* The payload contents
+ are completely application defined.
+
+ * - **RMR context**
+ -
+ A set of information which defines the current state of the
+ underlying transport connections that RMR is managing. The
+ application will be give a context reference (pointer) that
+ is supplied to most RMR functions as the first parameter.
+
+ * - **Round robin**
+ -
+ The method of selecting an *endpoint* from a list such that
+ all *endpoints* are selected before starting at the head of
+ the list.
+
+ * - **Route table**
+ -
+ A series of "rules" which define the possible *endpoints* for
+ each *routing key.*
+
+ * - **Route table manager**
+ -
+ An application responsible for building a *route table* and
+ then distributing it to all applicable RMR based
+ applications.
+
+ * - **Routing**
+ -
+ The process of selecting an *endpoint* which will be the
+ recipient of a message.
+
+ * - **Routing key**
+ -
+ A combination of *message type* and *subscription ID* which
+ RMR uses to select the destination *endpoint* when sending a
+ message.
+
+ * - **Source**
+ -
+ The sender of a message.
+
+ * - **Subscription ID**
+ -
+ A signed integer value (0-32000) which identifies the
+ subscription characteristic of a message. It is used in
+ conjunction with the *message type* to determine the *routing
+ key.*
+
+ * - **Target**
+ -
+ The *endpoint* selected to receive a message.
+
+ * - **TCP**
+ -
+ Transmission Control Protocol. A connection based internet
+ protocol which provides for lossless packet transportation,
+ usually over IP.
+
+ * - **Thread**
+ -
+ Also called a *process thread, or pthread.* This is a
+ 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.
+
+ * - **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**
+ -
+ A fixed number of bytes in the *message* buffer) which the
+ application may populate with information related to the
+ transaction. RMR makes use of the transaction ID for matching
+ response messages with the &c function is used to send a
+ message.
+
+ * - **Transient failure**
+ -
+ An error state that is believed to be short lived and that
+ the operation, if retried by the application, might be
+ successful. C programmers will recognise this as
+ ``EAGAIN.``
+
+ * - **Warning**
+ -
+ A warning occurs when RMR has encountered something that it
+ believes isn't correct, but has a defined work round.
+
+ * - **Wormhole**
+ -
+ A direct connection managed by RMR between the user
+ application and a remote, RMR based, application.
+
+
+