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
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
--------------------------------------------------------------------------------------------
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
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.
-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
--------------------------------------------------------------------------------------------
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:
rmr_ring_free(3), rmr_torcv_rcv(3), rmr_wh_send_msg(3)
+NAME
+--------------------------------------------------------------------------------------------
+
+rmr_set_fack
+
+SYNOPSIS
+--------------------------------------------------------------------------------------------
+
+
+::
+
+ #include <rmr/rmr.h>
+ 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
--------------------------------------------------------------------------------------------
::
#include <rmr/rmr.h>
- 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 )
rmr_wh_open(3), rmr_wh_send_msg(3)
+NAME
+--------------------------------------------------------------------------------------------
+
+rmr_set_trace
+
+SYNOPSIS
+--------------------------------------------------------------------------------------------
+
+
+::
+
+ #include <rmr/rmr.h>
+ #include <rmr/rmr_logging.h>
+ 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
--------------------------------------------------------------------------------------------
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
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 <rmr/rmr.h>
+ 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)
Code Review / ric-plt / lib / rmr.git / blobdiff