-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.
-
-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 *modes* which
-allow the application to manage these states based on the
-overall needs of the application. These modes are discussed
-in the *Configuration* section of this document.
+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.
+
+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 *modes* which
+allow the application to manage these states based on the
+overall needs of the application. These modes are discussed
+in the *Configuration* section of this document.
-The RMR function ``rmr_init()`` is used to set up the RMR
-environment and must be called before messages can be sent or
-received. One of the few parameters that the application must
-communicate to RMR is the port number that will be used as
-the listen port for new connections. The port number is
-passed on the initialisation function call and a TCP listen
-socket will be opened with this port. If the port is already
-in use RMR will report a failure; the application will need
-to reinitialise with a different port number, abort, or take
-some other action appropriate for the application.
-
-In addition to creating a TCP listen port, RMR will start a
-process thread which will be responsible for receiving
-dynamic updates to the route table. This thread also causes a
-TCP listen port to be opened as it is expected that the
-process which generates route table updates will connect and
-send new information when needed. The route table update port
-is **not** supplied by the application, but is supplied via
-an environment variable as this value is likely determined by
-the mechanism which is starting and configuring the
-application.
+The RMR function ``rmr_init()`` is used to set up the RMR
+environment and must be called before messages can be sent or
+received. One of the few parameters that the application must
+communicate to RMR is the port number that will be used as
+the listen port for new connections. The port number is
+passed on the initialisation function call and a TCP listen
+socket will be opened with this port. If the port is already
+in use RMR will report a failure; the application will need
+to reinitialise with a different port number, abort, or take
+some other action appropriate for the application.
+
+In addition to creating a TCP listen port, RMR will start a
+process thread which will be responsible for receiving
+dynamic updates to the route table. This thread also causes a
+TCP listen port to be opened as it is expected that the
+process which generates route table updates will connect and
+send new information when needed. The route table update port
+is **not** supplied by the application, but is supplied via
+an environment variable as this value is likely determined by
+the mechanism which is starting and configuring the
+application.
-The function ``rmr_msg_alloc()`` allocates a *zero copy*
-buffer and returns a pointer to the RMR ``rmr_mbuf_t``
-structure. The message buffer provides direct access to the
-payload, length, message type and subscription ID fields. The
-buffer must be preallocated in order to allow the underlying
-transport mechanism to allocate the payload space from its
-internal memory pool; this eliminates multiple copies as the
-message is sent, and thus is more efficient.
-
-If a message buffer has been received, and the application
-wishes to use the buffer to send a response, or to forward
-the buffer to another application, a new buffer does **not**
-need to be allocated. The application may set the necessary
-information (message type, etc.), and adjust the payload, as
-is necessary and then pass the message buffer to
-``rmr_send_msg()`` or ``rmr_rts_msg()`` to be sent or
-returned to the sender.
+The function ``rmr_msg_alloc()`` allocates a *zero copy*
+buffer and returns a pointer to the RMR ``rmr_mbuf_t``
+structure. The message buffer provides direct access to the
+payload, length, message type and subscription ID fields. The
+buffer must be preallocated in order to allow the underlying
+transport mechanism to allocate the payload space from its
+internal memory pool; this eliminates multiple copies as the
+message is sent, and thus is more efficient.
+
+If a message buffer has been received, and the application
+wishes to use the buffer to send a response, or to forward
+the buffer to another application, a new buffer does **not**
+need to be allocated. The application may set the necessary
+information (message type, etc.), and adjust the payload, as
+is necessary and then pass the message buffer to
+``rmr_send_msg()`` or ``rmr_rts_msg()`` to be sent or
+returned to the sender.
-The application has direct access to several of the message
-buffer fields, and should set them appropriately.
-
-
- .. list-table::
- :widths: 15,80
- :header-rows: 0
- :class: borderless
-
- * - **len**
- -
- This is the number of bytes that the application placed into
- the payload. Setting length to 0 is allowed, and length may
- be less than the allocated payload size.
-
- * - **mtype**
- -
- The message type that RMR will use to determine the endpoint
- used as the target of the send.
-
- * - **sub_id**
- -
- The subscription ID if the message is to be routed based on
- the combination of message type and subscription ID. If no
- subscription ID is valid for the message, the application
- should set the field with the RMR constant
- ``RMR_VOID_SUBID.``
-
- * - **payload**
- -
- The application should obtain the reference (pointer) to the
- payload from the message buffer and place any data into the
- payload. The application is responsible for ensuring that the
- maximum payload size is not exceeded. The application may
- obtain the maximum size via the ``rmr_payload_size()``
- function.
-
- * - **trace data**
- -
- Optionally, the application may add trace information to the
- message buffer.
-
-
-
+The application has direct access to several of the message
+buffer fields, and should set them appropriately.
+
+
+ .. list-table::
+ :widths: 15,80
+ :header-rows: 0
+ :class: borderless
+
+ * - **len**
+ -
+ This is the number of bytes that the application placed into
+ the payload. Setting length to 0 is allowed, and length may
+ be less than the allocated payload size.
+
+ * - **mtype**
+ -
+ The message type that RMR will use to determine the endpoint
+ used as the target of the send.
+
+ * - **sub_id**
+ -
+ The subscription ID if the message is to be routed based on
+ the combination of message type and subscription ID. If no
+ subscription ID is valid for the message, the application
+ should set the field with the RMR constant
+ ``RMR_VOID_SUBID.``
+
+ * - **payload**
+ -
+ The application should obtain the reference (pointer) to the
+ payload from the message buffer and place any data into the
+ payload. The application is responsible for ensuring that the
+ maximum payload size is not exceeded. The application may
+ obtain the maximum size via the ``rmr_payload_size()``
+ function.
+
+ * - **trace data**
+ -
+ Optionally, the application may add trace information to the
+ message buffer.
+
+
+
-Once the application has populated the necessary bits of a
-message, it may be sent by passing the buffer to the
-``rmr_send_msg()`` function. This function will select an
-endpoint to receive the message, based on message type and
-subscription ID, and will pass the message to the underlying
-transport mechanism for actual transmission on the
-connection. (Depending on the underlying transport mechanism,
-the actual connection to the endpoint may happen at the time
-of the first message sent to the endpoint, and thus the
-latency of the first send might be longer than expected.)
-
-On success, the send function will return a reference to a
-message buffer; the status within that message buffer will
-indicate what the message buffer contains. When the status is
-``RMR_OK`` the reference is to a **new** message buffer for
-the application to use for the next send; the payload size is
-the same as the payload size allocated for the message that
-was just sent. This is a convenience as it eliminates the
-need for the application to call the message allocation
-function at some point in the future, and assumes the
-application will send many messages which will require the
-same payload dimensions.
-
-If the message contains any status other than ``RMR_OK,``
-then the message could **not** be sent, and the reference is
-to the unsent message buffer. The value of the status will
-indicate whether the nature of the failure was transient (
-``RMR_ERR_RETRY``) or not. Transient failures are likely to
-be successful if the application attempts to send the message
-at a later time. Unfortunately, it is impossible for RMR to
-know the exact transient failure (e.g. connection being
-established, or TCP buffer shortage), and thus it is not
-possible to communicate how long the application should wait
-before attempting to resend, if the application wishes to
-resend the message. (More discussion with respect to message
-retries can be found in the *Handling Failures* section.)
+Once the application has populated the necessary bits of a
+message, it may be sent by passing the buffer to the
+``rmr_send_msg()`` function. This function will select an
+endpoint to receive the message, based on message type and
+subscription ID, and will pass the message to the underlying
+transport mechanism for actual transmission on the
+connection. (Depending on the underlying transport mechanism,
+the actual connection to the endpoint may happen at the time
+of the first message sent to the endpoint, and thus the
+latency of the first send might be longer than expected.)
+
+On success, the send function will return a reference to a
+message buffer; the status within that message buffer will
+indicate what the message buffer contains. When the status is
+``RMR_OK`` the reference is to a **new** message buffer for
+the application to use for the next send; the payload size is
+the same as the payload size allocated for the message that
+was just sent. This is a convenience as it eliminates the
+need for the application to call the message allocation
+function at some point in the future, and assumes the
+application will send many messages which will require the
+same payload dimensions.
+
+If the message contains any status other than ``RMR_OK,``
+then the message could **not** be sent, and the reference is
+to the unsent message buffer. The value of the status will
+indicate whether the nature of the failure was transient (
+``RMR_ERR_RETRY``) or not. Transient failures are likely to
+be successful if the application attempts to send the message
+at a later time. Unfortunately, it is impossible for RMR to
+know the exact transient failure (e.g. connection being
+established, or TCP buffer shortage), and thus it is not
+possible to communicate how long the application should wait
+before attempting to resend, if the application wishes to
+resend the message. (More discussion with respect to message
+retries can be found in the *Handling Failures* section.)
-The RMR function ``rmr_call()`` sends a message in the exact
-same manner as the ``rmr_send_msg()()`` function, with the
-endpoint selection based on the message key. But unlike the
-send function, ``rmr_call()`` will block and wait for a
-response from the application that is selected to receive the
-message. The matching message is determined by the
-transaction ID which the application must place into the
-message buffer prior to invoking ``rmr_call()``. Similarly,
-the responding application must ensure that the same
-transaction ID is placed into the message buffer before
-returning its response.
-
-The return from the call is a message buffer with the
-response message; there is no difference between a message
-buffer returned by the receive function and one returned by
-the ``rmr_call()`` function. If a response is not received in
-a reasonable amount of time, a nil message buffer is returned
-to the calling application.
+The RMR function ``rmr_call()`` sends a message in the exact
+same manner as the ``rmr_send_msg()()`` function, with the
+endpoint selection based on the message key. But unlike the
+send function, ``rmr_call()`` will block and wait for a
+response from the application that is selected to receive the
+message. The matching message is determined by the
+transaction ID which the application must place into the
+message buffer prior to invoking ``rmr_call()``. Similarly,
+the responding application must ensure that the same
+transaction ID is placed into the message buffer before
+returning its response.
+
+The return from the call is a message buffer with the
+response message; there is no difference between a message
+buffer returned by the receive function and one returned by
+the ``rmr_call()`` function. If a response is not received in
+a reasonable amount of time, a nil message buffer is returned
+to the calling application.
-Because of the nature of RMR's routing policies, it is
-generally not possible for an application to control exactly
-which endpoint is sent a message. There are cases, such as
-responding to a message delivered via ``rmr_call()`` that the
-application must send a message and guarantee that RMR routes
-it to an exact destination. To enable this, RMR provides the
-``rmr_rts_msg(),`` return to sender, function. Upon receipt
-of any message, an application may alter the payload, and if
-necessary the message type and subscription ID, and pass the
-altered message buffer to the ``rmr_rts_msg()`` function to
-return the altered message to the application which sent it.
-When this function is used, RMR will examine the message
-buffer for the source information and use that to select the
-connection on which to write the response.
+Because of the nature of RMR's routing policies, it is
+generally not possible for an application to control exactly
+which endpoint is sent a message. There are cases, such as
+responding to a message delivered via ``rmr_call()`` that the
+application must send a message and guarantee that RMR routes
+it to an exact destination. To enable this, RMR provides the
+``rmr_rts_msg(),`` return to sender, function. Upon receipt
+of any message, an application may alter the payload, and if
+necessary the message type and subscription ID, and pass the
+altered message buffer to the ``rmr_rts_msg()`` function to
+return the altered message to the application which sent it.
+When this function is used, RMR will examine the message
+buffer for the source information and use that to select the
+connection on which to write the response.
-The basic call mechanism described above is **not** thread
-safe, as it is not possible to guarantee that a response
-message is delivered to the correct thread. The RMR function
-``rmr_mt_call()`` accepts an additional parameter which
-identifies the calling thread in order to ensure that the
-response is delivered properly. In addition, the application
-must specifically initialise the multi-threaded call
-environment by passing the ``RMRFL_MTCALL`` flag as an option
-to the ``rmr_init()`` function.
-
-One advantage of the multi-threaded call capability in RMR is
-the fact that only the calling thread is blocked. Messages
-received which are not responses to the call are continued to
-be delivered via normal ``rmr_rcv_msg()`` calls.
-
-While the process is blocked waiting for the response, it is
-entirely possible that asynchronous, non-matching, messages
-will arrive. When this happens, RMR will queues the messages
-and return them to the application over the next calls to
-``rmr_rcv_msg().``
+The basic call mechanism described above is **not** thread
+safe, as it is not possible to guarantee that a response
+message is delivered to the correct thread. The RMR function
+``rmr_mt_call()`` accepts an additional parameter which
+identifies the calling thread in order to ensure that the
+response is delivered properly. In addition, the application
+must specifically initialise the multi-threaded call
+environment by passing the ``RMRFL_MTCALL`` flag as an option
+to the ``rmr_init()`` function.
+
+One advantage of the multi-threaded call capability in RMR is
+the fact that only the calling thread is blocked. Messages
+received which are not responses to the call are continued to
+be delivered via normal ``rmr_rcv_msg()`` calls.
+
+While the process is blocked waiting for the response, it is
+entirely possible that asynchronous, non-matching, messages
+will arrive. When this happens, RMR will queues the messages
+and return them to the application over the next calls to
+``rmr_rcv_msg().``
-As was mentioned earlier, the design of RMR is to eliminate
-the need for an application to know a specific endpoint, even
-when a response message is being sent. In some rare cases it
-may be necessary for an application to establish a direct
-connection to an RMR-based application rather than relying on
-message type and subscription ID based routing. The
-*wormhole* functions provide an application with the ability
-to create a direct connection and then to send and receive
-messages across the connection. The following are the RMR
-functions which provide wormhole communications:
-
-
- .. list-table::
- :widths: auto
- :header-rows: 0
- :class: borderless
-
- * - **rmr_wh_open**
- -
- Open a connection to an endpoint. Name or IP address and port
- of the endpoint is supplied. Returns a wormhole ID that the
- application must use when sending a direct message.
-
- * - **rmr_wh_send_msg**
- -
- Sends an RMR message buffer to the connected application. The
- message type and subscription ID may be set in the message,
- but RMR will ignore both.
-
- * - **rmr_wh_close**
- -
- Closes the direct connection.
-
-
-
+As was mentioned earlier, the design of RMR is to eliminate
+the need for an application to know a specific endpoint, even
+when a response message is being sent. In some rare cases it
+may be necessary for an application to establish a direct
+connection to an RMR-based application rather than relying on
+message type and subscription ID based routing. The
+*wormhole* functions provide an application with the ability
+to create a direct connection and then to send and receive
+messages across the connection. The following are the RMR
+functions which provide wormhole communications:
+
+
+ .. list-table::
+ :widths: auto
+ :header-rows: 0
+ :class: borderless
+
+ * - **rmr_wh_open**
+ -
+ Open a connection to an endpoint. Name or IP address and port
+ of the endpoint is supplied. Returns a wormhole ID that the
+ application must use when sending a direct message.
+
+ * - **rmr_wh_send_msg**
+ -
+ Sends an RMR message buffer to the connected application. The
+ message type and subscription ID may be set in the message,
+ but RMR will ignore both.
+
+ * - **rmr_wh_close**
+ -
+ Closes the direct connection.
+
+
+
-In an effort to reduce the workload of an application
-developer, RMR has a default retry policy such that RMR will
-attempt to retransmit a message up to 1000 times when a soft
-failure is reported. These retries generally take less than 1
-millisecond (if all 1000 are attempted) and in most cases
-eliminates nearly all reported soft failures to the
-application. When using this mode, it might allow the
-application to simply treat all bad return values from a send
-attempt as permanent failures.
-
-If an application is so sensitive to any delay in RMR, or the
-underlying transport mechanism, it is possible to set RMR to
-return a failure immediately on any kind of error (permanent
-failures are always reported without retry). In this mode,
-RMR will still set the state in the message buffer to
-``RMR_ERR_RETRY,`` but will **not** make any attempts to
-resend the message. This zero-retry policy is enabled by
-invoking the ``rmr_set_stimeout()`` with a value of 0; this
-can be done once immediately after ``rmr_init()`` is invoked.
-
-Regardless of the retry mode which the application sets, it
-will ultimately be up to the application to handle failures
-by queuing the message internally for resend, retrying
-immediately, or dropping the send attempt all together. As
-stated before, only the application can determine how to best
-handle send failures.
+In an effort to reduce the workload of an application
+developer, RMR has a default retry policy such that RMR will
+attempt to retransmit a message up to 1000 times when a soft
+failure is reported. These retries generally take less than 1
+millisecond (if all 1000 are attempted) and in most cases
+eliminates nearly all reported soft failures to the
+application. When using this mode, it might allow the
+application to simply treat all bad return values from a send
+attempt as permanent failures.
+
+If an application is so sensitive to any delay in RMR, or the
+underlying transport mechanism, it is possible to set RMR to
+return a failure immediately on any kind of error (permanent
+failures are always reported without retry). In this mode,
+RMR will still set the state in the message buffer to
+``RMR_ERR_RETRY,`` but will **not** make any attempts to
+resend the message. This zero-retry policy is enabled by
+invoking the ``rmr_set_stimeout()`` with a value of 0; this
+can be done once immediately after ``rmr_init()`` is invoked.
+
+Regardless of the retry mode which the application sets, it
+will ultimately be up to the application to handle failures
+by queuing the message internally for resend, retrying
+immediately, or dropping the send attempt all together. As
+stated before, only the application can determine how to best
+handle send failures.
-RMR will return the state of processing for message based
-operations (send/receive) as the status in the message
-buffer. For non-message operations, state is returned to the
-caller as the integer return value for all functions which
-are not expected to return a pointer (e.g.
-``rmr_init()``.) The following are the RMR state constants
-and a brief description of their meaning.
-
-
- .. list-table::
- :widths: auto
- :header-rows: 0
- :class: borderless
-
- * - **RMR_OK**
- -
- state is good; operation finished successfully
-
- * - **RMR_ERR_BADARG**
- -
- argument passed to function was unusable
-
- * - **RMR_ERR_NOENDPT**
- -
- send/call could not find an endpoint based on msg type
-
- * - **RMR_ERR_EMPTY**
- -
- msg received had no payload; attempt to send an empty message
-
- * - **RMR_ERR_NOHDR**
- -
- message didn't contain a valid header
-
- * - **RMR_ERR_SENDFAILED**
- -
- send failed; errno may contain the transport provider reason
-
- * - **RMR_ERR_CALLFAILED**
- -
- unable to send the message for a call function; errno may
- contain the transport provider reason
-
- * - **RMR_ERR_NOWHOPEN**
- -
- no wormholes are open
-
- * - **RMR_ERR_WHID**
- -
- the wormhole id provided was invalid
-
- * - **RMR_ERR_OVERFLOW**
- -
- operation would have busted through a buffer/field size
-
- * - **RMR_ERR_RETRY**
- -
- request (send/call/rts) failed, but caller should retry
- (EAGAIN for wrappers)
-
- * - **RMR_ERR_RCVFAILED**
- -
- receive failed (hard error)
-
- * - **RMR_ERR_TIMEOUT**
- -
- response message not received in a reasonable amount of time
-
- * - **RMR_ERR_UNSET**
- -
- the message hasn't been populated with a transport buffer
-
- * - **RMR_ERR_TRUNC**
- -
- length in the received buffer is longer than the size of the
- allocated payload, received message likely truncated (length
- set by sender could be wrong, but we can't know that)
-
- * - **RMR_ERR_INITFAILED**
- -
- initialisation of something (probably message) failed
-
- * - **RMR_ERR_NOTSUPP**
- -
- the request is not supported, or RMR was not initialised for
- the request
-
-
-
-Depending on the underlying transport mechanism, and the
-nature of the call that RMR attempted, the system
-``errno`` value might reflect additional detail about the
-failure. Applications should **not** rely on errno as some
-transport mechanisms do not set it with any consistency.
+RMR will return the state of processing for message based
+operations (send/receive) as the status in the message
+buffer. For non-message operations, state is returned to the
+caller as the integer return value for all functions which
+are not expected to return a pointer (e.g.
+``rmr_init()``.) The following are the RMR state constants
+and a brief description of their meaning.
+
+
+ .. list-table::
+ :widths: auto
+ :header-rows: 0
+ :class: borderless
+
+ * - **RMR_OK**
+ -
+ state is good; operation finished successfully
+
+ * - **RMR_ERR_BADARG**
+ -
+ argument passed to function was unusable
+
+ * - **RMR_ERR_NOENDPT**
+ -
+ send/call could not find an endpoint based on msg type
+
+ * - **RMR_ERR_EMPTY**
+ -
+ msg received had no payload; attempt to send an empty message
+
+ * - **RMR_ERR_NOHDR**
+ -
+ message didn't contain a valid header
+
+ * - **RMR_ERR_SENDFAILED**
+ -
+ send failed; errno may contain the transport provider reason
+
+ * - **RMR_ERR_CALLFAILED**
+ -
+ unable to send the message for a call function; errno may
+ contain the transport provider reason
+
+ * - **RMR_ERR_NOWHOPEN**
+ -
+ no wormholes are open
+
+ * - **RMR_ERR_WHID**
+ -
+ the wormhole id provided was invalid
+
+ * - **RMR_ERR_OVERFLOW**
+ -
+ operation would have busted through a buffer/field size
+
+ * - **RMR_ERR_RETRY**
+ -
+ request (send/call/rts) failed, but caller should retry
+ (EAGAIN for wrappers)
+
+ * - **RMR_ERR_RCVFAILED**
+ -
+ receive failed (hard error)
+
+ * - **RMR_ERR_TIMEOUT**
+ -
+ response message not received in a reasonable amount of time
+
+ * - **RMR_ERR_UNSET**
+ -
+ the message hasn't been populated with a transport buffer
+
+ * - **RMR_ERR_TRUNC**
+ -
+ length in the received buffer is longer than the size of the
+ allocated payload, received message likely truncated (length
+ set by sender could be wrong, but we can't know that)
+
+ * - **RMR_ERR_INITFAILED**
+ -
+ initialisation of something (probably message) failed
+
+ * - **RMR_ERR_NOTSUPP**
+ -
+ the request is not supported, or RMR was not initialised for
+ the request
+
+
+
+Depending on the underlying transport mechanism, and the
+nature of the call that RMR attempted, the system
+``errno`` value might reflect additional detail about the
+failure. Applications should **not** rely on errno as some
+transport mechanisms do not set it with any consistency.
-Several environment variables are recognised by RMR which, in
-general, are used to define interfaces and listen ports (e.g.
-the route table update listen port), or debugging
-information. Generally this information is system controlled
-and thus RMR expects this information to be defined in the
-environment rather than provided by the application. The
-following is a list of the environment variables which RMR
-recognises:
-
-
- .. list-table::
- :widths: auto
- :header-rows: 0
- :class: borderless
-
- * - **RMR_BIND_IF**
- -
- The interface to bind to listen ports to. If not defined
- 0.0.0.0 (all interfaces) is assumed.
-
- * - **RMR_RTG_SVC**
- -
- The port RMR will listen on for route manager connections. If
- not defined 4561 is used.
-
- * - **RMR_SEED_RT**
- -
- Where RMR expects to find the name of the seed (static) route
- table. If not defined no static table is read.
-
- * - **RMR_RTG_ISRAW**
- -
- If the value set to 0, RMR expects the route table manager
- messages to be messages with and RMR header. If this is not
- defined messages are assumed to be "raw" (without an RMR
- header.
-
- * - **RMR_VCTL_FILE**
- -
- Provides a file which is used to set the verbose level of the
- route table collection thread. The first line of the file is
- read and expected to contain an integer value to set the
- verbose level. The value may be changed at any time and the
- route table thread will adjust accordingly.
-
- * - **RMR_SRC_NAMEONLY**
- -
- If the value of this variable is greater than 0, RMR will not
- permit the IP address to be sent as the message source. Only
- the host name will be sent as the source in the message
- header.
-
-
-
+Several environment variables are recognised by RMR which, in
+general, are used to define interfaces and listen ports (e.g.
+the route table update listen port), or debugging
+information. Generally this information is system controlled
+and thus RMR expects this information to be defined in the
+environment rather than provided by the application. The
+following is a list of the environment variables which RMR
+recognises:
+
+
+ .. list-table::
+ :widths: auto
+ :header-rows: 0
+ :class: borderless
+
+ * - **RMR_BIND_IF**
+ -
+ The interface to bind to listen ports to. If not defined
+ 0.0.0.0 (all interfaces) is assumed.
+
+ * - **RMR_RTG_SVC**
+ -
+ The port RMR will listen on for route manager connections. If
+ not defined 4561 is used.
+
+ * - **RMR_SEED_RT**
+ -
+ Where RMR expects to find the name of the seed (static) route
+ table. If not defined no static table is read.
+
+ * - **RMR_RTG_ISRAW**
+ -
+ If the value set to 0, RMR expects the route table manager
+ messages to be messages with and RMR header. If this is not
+ defined messages are assumed to be "raw" (without an RMR
+ header.
+
+ * - **RMR_VCTL_FILE**
+ -
+ Provides a file which is used to set the verbose level of the
+ route table collection thread. The first line of the file is
+ read and expected to contain an integer value to set the
+ verbose level. The value may be changed at any time and the
+ route table thread will adjust accordingly.
+
+ * - **RMR_SRC_NAMEONLY**
+ -
+ If the value of this variable is greater than 0, RMR will not
+ permit the IP address to be sent as the message source. Only
+ the host name will be sent as the source in the message
+ header.
+
+
+
-The state field reflects the state at the time the message
-buffer is returned to the calling application. For a send
-operation, if the state is not ``RMR_OK`` then the message
-buffer references the payload that could not be sent, and
-when the state is ``RMR_OK`` the buffer references a *fresh*
-payload that the application may fill in.
-
-When the state is not ``RMR_OK,`` C programmes may examine
-the global ``errno`` value which RMR will have left set, if
-it was set, by the underlying transport mechanism. In some
-cases, wrapper modules are not able to directly access the
-C-library ``errno`` value, and to assist with possible
-transport error details, the send and receive operations
-populate ``tp_state`` with the value of ``errno.``
-
-Regardless of whether the application makes use of the
-``tp_state,`` or the ``errno`` value, it should be noted that
-the underlying transport mechanism may not actually update
-the errno value; in other words: it might not be accurate. In
-addition, RMR populates the ``tp_state`` value in the message
-buffer **only** when the state is not ``RMR_OK.``
+The state field reflects the state at the time the message
+buffer is returned to the calling application. For a send
+operation, if the state is not ``RMR_OK`` then the message
+buffer references the payload that could not be sent, and
+when the state is ``RMR_OK`` the buffer references a *fresh*
+payload that the application may fill in.
+
+When the state is not ``RMR_OK,`` C programmes may examine
+the global ``errno`` value which RMR will have left set, if
+it was set, by the underlying transport mechanism. In some
+cases, wrapper modules are not able to directly access the
+C-library ``errno`` value, and to assist with possible
+transport error details, the send and receive operations
+populate ``tp_state`` with the value of ``errno.``
+
+Regardless of whether the application makes use of the
+``tp_state,`` or the ``errno`` value, it should be noted that
+the underlying transport mechanism may not actually update
+the errno value; in other words: it might not be accurate. In
+addition, RMR populates the ``tp_state`` value in the message
+buffer **only** when the state is not ``RMR_OK.``
-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.
+
+
+