X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=docs%2Fuser-guide.rst;h=a59239dfa4e5d6ac0031f24caa7beb7d6ee6edfb;hb=4d1f9bf4b14788f957964d93af940e84f8f01601;hp=c0b7bc8ad12f0f14b6bbe92e25dd2741605b76ae;hpb=6926c66052111119df8a3d2e7b9e4ddbbeea7910;p=ric-plt%2Flib%2Frmr.git diff --git a/docs/user-guide.rst b/docs/user-guide.rst index c0b7bc8..a59239d 100644 --- a/docs/user-guide.rst +++ b/docs/user-guide.rst @@ -128,8 +128,7 @@ xaction and wait for the reply; the underlying RMR processing expects that the matching reply message will also contain the same data in the *xaction* field. - - + sub_id @@ -147,21 +146,21 @@ tp_state For C applications making use of RMR, the state of a transport based failure will often be available via errno. - However, some wrapper environments may not have direct access - to the C-lib errno value. RMR send and receive operations - will place the current value of errno into this field which - should make it available to wrapper functions. User - applications are strongly cautioned against relying on the - value of errno as some transport mechanisms may not set this - value on all calls. This value should also be ignored any - time the message status is RMR_OK. + However, some wrapper environments may not have direct + access to the C-lib errno value. RMR send and receive + operations will place the current value of errno into this + field which should make it available to wrapper functions. + User applications are strongly cautioned against relying + on the value of errno as some transport mechanisms may not + set this value on all calls. This value should also be + ignored any time the message status is RMR_OK. RETURN VALUE -------------------------------------------------------------------------------------------- -The function returns a pointer to a rmr_mbuf structure, or NULL -on error. +The function returns a pointer to a rmr_mbuf structure, or +NULL on error. ERRORS -------------------------------------------------------------------------------------------- @@ -176,12 +175,12 @@ ENOMEM SEE ALSO -------------------------------------------------------------------------------------------- -rmr_tralloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), -rmr_init_trace(3), rmr_get_trace(3), rmr_get_trlen(3), -rmr_payload_size(3), rmr_send_msg(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_set_trace(3) +rmr_tralloc_msg(3), rmr_call(3), rmr_free_msg(3), +rmr_init(3), rmr_init_trace(3), rmr_get_trace(3), +rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(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_set_trace(3) NAME @@ -1214,12 +1213,15 @@ RMRFL_MTCALL Enable multi-threaded call support. - &ditem Some underlying transport providers (e.g. SI95) - enable locking to be turned off if the user application is - single threaded, or otherwise can guarantee that RMR - functions will not be invoked concurrently from different - threads. Turning off locking can help make message receipt - more efficient. If this flag is set when the underlying + +RMRFL_NOLOCK + + Some underlying transport providers (e.g. SI95) enable + locking to be turned off if the user application is single + threaded, or otherwise can guarantee that RMR functions + will not be invoked concurrently from different threads. + Turning off locking can help make message receipt more + efficient. If this flag is set when the underlying transport does not support disabling locks, it will be ignored. @@ -1257,24 +1259,194 @@ setup. The following variables will be used when found. -RMR_SEED_RT +RMR_ASYNC_CONN + + Allows the async connection mode to be turned off (by + setting the value to 0. When set to 1, or missing from the + environment, RMR will invoke the connection interface in + the transport mechanism using the non-blocking (async) + mode. This will likely result in many "soft failures" + (retry) until the connection is established, but allows + the application to continue unimpeeded should the + connection be slow to set up. + + +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. + + +RMR_CTL_PORT + + This variable defines the port that RMR should open for + communications with Route Manager, and other RMR control + applications. If not defined, the port 4561 is assumed. + + Previously, the RMR_RTG_SVC (route table generator service + port) was used to define this port. However, a future + version of Route Manager will require RMR to connect and + request tables, thus that variable is now used to supply + the Route Manager well known address and port. + + To maintain backwards compatablibility with the older + Route Manager versions, the presence of this variable in + the environment will shift RMR's behaviour with respect to + the default value used when RMR_RTG_SVC is **not** + defined. + + When RMR_CTL_PORT is **defined:** RMR assumes that Route + Manager requires RMR to connect and request table updates + is made, and the default well known address for Route + manager is used (routemgr:4561). + + When RMR_CTL_PORT is **undefined:** RMR assumes that Route + Manager will connect and push table updates, thus the + default listen port (4561) is used. - Assumes this is the filename of the seed route table file - to use. In normal situations, the library will wait for an - update from the route table generator (expected within a - few seconds of initialisation) before being able to send - messages. However, in some situations where a bootstrap - table is necessary, this is the means to supply it to the - library. + To avoid any possible misinterpretation and/or incorrect + assumptions on the part of RMR, it is recommended that + both the RMR_CTL_PORT and RMR_RTG_SVC be defined. In the + case where both variables are defined, RMR will behave + exactly as is communicated with the variable's values. RMR_RTG_SVC - The route table generator assumes that RMr is listening on - a well known port (4561) by default, but this environment - variable can be used to change the listening port if - needed. The value of the variable is expected to be just - the port. + The value of this variable depends on the Route Manager in + use. + + When the Route Manager is expecting to connect to an xAPP + and push route tables, this variable must indicate the + port which RMR should use to listen for these connections. + + When the Route Manager is expecting RMR to connect and + request a table update during initialisation, the variable + should be the host of the Route Manager process. + + The RMR_CTL_PORT variable (added with the support of + sending table update requests to Route manager), controls + the behaviour if this variable is not set. See the + description of that variable for details. + + +RMR_HR_LOG + + By default RMR writes messages to standard error + (incorrectly referred to as log messages) in human + readable format. If this environment variable is set to 0, + the format of standard error messages might be written in + some format not easily read by humans. If missing, a value + of 1 is assumed. + + +RMR_LOG_VLEVEL + + This is a numeric value which corresponds to the verbosity + level used to limit messages written to standard error. + The lower the number the less chatty RMR functions are + during execution. The following is the current + relationship between the value set on this variable and + the messages written: + + +0 + + Off; no messages of any sort are written. + + +1 + + Only critical messages are written (default if this + variable does not exist) + + +2 + + Errors and all messages written with a lower value. + + +3 + + Warnings and all messages written with a lower value. + + +4 + + Informational and all messages written with a lower + value. + + +5 + + Debugging mode -- all messages written, however this + requires RMR to have been compiled with debugging + support enabled. + + + +RMR_RTG_ISRAW + + **Deprecated.** Should be 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. + + This variable is only recognised when using the NNG + transport library as it is not possible to support NNG + "raw" communications with other transport libraries. It is + also necessary to match the value of this variable with + the capabilities of the Route Manager; at some point in + the future RMR will assume that all Route Manager messages + will arrive via an RMR connection and will ignore this + variable. + +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 *ready* until a table is received. The static route + table may contain both the route table (between newrt + start and end records), and the MEID map (between meid_map + start and end records) + +RMR_SRC_ID + + This is either the name or IP address which is placed into + outbound messages as the message source. This will used + when an RMR based application uses the rmr_rts_msg() + function to return a response to the sender. If not + supplied RMR will use the hostname which in some container + environments might not be routable. + + The value of this variable is also used for Route Manager + messages which are sent via an RMR connection. + +RMR_VCTL_FILE + + This supplies the name of a verbosity control file. The + core RMR functions do not produce messages unless there is + a critical failure. However, the route table collection + thread, not a part of the main message processing + component, can write additional messages to standard + error. If this variable is set, RMR will extract the + verbosity level for these messages (0 is silent) from the + first line of the file. Changes to the file are detected + and thus the level can be changed dynamically, however RMR + will only suss out this variable during initialisation, so + it is impossible to enable verbosity after startup. + +RMR_WARNINGS + + If set to 1, RMR will write some warnings which are + non-performance impacting. If the variable is not defined, + or set to 0, RMR will not write these additional warnings. RETURN VALUE @@ -1928,10 +2100,37 @@ ERRORS -------------------------------------------------------------------------------------------- The *state* field in the message buffer will indicate either -RMR_OK or RMR_ERR_EMPTY if an empty message was received. If -a nil pointer is returned, or any other state value was set -in the message buffer, errno will be set to one of the -following: +RMR_OK when the message receive process was successful and +the message can be used by the caller. Depending on the +underlying transport mechanism, one of the following RMR +error stats may be returned: + + + +RMR_ERR_EMPTY + + The message received had no payload, or was completely + empty. + + +RMR_ERR_TIMEOUT + + For some transport mechanisms, or if reading the receive + queue from multiple threads, it is possible for one thread + to find no data waiting when it queries the queue. When + this state is reported, the message buffer does not + contain message data and the user application should + reinvoke the receive function. + + +When an RMR error state is reported, the underlying errno +value might provide more information. The following is a list +of possible values that might accompany the states listed +above: + +RMR_ERR_EMPTY if an empty message was received. If a nil +pointer is returned, or any other state value was set in the +message buffer, errno will be set to one of the following: @@ -2653,6 +2852,46 @@ rmr_rts_msg(3), rmr_ready(3), rmr_mk_ring(3), rmr_ring_free(3), rmr_torcv_rcv(3), rmr_wh_send_msg(3) +NAME +-------------------------------------------------------------------------------------------- + +rmr_set_fack + +SYNOPSIS +-------------------------------------------------------------------------------------------- + + +:: + + #include + void rmr_set_fack( void* vctx ); + + + +DESCRIPTION +-------------------------------------------------------------------------------------------- + +The rmr_set_fack function enables *fast TCP acknowledgements* +if the underlying transport library supports it. This might +be useful for applications which must send messages as a +maximum rate. + +RETURN VALUE +-------------------------------------------------------------------------------------------- + +There is no return value. + +ERRORS +-------------------------------------------------------------------------------------------- + +This function does not generate any errors. + +SEE ALSO +-------------------------------------------------------------------------------------------- + +rmr_init(3), + + NAME -------------------------------------------------------------------------------------------- @@ -2755,7 +2994,7 @@ SYNOPSIS :: #include - int rmr_bytes2payload( rmr_mbuf_t* mbuf, unsigned char* data, int len ) + int rmr_set_trace( rmr_mbuf_t* mbuf, unsigned char* data, int len ) @@ -2789,6 +3028,99 @@ rmr_ring_free(3), rmr_str2meid(3), rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3) +NAME +-------------------------------------------------------------------------------------------- + +rmr_set_trace + +SYNOPSIS +-------------------------------------------------------------------------------------------- + + +:: + + #include + #include + void rmr_set_vlevel( int new_level ) + + + +DESCRIPTION +-------------------------------------------------------------------------------------------- + +The rmr_set_vlevel allows the user programme to set the +verbosity level which is used to determine the messages RMR +writes to standard error. The new_vlevel value must be one of +the following constants which have the indicated meanings: + + +RMR_VL_OFF + + Turns off all message writing. This includes the stats and + debugging messages generated by the route collector thread + which are normally affected only by the externally managed + verbose level file (and related environment variable). + + +RMR_VL_CRIT + + Write only messages of critical importance. From the point + of view of RMR, when a critical proper behaviour of the + library cannot be expected or guaranteed. + +RMR_VL_ERR + + Include error messages in the output. An error is an event + from which RMR has no means to recover. Continued proper + execution is likely except where the affected connection + and/or component mentioned in the error is concerned. + +RMR_VL_WARN + + Include warning messages in the output. A warning + indicates an event which is not considered to be normal, + but is expected and continued acceptable behaviour of the + system is assured. + +RMR_VL_INFO + + Include informational messagees in the output. + Informational messages include some diagnostic information + which explain the activities of RMR. + +RMR_VL_DEBUG + + Include all debugging messages in the output. Debugging + must have also been enabled during the build as a + precaution to accidentally enabling this level of output + as it can grossly affect performance. + + +generally RMR does not write messages to the standard error +device from *critical path* functions, therefore it is +usually not harmful to enable a verbosity level of either +RMR_VL_CRIT, or RMR_VL_ERR. + +Messages written from the route table collection thread are +still governed by the value placed into the verbose level +control file (see the man page for rmr_init()); those +messages are affected only when logging is completely +disabled by passing RMR_VL_OFF to this function. + +The verbosity level can also be set via an environment +variable prior to the start of the RMR based application. The +environment variable is read only during initialisation; if +the programme must change the value during execution, this +function must be used. The default value, if this function is +never called, and the environment variable is not present, is +RMR_VL_ERR. + +SEE ALSO +-------------------------------------------------------------------------------------------- + +rmr_init(3) + + NAME -------------------------------------------------------------------------------------------- @@ -3509,8 +3841,8 @@ rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(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_wh_send_msg(3), -rmr_wh_close(3) +rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_close(3), +rmr_wh_send_msg(3), rmr_wh_state(3) NAME @@ -3771,5 +4103,73 @@ 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_set_stimeout(3), rmr_wh_open(3), rmr_wh_close(3) +rmr_set_stimeout(3), rmr_wh_open(3), rmr_wh_close(3), +rmr_wh_state(3) + + +NAME +-------------------------------------------------------------------------------------------- + +rmr_wh_state + +SYNOPSIS +-------------------------------------------------------------------------------------------- + + +:: + + #include + int rmr_wh_state( void* vctx, rmr_whid_t whid ) + + + +DESCRIPTION +-------------------------------------------------------------------------------------------- + +The rmr_wh_state function will return the current state of +the connection associated with the given wormhole (whid). The +return value indicates whether the connection is open +(RMR_OK), or closed (any other return value). + +When using some transport mechanisms (e.g. NNG), it may not +be possible for RMR to know the actual state and the +connection may always be reported as "open." + +RETURN +-------------------------------------------------------------------------------------------- + +The following values are potential return values. + + + +RMR_OK + + The wormhole ID is valid and the connection is "open." + + +RMR_ERR_WHID + + THe wormhole ID passed into the function was not valid. + + +RMR_ERR_NOENDPT + + The wormhole is not open (not connected). + + +RMR_ERR_BADARG + + The context passed to the function was nil or invalid. + + +RMR_ERR_NOWHOPEN + + Wormholes have not been initialised (no wormhole open call + has been made). + + + +SEE ALSO +-------------------------------------------------------------------------------------------- +rmr_wh_open(3), rmr_wh_send_msg(3), rmr_wh_close(3)