X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=doc%2Fsrc%2Fman%2Frmr.7.xfm;fp=doc%2Fsrc%2Fman%2Frmr.7.xfm;h=4c3e13a883748a25c809b67db0e7fbc4e078affa;hb=fd9cc7a5b3355146388ebdf4d558cb284c66c5f1;hp=0000000000000000000000000000000000000000;hpb=008bc5b4414cebe48cecf63e8c817a02f7c3ce74;p=ric-plt%2Flib%2Frmr.git diff --git a/doc/src/man/rmr.7.xfm b/doc/src/man/rmr.7.xfm new file mode 100644 index 0000000..4c3e13a --- /dev/null +++ b/doc/src/man/rmr.7.xfm @@ -0,0 +1,135 @@ +.if false +================================================================================== + 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. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under 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 +.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 + +&line_len(6i) + +&h1(RMr Library) +&h2(NAME) + 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) +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. + +&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. + + +&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. + +&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. + +&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. + +&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 + + +&h2(SEE ALSO ) +.ju off +rmr_alloc_msg(3), +rmr_call(3), +rmr_free_msg(3), +rmr_init(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_ring_free(3), +rmr_torcv_msg(3), +rmr_wh_open(3), +rmr_wh_send_msg(3) +.ju on + + +.qu