X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=doc%2Fsrc%2Fman%2Frmr.7.xfm;h=e3725714e0fef6552e8fce5dbb75531d6f8f8daf;hb=0f231bf2bf5520a418156c965c669e411875dcf0;hp=2f2e47d47670a8c47f10cc2a3944a9dced6dd21c;hpb=392168d467d7949f391602f53f9fd62d2a64d12b;p=ric-plt%2Flib%2Frmr.git diff --git a/doc/src/man/rmr.7.xfm b/doc/src/man/rmr.7.xfm index 2f2e47d..e372571 100644 --- a/doc/src/man/rmr.7.xfm +++ b/doc/src/man/rmr.7.xfm @@ -1,7 +1,7 @@ .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. @@ -17,10 +17,10 @@ ================================================================================== .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 .gv e LIB lib @@ -28,17 +28,17 @@ &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. @@ -47,13 +47,13 @@ message, and in some cases whether that message was sent to multiple 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. &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 @@ -64,15 +64,115 @@ 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. +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 | [,] | [;]... +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 | | [...] +mme_del | [...] +meid_map | end | [| +&ex_end + +&space +The 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 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 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 +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. +and the defaults which RMR uses if undefined. +&space .** the list of environment vars supported .im &{lib}/man/env_var_list.im