--- /dev/null
+
+.. 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.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+
+RMR Overview
+============================================================================================
+
+
+RMr Library
+============================================================================================
+
+
+NAME
+--------------------------------------------------------------------------------------------
+
+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
+applications without having to understand the underlying
+messaging transport environment (e.g. Nanomsg) and without
+needing to know which other endpoint applications are
+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 user application) to an endpoint entry. Once determined,
+the message is sent directly to the endpoint. The user
+application is unaware of which endpoint actually receives
+the message, and in some cases whether that message was sent
+to multiple applications.
+
+RMr functions do provide for the ability to respond to the
+specific source instance of a message allowing for either a
+request response, or call response relationship when needed.
+
+The Route Table
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The library is supplied with 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.
+
+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
+for mapping messages to end points.
+
+Environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To enable configuration of the library behaviour outside 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
+if undefined.
+
+
+RMR_ASYNC_CONN
+
+ Allows the asynch 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 (asynch)
+ mode. This will likely result in many "soft failures"
+ (retry) until the connection is established, but allows
+ the application to continue unimpeeded 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.
+
+RMR_RTG_SVC
+
+ RMr opens a TCP listen socket using the port defined by
+ this environment variable and expects that the route table
+ generator process will connect to this port. If not
+ supplied the port 4561 is used.
+
+RMR_RTG_ISRAW
+
+ Is 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.
+
+RMR_SEED_RT
+
+ This is used to supply a static route table which can be
+ used for debugging, testing, or if no route table
+ generator process is being used to supply the route table.
+ If not defined, no static table is used and RMr will not
+ report *ready* until a table is received.
+
+RMR_SRC_ID
+
+ This is either the name or IP address which is placed into
+ outbound messages as the message source. This will used
+ when an RMR based application uses the rmr_rts_msg()
+ function to return a response to the sender. If not
+ supplied RMR will use the hostname which in some container
+ environments might not be routable.
+
+RMR_VCTL_FILE
+
+ This supplies the name of a verbosity control file. The
+ core RMR functions do not produce messages unless there is
+ a critical failure. However, the route table collection
+ thread, not a part of the main message processing
+ component, can write additional messages to standard
+ error. If this variable is set, RMR will extract the
+ verbosity level for these messages (0 is silent) from the
+ first line of the file. Changes to the file are detected
+ and thus the level can be changed dynamically, however RMR
+ will only suss out this variable during initialisation, so
+ it is impossible to enable verbosity after startup.
+
+RMR_WARNINGS
+
+ If set to 1, RMR will write some warnings which are
+ non-performance impacting. If the variable is not defined,
+ or set to 0, RMR will not write these additional warnings.
+
+
+SEE ALSO
+--------------------------------------------------------------------------------------------
+
+rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_call(3),
+rmr_free_msg(3), rmr_init(3), rmr_init_trace(3),
+rmr_get_meid(3), rmr_get_src(3), rmr_get_srcip(3),
+rmr_get_trace(3), rmr_get_trlen(3), rmr_get_xact(3),
+rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
+rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
+rmr_tokenise(3), rmr_mk_ring(3), rmr_realloc_payload(3),
+rmr_ring_free(3), rmr_set_trace(3), rmr_torcv_msg(3),
+rmr_wh_open(3), rmr_wh_send_msg(3)
Code Review / ric-plt / lib / rmr.git / blobdiff