Date 29 January 2019
.fi
-.** if formatting with tfm, the roff.im will cause roff output to be generated
-.** and rst.im will cause rst to be generated depending on OUTPUT_TYPE env
-.** var.
-.** if formatting with pfm, then pretty postscript will be generated
-
.gv e LIB lib
-.if pfm
- .im &{lib}/generic_ps.im
-.ei
- .gv e OUTPUT_RST use_rst
- .if .ev &use_rst 1 =
- .im &{lib}/rst.im
- .ei
- .im &{lib}/roff.im
- .fi
-.fi
+.im &{lib}/man/setup.im
&line_len(6i)
&space
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.
+response relationship when needed.
&h3(The Route Table)
-The library is supplied with a route table which maps message numbers to
+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
Once understood, the route table generator publishes a table that is ingested
by RMr and used for mapping messages to end points.
+.sp
+The following is a simple route table which causes message types 0 through 9 to
+be routed to specific applications:
+
+&ex_start
+newrt|start
+ mse|0|-1| %meid
+ mse|1|-1|app10:4560,app11:4560
+ mse|2|-1|app12:4560
+ mse|3|-1|app14:4560
+ mse|4|-1|app18:4560
+ mse|5|-1|app01:4560
+ mse|6|-1|app02:4560
+ mse|7|-1|app03:4560
+ mse|8|-1|app04:4560
+ mse|9|-1|app05:4560
+newrt|end
+&ex_end
+&space
+The special endpoint "%meid" indicates that the message type (0 in this case) is
+to be routed to the endpoint which has been listed as the "owner" for the meid
+appearing in the message.
+MEID ownership is communicated to RMR using the same Route Table Manager interface
+and by supplying a "table" such as the one below:
+
+&ex_start
+meid_map | start
+ mme_ar | control1 | meid000 meid001 meid002 meid003 meid004 meid005
+ mme_ar | control2 | meid100 meid101 meid102 meid103
+meid_map | end | 2
+&ex_end
+
+This table indicates that the application (endpoint) &ital(control1) "owns" 6 MEIDs
+and &ital(control2) owns 4.
+When message type 0 is sent, the MEID in the message will be used to select the
+endpoint via this table.
+
+&space
+The MEID table will update the existing owner relationships, and add new ones; it
+is necessary to send only the changes with the add/replace (mme_ar) entries in
+the table.
+When necessary, MEIDs can be deleted by adding an &cw(mme_del) record to the table.
+The following example illustrates how this might look:
+
+&ex_start
+meid_map | start
+ mme_ar | control1 | meid000 meid001 meid002 meid003 meid004 meid005
+ mme_ar | control2 | meid100 meid101 meid102 meid103
+ mme_del| meid200 meid401
+meid_map | end | 3
+&ex_end
+
+&h3(Route Table Syntax)
+The following illustrates the syntax for both the route table.
+
+&space
+&ex_start
+newrt | start
+mse | <message-type>[,<sender-endpoint>] | <sub-id> <roud-robin-grp>[;<round-robin-grp>]...
+newrt | end
+&ex_end
+&space
+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 that should receive the message type.
+If multiple round-robin groups are given, they must be separated by a semicolon, and
+
+&h3(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) or to
+delete one or more MEIDs (mme_del).
+The following is the syntax for the MEID map.
+
+&space
+&ex_start
+meid_map | start
+mme_ar | <owner-endpoint> | <meid> [<meid>...]
+mme_del | <meid> [<meid>...]
+meid_map | end | <count> [| <md5sum>
+&ex_end
+
+&space
+The <count> on the end record indicates the number of mme_ar and mme_del records
+which were sent; if the count does not match the whole map is refused and dropped.
+The <owner-endpoint> is the endpoint which should receive the message when a message
+is routed based on the MEID it contains.
+A MEID may be "owned" by only one endpoint, and if supplied multiple times, the last
+observed relationship is used.
+Each of the lists of MEIDs are blank separated.
+
+&space
+The optional <md5sum> on the &ital(end) record should be the computed MD5 hash for all
+records which appear between the start and and records.
+This allows for a tighter verification that all data was received exactly as the
+route manager transmitted them.
+
+
&h3(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.
+to the library.
The following is a list of the various environment variables, what they control
and the defaults which RMr uses if undefined.
-&beg_dlist(.75i : ^&bold_font )
-&di(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.
-
-&di(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.
-
-&di(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.
-
-&di(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 &ital(ready)
- until a table is received.
-&end_dlist
+&space
+.** the list of environment vars supported
+.im &{lib}/man/env_var_list.im
&h2(SEE ALSO )
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_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),
.ju on
-.qu