Add ability to save route table updates to disk

[ric-plt/lib/rmr.git] / doc / src / library / rt_tables.xfm

diff --git a/doc/src/library/rt_tables.xfm b/doc/src/library/rt_tables.xfm
index 0e4b7e6..1649aac 100644 (file)
--- a/doc/src/library/rt_tables.xfm
+++ b/doc/src/library/rt_tables.xfm
@@ -273,7 +273,7 @@ The connection between RMR and the &RTMGR is also an RMR session and thus
 RMR messages will be used to exchange requests and responses.
 
 &h2(Table Request)
-During initialisation, RMR will establish a wormhole connection to the &RTMGR and sends
+During initialisation, RMR establishes a wormhole connection to the &RTMGR and sends
 a message type of &MT_REQ_TABLE to request a new table.
 RMR will continue to send table requests until a table is received and accepted; in other
 words it is fine for the &RTMGR to ignore the requests if it is not ready to respond.
@@ -299,23 +299,52 @@ Any other response indicates that RMR did not use the table and has dropped it;
 table is still in use.
 
 
+&h2(Using A Static Route Table)
+A static route table can be provided to assist with testing, or to provide a bootstrap set of
+route information until a dynamic table is received from a routing manager.
+The environment variable &cw(RMR_SEED_RT) is checked during RMR initialisation and
+if set is expected to reference a file containing a route table.
+This table will be loaded and used until overlaid by a table sent by the &RTMGR.
+&space
+
+To simulate dynamic reloads during testing, and for some specialised use cases,
+the static table will be reloaded periodically if the &cw(RMR_RTG_SVC) environment
+variable is set to -1.
+When set to -1 RMR will not listen for &RTMGR connections, nor will it attempt to request a dynamic table.
+
+&space
+If the file given by the &cw(RMR_SEED_RT) variable does not exist, and the &cw(RMR_RTG_SVC) variable
+is set to -1, RMR will block until the table is created.
+This simulates a delayed dynamic load during testing, and can be used when the xAPP is reading
+the route table saved by another local process rather than one sent directly by the &RTMGR.
+
+&h2(Table Stashing)
+To assist with debugging, and to allow an application to share the route table received from
+&RTMGR, RMR will stash the route table updates it received.
+Updates are stashed in a file named by the &cw(RMR_STASH_RT) environment variable, and if that
+variable is not present, the &cw(RR_SEED_RT) variable will be used with an added &cw(.stash) extension.
 
+&space
+The primary use of route table stashing is to assist with debugging of applications, and because there are
+risks for an application to share its table, table sharing is &bold(NOT) recommended.
+Table sharing can be enabled by setting the &cw(RMR_STASH_RT) variable for the application that will be
+the source of the route table updates, and using the file named for tha application when defining the
+&cw(RMR_SEED_RT) variable for applications which are to read the table information.
+Obviously, all applications must be running in the same container, on the same host, or have a
+common disk volum between their environments.
+Known risks to using table sharing include
+&half_space
 
-&h1(Providing A Static Table)
-For testing, or possibly bootstrapping purposes, a static route table can be supplied.
-During initialisation, RMR will check the &cw(RMR_SEED_RT) environment variable.
-If it exists, and references a file, RMR will open and read the file expecting to find
-a static route table.
-This route table is used until an update is received from a &RTMGR.
-Normally, when the RMR initialisation function is invoked, a listener is started to receive route table information from a route
-manager process.
-During testing it is often useful to supply a static table which is available should no route management process exist,
-or to provide a seed table to use before the first table is delivered.
-The environment variable &cw(RMR_SEED_RT)  can be set to provide the RMR initialisation function with the name
-of the static table to use.
-If a static table is provided, it will be loaded only once, and will be overlaid if
-a dynamically delivered table is received.
+&indent
+&beg_list(&lic1)
+&li An update to the table (not a complete table) may be received prior to one or more readers
+       accessing the file, and thus the reader may not receive a valid or complete table.
+&half_space
 
+&li Any entry which has a sender:port associated with the message type will likely be ignored
+       by all readers.
+&end_list
+&uindent
 
 
 &h1(Routing Using MEID)