X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=doc%2Fsrc%2Flibrary%2Fuser.xfm;h=ce3e5ddb0c7bd53031e34cb8ccc0b014ff993daa;hb=fe6a856df463a0d7e06b28aac8590ac9c0f08dd6;hp=6a2371b258c995dd125a5911273b912f1859bf34;hpb=d961525e9eb23e3dee4a16960a1772782c3b8b36;p=ric-plt%2Flib%2Frmr.git diff --git a/doc/src/library/user.xfm b/doc/src/library/user.xfm index 6a2371b..ce3e5dd 100644 --- a/doc/src/library/user.xfm +++ b/doc/src/library/user.xfm @@ -55,8 +55,8 @@ .dv doc_subtitle User's Manual .if pfm - .** add licence, a title page, and talbe of contents - .im front_junk.im + .** add licence, a title page, and table of contents + .im front_junk.im .ei .** for text based things, nothing more than license .im license.im @@ -80,8 +80,11 @@ .st &textsize &h1(Overview) -The RIC Message Router (a.k.a. RMR) is a thin library which provides a latency sensitive application with the ability -to send and receive messages with other RMR based applications. + +The RIC Message Router (RMR) is a library for peer-to-peer +communication. Applications use the library to send and receive +messages where the message routing and endpoint selection is based on +the message type rather than DNS host name-IP port combinations. The library provides the following major features: &half_space @@ -96,63 +99,74 @@ The library provides the following major features: &li Message distribution (round robin or fanout) is selectable by message type. &half_space - &li Route management updates are received and processed asynchronously and without overt - application involvement. + &li Route management updates are received and processed + asynchronously and without overt application involvement. &end_list &uindent &space &h2(Purpose) -RMR's main purpose is to provide an application with the ability to send and receive messages to/from other -peer applications with minimal effort on the application's part. -To achieve this, RMR manages manages all endpoint information, connections, and routing information necessary -to establish and maintain communication. -From the application's point of view, all that is required to send a message is to allocate (via RMR) a message -buffer, add the payload data, and set the message type. -To receive a message, the application needs only to invoke the receive function; when a message -arrives a message buffer will be returned as the function result. - +RMR's main purpose is to provide an application with the ability to +send and receive messages to/from other peer applications with minimal +effort on the application's part. To achieve this, RMR manages all +endpoint information, connections, and routing information necessary +to establish and maintain communication. From the application's point +of view, all that is required to send a message is to allocate (via +RMR) a message buffer, add the payload data, and set the message type. +To receive a message, the application needs only to invoke the receive +function; when a message arrives a message buffer will be returned as +the function result. &h2(Message Routing) -Applications are required to place a message type into a message before sending, and may optionally add a -subscription ID when appropriate. -The combination of message type, and subscription ID are refered to as the &ital(message key,) -and is used to match an entry in a routing table which provides the possible endpoints expecting -to receive messages with the matching key. +Applications are required to place a message type into a message +before sending, and may optionally add a subscription ID when +appropriate. The combination of message type, and subscription ID are +refered to as the &ital(message key,) and is used to match an entry in +a routing table which provides the possible endpoints expecting to +receive messages with the matching key. &h3(Round Robin Delivery) -An endpoint from RMR's perspective is an application to which RMR may establish a connection, and expect to -send messages with one or more defined message keys. -Each entry in the route table consists of one or more endpoint groups, called round robin groups. -When a message matches a specific entry, the entry's groups are used to select the destination of the message. -A message is sent once to each group, with messages being &ital(balanced) across the endpoints of a group -via round robin selection. -Care should be taken when defining multiple groups for a message type as there is extra overhead required -and thus the overall message latency is somewhat reduced. +An endpoint from RMR's perspective is an application to which RMR may +establish a connection, and expect to send messages with one or more +defined message keys. Each entry in the route table consists of one +or more endpoint groups, called round robin groups. When a message +matches a specific entry, the entry's groups are used to select the +destination of the message. A message is sent once to each group, +with messages being &ital(balanced) across the endpoints of a group +via round robin selection. Care should be taken when defining +multiple groups for a message type as there is extra overhead required +and thus the overall message latency is somewhat increased. &h3(Routing Table Updates) -Route table information is made available to RMR a static file (loaded once), or by updates sent from a -separate route manager application. -If a static table is provided, it is loaded during RMR initialisation and will remain in use until -an external process connects and delivers a route table update (often referred to as a dynamic update). -Dynamic updates are listened for in a separate process thread and applied automatically; the application does not -need to allow for, or trigger, updates. +Route table information is made available to RMR a static file (loaded +once), or by updates sent from a separate route manager application. +If a static table is provided, it is loaded during RMR initialization +and will remain in use until an external process connects and delivers +a route table update (often referred to as a dynamic update). Dynamic +updates are listened for in a separate process thread and applied +automatically; the application does not need to allow for, or trigger, +updates. &h2(Latency And Throughput) -While providing insulation from the underlying message transport mechanics, RMR must also do so in such a -manner that message latency and throughput are not impacted. -In general, the RMR induced overhead, incurred due to the process of selecting an endpoint for each message, -is minimal and should not impact the overall latency or throughput of the application. -This impact has been measured with test applications running on the same physical host and the average -latency through RMR for a message was on the order of 0.02 milliseconds. +While providing insulation from the underlying message transport +mechanics, RMR must also do so in such a manner that message latency +and throughput are not impacted. In general, the RMR induced +overhead, incurred due to the process of selecting an endpoint for +each message, is minimal and should not impact the overall latency or +throughput of the application. This impact has been measured with +test applications running on the same physical host and the average +latency through RMR for a message was on the order of 0.02 +milliseconds. &space -As an application's throughput increases, it becomes easy for the application to overrun the underlying -transport mechanism (e.g. NNG), consume all available TCP transmit buffers, or otherwise find itself -in a situation where a send might not immediately complete. -RMR offers different &ital(modes) which allow the application to manage these states based on the -overall needs of the application. -These modes are discussed in the &ital(Configuration) section of this document. +As an application's throughput increases, it becomes easy for the +application to overrun the underlying transport mechanism (e.g. NNG), +consume all available TCP transmit buffers, or otherwise find itself +in a situation where a send might not immediately complete. RMR +offers different &ital(modes) which allow the application to manage +these states based on the overall needs of the application. These +modes are discussed in the &ital(Configuration) section of this +document. .** snarf in the major sections (to avoid one huge source document and maybe to promote reuse)