.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019 Nokia
+ Copyright (c) 2018-2019 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
==================================================================================
.fi
.if false
- Mnemonic rmr.7.xfm
- Abstract The manual page for the whole RMr library
- Author E. Scott Daniels
- Date 29 January 2019
+ Mnemonic rmr.7.xfm
+ Abstract The manual page for the whole RMR library
+ Author E. Scott Daniels
+ 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)
-&h1(RMr Library)
+&h1(RMR Library)
+
&h2(NAME)
- RMr -- Ric Message Router Library
+ RMR -- Ric Message Router Library
&h2(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)
+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., SI95)
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.
+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.
applications.
&space
-RMr functions do provide for the ability to respond to the specific source
+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
-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.
+The library must be given a route table which maps message 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.
&space
-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.
+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: &ital(rte) and
+&ital(mse).
-&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.
-The following is a list of the various environment variables, what they control
-and the defaults which RMr uses if undefined.
+&space
+A &ital(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.
+
+&ex_start
+ rte | 1 | app10:4560
+&ex_end
+
+&space
+The second type of entry is &ital(mse). This entry defines a message
+type, an optional sender application, a subscription ID, and a
+collection of endpoints. An example record appears next.
+&ex_start
+ mse | 1000,forwarder:43086 | 10 | app2:43086
+&ex_end
+
+&space
+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.
+
+.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
+
+&space
+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 types of route table entries.
+
+&space
+&ex_start
+newrt | start
+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
+&ex_end
-&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.
+&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 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.
+
+&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.
-&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.
+&space
+&ex_start
+meid_map | start
+mme_ar | <owner-endpoint> | <meid> [<meid>...]
+mme_del | <meid> [<meid>...]
+meid_map | end | <count> | <md5sum>
+&ex_end
-&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.
+&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.
+The following is a list of the various environment variables, what they control
+and the defaults which RMR uses if undefined.
-&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
+.** 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
Code Review / ric-plt / lib / rmr.git / blobdiff