Various RMr man pages. These are maintained in {X}fm format which allows
them to be rendered into one of these formats:
- Postscript
- troff
- rst
- markdown
- html
+ Postscript
+ troff
+ rst
+ markdown
+ html
Troff is generated and installed into deb packages such that 'man rmr_call'
.** vim: ts=4 noet sw=42
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
.fi
.if false
- Mnemonic: env_list_vars.im
- Abstract: This is a list of environment variables which are recognised
- by RMR. This is an embed file as it is referenced by both
- manual pages and the 'read the docs' source (allowing a single
- point of maintenance).
-
- Date: 6 November 2019 (broken from the main manual page)
- Author: E. Scott Daniels
+ Mnemonic: env_list_vars.im
+ Abstract: This is a list of environment variables which are recognised
+ by RMR. This is an embed file as it is referenced by both
+ manual pages and the 'read the docs' source (allowing a single
+ point of maintenance).
+
+ Date: 6 November 2019 (broken from the main manual page)
+ Author: E. Scott Daniels
.fi
&beg_dlist(.75i : ^&bold_font )
&ditem(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.
- &half_space
-
-&ditem(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.
- &half_space
-
-&ditem(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.
-
- &space
- Previously, the &cw(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.
-
- &space
- 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 &cw(RMR_RTG_SVC) is &bold(not) defined.
-
- &space
- When &cw(RMR_CTL_PORT) is &bold(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).
-
- &space
- When &cw(RMR_CTL_PORT) is &bold(undefined^:)
- RMR assumes that Route Manager will connect and push table updates, thus the
- default listen port (4561) is used.
-
- &space
- To avoid any possible misinterpretation and/or incorrect assumptions on the part
- of RMR, it is recommended that both the &cw(RMR_CTL_PORT) and &cw(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.
- &half_space
-
-&ditem(RMR_RTG_SVC)
- The value of this variable depends on the Route Manager in use.
- &space
- When the Route Manager is expecting to connect to an xAPP and push
- route tables, this variable must indicate the &cw(port) which RMR should
- use to listen for these connections.
-
- &space
- When the Route Manager is expecting RMR to connect and request a
- table update during initialisation, the variable should be the
- &cw(host:port) of the Route Manager process.
-
- &space
- The &cw(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.
- &half_space
-
-&ditem(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.
- &half_space
+ 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 unimpeded should the
+ connection be slow to set up.
+ &half_space
+
+&ditem(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.
+ &half_space
+
+&ditem(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.
+
+ &space
+ Previously, the &cw(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's well-known address and port.
+
+ &space
+ To maintain backwards compatibility 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 &cw(RMR_RTG_SVC) is &bold(not) defined.
+
+ &space
+ When &cw(RMR_CTL_PORT) is &bold(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).
+
+ &space
+ When &cw(RMR_CTL_PORT) is &bold(undefined^:)
+ RMR assumes that Route Manager will connect and push table updates, thus the
+ default listen port (4561) is used.
+
+ &space
+ To avoid any possible misinterpretation and/or incorrect assumptions on the part
+ of RMR, it is recommended that both the &cw(RMR_CTL_PORT) and &cw(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.
+ &half_space
+
+&ditem(RMR_RTG_SVC)
+ The value of this variable depends on the Route Manager in use.
+ &space
+ When the Route Manager is expecting to connect to an xAPP and push
+ route tables, this variable must indicate the &cw(port) which RMR should
+ use to listen for these connections.
+
+ &space
+ When the Route Manager is expecting RMR to connect and request a
+ table update during initialisation, the variable should be the
+ &cw(host:port) of the Route Manager process.
+
+ &space
+ The &cw(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.
+ &half_space
+
+&ditem(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.
+ &half_space
&ditem(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:
-
- &beg_dlist(.25i : &bold_font )
- &ditem(0) Off; no messages of any sort are written.
- &half_space
- &ditem(1) Only critical messages are written (default if this variable does not exist)
- &half_space
- &ditem(2) Errors and all messages written with a lower value.
- &half_space
- &ditem(3) Warnings and all messages written with a lower value.
- &half_space
- &ditem(4) Informational and all messages written with a lower value.
- &half_space
- &ditem(5) Debugging mode -- all messages written, however this requires RMR to have been compiled with debugging support enabled.
- &end_dlist
- &half_space
-
-&ditem(RMR_RTG_ISRAW)
- &bold(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.
- &half_space
- 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.
+ 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:
+
+ &beg_dlist(.25i : &bold_font )
+ &ditem(0) Off; no messages of any sort are written.
+ &half_space
+ &ditem(1) Only critical messages are written (default if this variable does not exist)
+ &half_space
+ &ditem(2) Errors and all messages written with a lower value.
+ &half_space
+ &ditem(3) Warnings and all messages written with a lower value.
+ &half_space
+ &ditem(4) Informational and all messages written with a lower value.
+ &half_space
+ &ditem(5) Debugging mode -- all messages written, however this requires RMR to have been compiled with debugging support enabled.
+ &end_dlist
+ &half_space
+
+&ditem(RMR_RTG_ISRAW)
+ &bold(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.
+ &half_space
+ 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.
&ditem(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.
- 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)
+ 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.
+ 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).
&ditem(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.
- &half_space
- The value of this variable is also used for Route Manager messages which are
- sent via an RMR connection.
+ 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.
+ &half_space
+ The value of this variable is also used for Route Manager messages which are
+ sent via an RMR connection.
&ditem(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 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.
&ditem(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.
+ impacting. If the variable is not defined, or set to 0, RMR will not write these
+ additional warnings.
&end_dlist
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
.fi
.if false
- Mnemonic: retry.im
- Abstract: Common text for all send operation functions. This should be imbedded by any
- function which will ultimately use the internal send_msg funciton which
- governs retries in this manner.
- Date: 16 July 2019
+ Mnemonic: retry.im
+ Abstract: Common text for all send operation functions. This should be imbedded by any
+ function which will ultimately use the internal send_msg funciton which
+ governs retries in this manner.
+ Date: 16 July 2019
.fi
&h3(Retries)
-The send operations in RMr will retry &ital(soft) send failures until one of three
+The send operations in RMR will retry &ital(soft) send failures until one of three
conditions occurs:
&half_space
&indent
&beg_dlist( 0.3i : ^&bold_font )
- &di(1.) The message is sent without error
- &half_space
+ &di(1.) The message is sent without error
+ &half_space
- &di(2.) The underlying transport reports a &ital( hard ) failure
- &half_space
+ &di(2.) The underlying transport reports a &ital(hard) failure
+ &half_space
- &di(3.) The maximum number of retry loops has been attempted
- &end_dlist
+ &di(3.) The maximum number of retry loops has been attempted
+ &end_dlist
&uindent
&space
-A retry loop consists of approximately 1000 send attemps &bold( without) any intervening
-calls to &ital( sleep() ) or &ital( usleep(). )
+A retry loop consists of approximately 1000 send attempts &bold(without) any intervening
+calls to &ital(sleep()) or &ital(usleep().)
The number of retry loops defaults to 1, thus a maximum of 1000 send attempts is performed
before returning to the user application.
-This value can be set at any point after RMr initialisation using the &ital( rmr_set_stimeout() )
+This value can be set at any point after RMr initialisation using the &ital(rmr_set_stimeout())
function allowing the user application to completely disable retires (set to 0), or to
increase the number of retry loops.
&space
It should be noted that depending on the underlying transport mechanism being used, it is
-extremly possible that during normal operations that retry conditions are very likely to
-happen.
-These are completely out of RMr's control, and there is nothing that RMr can do to avoid or midigate
-these other than by allowing RMr to retry the send operation, and even then it is possible
-(e.g. during connection reattempts), that a single retry loop is not enough to guarentee a
+extremely likely that retry conditions will happen during normal operations.
+These are completely out of RMR's control, and there is nothing that RMR can do to avoid or mitigate
+these other than by allowing RMR to retry the send operation, and even then it is possible
+(e.g., during connection reattempts), that a single retry loop is not enough to guarantee a
successful send.
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
==================================================================================
.fi
.if false
- Mnemonic rmr.7.xfm
- Abstract The manual page for the whole RMr library
- Author E. Scott Daniels
- Date 29 January 2019
+ Mnemonic rmr.7.xfm
+ Abstract The manual page for the whole RMr library
+ Author E. Scott Daniels
+ Date 29 January 2019
.fi
.gv e LIB lib
&h1(RMr Library)
&h2(NAME)
- RMr -- Ric Message Router Library
+ 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)
+without having to understand the underlying messaging transport environment (e.g., SI95)
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.
&ex_end
This table indicates that the application (endpoint) &ital(control1) "owns" 6 MEIDs
-and &ital(control2) owns 4.
+and &ital(control2) owns 4.
When message type 0 is sent, the MEID in the message will be used to select the
endpoint via this table.
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
==================================================================================
.fi
.if false
- Mnemonic rmr_alloc_msg.xfm
- Abstract The manual page for the rmr_alloc_msg function.
- Author E. Scott Daniels
- Date 28 January 2019
+ Mnemonic rmr_alloc_msg.xfm
+ Abstract The manual page for the rmr_alloc_msg function.
+ Author E. Scott Daniels
+ Date 28 January 2019
.fi
.gv e LIB lib
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_alloc_msg
+ rmr_alloc_msg
&h2(SYNOPSIS )
&indent
int len;
unsigned char* payload;
unsigned char* xaction;
- int sub_id;
- int tp_state;
+ int sub_id;
+ int tp_state;
} rmr_mbuf_t;
&ex_end
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
.fi
.if false
- Mnemonic rmr_bytes2meid.xfm
- Abstract The manual page for the rmr_bytes2meid function.
- Author E. Scott Daniels
- Date 8 March 2019
+ Mnemonic rmr_bytes2meid.xfm
+ Abstract The manual page for the rmr_bytes2meid function.
+ Author E. Scott Daniels
+ Date 8 March 2019
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_bytes2meid
+ rmr_bytes2meid
&h2(SYNOPSIS)
&indent
&uindent
&h2(DESCRIPTION)
-The &cw(rmr_bytes2meid) function will copy up to &ital(len) butes from &ital(src) to the
-managed entity ID (meid) field in the message.
+The &cw(rmr_bytes2meid) function will copy up to &ital(len) butes from &ital(src) to the
+managed entity ID (meid) field in the message.
The field is a fixed length, gated by the constant &cw(RMR_MAX_MEID) and if len is larger
than this value, only RMR_MAX_MEID bytes will actually be copied.
&half_space
&di(EOVERFLOW) The length passed in was larger than the maximum length of the field; only a portion of
- the source bytes were copied.
+ the source bytes were copied.
&end_dlist
&h2(EXAMPLE)
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
.fi
.if false
- Mnemonic rmr_bytes2payload.xfm
- Abstract The manual page for the rmr_bytes2payload function.
- Author E. Scott Daniels
- Date 8 March 2019
+ Mnemonic rmr_bytes2payload.xfm
+ Abstract The manual page for the rmr_bytes2payload function.
+ Author E. Scott Daniels
+ Date 8 March 2019
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_bytes2payload
+ rmr_bytes2payload
&h2(SYNOPSIS)
&indent
directly copy into the payload buffer.
The bytes from &ital(src) for the length given are copied to the payload.
It is the caller's responsibility to ensure that the payload is large enough.
-Upon successfully copy, the &cw(len) field in the message buffer is updated to
+Upon successfully copy, the &cw(len) field in the message buffer is updated to
reflect the number of bytes copied.
.sp
There is little error checking, and no error reporting.
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
.fi
.if false
- Mnemonic rmr_bytes2xact.xfm
- Abstract The manual page for the rmr_bytes2xact function.
- Author E. Scott Daniels
- Date 8 March 2019
+ Mnemonic rmr_bytes2xact.xfm
+ Abstract The manual page for the rmr_bytes2xact function.
+ Author E. Scott Daniels
+ Date 8 March 2019
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_bytes2xact
+ rmr_bytes2xact
&h2(SYNOPSIS)
&indent
&uindent
&h2(DESCRIPTION)
-The &cw(rmr_bytes2xact) function will copy up to &ital(len) butes from &ital(src) to the
-transaction ID (xaction) field in the message.
+The &cw(rmr_bytes2xact) function will copy up to &ital(len) butes from &ital(src) to the
+transaction ID (xaction) field in the message.
The field is a fixed length, gated by the constant &cw(RMR_MAX_XID) and if len is larger
than this value, only RMR_MAX_XID bytes will actually be copied.
&half_space
&di(EOVERFLOW) The length passed in was larger than the maximum length of the field; only a portion of
- the source bytes were copied.
+ the source bytes were copied.
&end_dlist
&h2(EXAMPLE)
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
.if false
- Mnemonic rmr_call_man.xfm
- Abstract The manual page for the rmr_call function.
- Author E. Scott Daniels
- Date 28 January 2019
+ Mnemonic rmr_call_man.xfm
+ Abstract The manual page for the rmr_call function.
+ Author E. Scott Daniels
+ Date 28 January 2019
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_call
+ rmr_call
&h2(SYNOPSIS )
&indent
&space
Messages which are received while waiting for the response are queued internally
-by RMR, and are returned to the user application when &cw(rmr_rcv_msg) is
+by RMR, and are returned to the user application when &cw(rmr_rcv_msg) is
invoked.
-These messages are returned in th order received, one per call to &cw(rmr_rcv_msg.)
+These messages are returned in the order received, one per call to &cw(rmr_rcv_msg.)
&h3(Call Timeout)
The &cw(rmr_call) function implements a timeout failsafe to prevent, in most cases, the
-function from blocking forever.
+function from blocking forever.
The timeout period is &bold(not) based on time (calls to clock are deemed too expensive
-for a low latency system level library, but instead the period is based on the number of
-received messages which are not the response.
+for a low latency system level library), but instead the period is based on the number of
+received messages which are not the response.
Using a non-time mechanism for &ital(timeout) prevents the async queue from filling
(which would lead to message drops) in an environment where there is heavy message traffic.
&space
When the threshold number of messages have been queued without receiving a response message,
-control is returned to the user application and a NULL pointer is returned to indicate that
+control is returned to the user application and a nil pointer is returned to indicate that
no message was received to process.
Currently the threshold is fixed at 20 messages, though in future versions of the library
this might be extended to be a parameter which the user application may set.
.** pull in common retry text
-.im &{lib}/man/retry.im
+.im &{lib}/man/retry.im
&h2(RETURN VALUE)
The &cw(rmr_call) function returns a pointer to a message buffer with the state set to reflect
-the overall state of call processing (see Errors below).
-In some cases a NULL pointer will be returned; when this is the case only &ital(errno)
+the overall state of call processing (see Errors below).
+In some cases a nil pointer will be returned; when this is the case only &ital(errno)
will be available to describe the reason for failure.
&h2(ERRORS)
-These values are reflected in the state field of the returned message.
+These values are reflected in the state field of the returned message.
&half_space
&beg_dlist(.75i : ^&bold_font )
&di(RMR_OK) The call was successful and the message buffer references the response message.
&half_space
-&di(RMR_ERR_CALLFAILED) The call failed and the value of &ital(errno,) as described below,
- should be checked for the specific reason.
+&di(RMR_ERR_CALLFAILED) The call failed and the value of &ital(errno,) as described below,
+ should be checked for the specific reason.
&end_dlist
&space
-The global "variable" &ital(errno) will be set to one of the following values if the
-overall call processing was not successful.
+The global "variable" &ital(errno) will be set to one of the following values if the
+overall call processing was not successful.
&half_space
&beg_dlist(.75i : ^&bold_font )
&half_space
&di(EINVAL) A parameter was not valid
&half_space
-&di(EAGAIN) The underlying message system wsa interrupted or the device was busy;
- the message was &bold(not) sent, and user application should call
- this function with the message again.
+&di(EAGAIN) The underlying message system was interrupted or the device was busy;
+ the message was &bold(not) sent, and the user application should call
+ this function with the message again.
&end_dlist
&h2(EXAMPLE)
-The following code bit shows one way of using the &cw(rmr_call) function, and illustrates
+The following code snippet shows one way of using the &cw(rmr_call) function, and illustrates
how the transaction ID must be set.
&space
static rmr_mbuf_t* mbuf = NULL; // response msg
msg_t* pm; // private message (payload)
- // get a send buffer and reference the payload
+ // get a send buffer and reference the payload
mbuf = rmr_alloc_msg( mr, RMR_MAX_RCV_BYTES );
pm = (msg_t*) mbuf->payload;
- // generate an xaction ID and fill in payload with data and msg type
+ // generate an xaction ID and fill in payload with data and msg type
snprintf( mbuf->xaction, RMR_MAX_XID, "%s", gen_xaction() );
snprintf( pm->req, sizeof( pm->req ), "{ \"req\": \"num users\"}" );
mbuf->mtype = MT_REQ;
-
+
msg = rmr_call( mr, msg );
if( ! msg ) { // probably a timeout and no msg received
return NULL; // let errno trickle up
- }
+ }
if( mbuf->state != RMR_OK ) {
while( retries_left-- > 0 && // loop as long as eagain
- errno == EAGAIN &&
- (msg = rmr_call( mr, msg )) != NULL &&
+ errno == EAGAIN &&
+ (msg = rmr_call( mr, msg )) != NULL &&
mbuf->state != RMR_OK ) {
usleep( retry_delay );
}
-
+
if( mbuf == NULL || mbuf->state != RMR_OK ) {
rmr_free_msg( mbuf ); // safe if nil
return NULL;
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
.fi
.if false
- Mnemonic rmr_close.3.xfm
- Abstract The manual page for the rmr_close function.
- Author E. Scott Daniels
- Date 21 February 2019
+ Mnemonic rmr_close.3.xfm
+ Abstract The manual page for the rmr_close function.
+ Author E. Scott Daniels
+ Date 21 February 2019
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_wh_open
+ rmr_close
&h2(SYNOPSIS)
&indent
&h2(DESCRIPTION)
The &cw(rmr_close) function closes the listen socket effectively cutting the application
off.
-The route table listener is also stopped.
+The route table listener is also stopped.
Calls to rmr_rcv_msg() will fail with unpredictable error codes, and calls to rmr_send_msg(),
rmr_call(), and rmr_rts_msg() will have unknown results.
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
.fi
.if false
- Mnemonic rmr_free_msg_man.xfm
- Abstract The manual page for the rmr_free_msg function.
- Author E. Scott Daniels
- Date 28 January 2019
+ Mnemonic rmr_free_msg_man.xfm
+ Abstract The manual page for the rmr_free_msg function.
+ Author E. Scott Daniels
+ Date 28 January 2019
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_free_msg
+ rmr_free_msg
&h2(SYNOPSIS )
&indent
&h2(DESCRIPTION)
The message buffer is returned to the pool, or the associated memory is
-released depending on the needs of the underlying messaging system.
-This allows the user application to release a buffer that is not going
+released depending on the needs of the underlying messaging system.
+This allows the user application to release a buffer that is not going
to be used.
-It is safe to pass a nil pointer to this function, and doing so does
+It is safe to pass a nil pointer to this function, and doing so does
not result in a change to the value of &cw(errrno.)
&space
-After calling, the user application should &bold(not) use any of the
+After calling, the user application should &bold(not) use any of the
pointers (transaction ID, or payload) which were available.
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
.fi
.if false
- Mnemonic rmr_get_meid.xfm
- Abstract The manual page for the rmr_get_meid function.
- Author E. Scott Daniels
- Date 8 March 2019
+ Mnemonic rmr_get_meid.xfm
+ Abstract The manual page for the rmr_get_meid function.
+ Author E. Scott Daniels
+ Date 8 March 2019
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_get_meid
+ rmr_get_meid
&h2(SYNOPSIS)
&indent
&h2(DESCRIPTION)
The &cw(rmr_get_meid) function will copy the managed entity ID (meid) field from the message
-into the &ital(dest) buffer provided by the user.
+into the &ital(dest) buffer provided by the user.
The buffer referenced by &ital(dest) is assumed to be at least &cw(RMR_MAX_MEID) bytes in length.
If &ital(dest) is NULL, then a buffer is allocated (the calling application is expected
to free when the buffer is no longer needed).
&h2(RETURN VALUE)
-On success, a pointer to the extracted string is returned.
+On success, a pointer to the extracted string is returned.
If &ital(dest) was supplied, then this is just a pointer to the caller's buffer.
If &ital(dest) was NULL, this is a pointer to the allocated buffer.
If an error occurs, a nil pointer is returned and errno is set as described below.
&h2(ERRORS)
-If an error occurs, the value of the global variable &cw(errno) will be set to one of
+If an error occurs, the value of the global variable &cw(errno) will be set to one of
the following with the indicated meaning.
&beg_dlist(.75i : ^&bold_font )
&di(EINVAL) The message, or an internal portion of the message, was corrupted or the pointer was invalid.
&half_space
-&di(ENOMEM) A nil pointer was passed for &ital(dest,) however it was not possible to allocate a
- buffer using malloc().
+&di(ENOMEM) A nil pointer was passed for &ital(dest,) however it was not possible to allocate a
+ buffer using malloc().
&end_dlist
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
.fi
.if false
- Mnemonic rmr_get_rcvfd.3.xfm
- Abstract The manual page for the rmr_get_rcvfd function.
- Author E. Scott Daniels
- Date 11 February 2019
+ Mnemonic rmr_get_rcvfd.3.xfm
+ Abstract The manual page for the rmr_get_rcvfd function.
+ Author E. Scott Daniels
+ Date 11 February 2019
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_get_rcvfd
+ rmr_get_rcvfd
&h2(SYNOPSIS)
&indent
by an application that wishes to use event poll in a single thread rather than block
on the arrival of a message via calls to rmr_rcv_msg().
When epoll_wait() indicates that this file descriptor is ready, a call to rmr_rcv_msg()
-will not block as at least one message has been received.
+will not block as at least one message has been received.
&space
The context (ctx) pointer passed in is the pointer returned by the call to rmr_init().
-&space
-&bold(NOTE^:) There is no support for epoll in Nanomsg, thus his function is only supported
-when linking with the NNG version of RMr and the file descriptor returned when using the
-Nanomsg verfsion will always return an error.
-
-
&h2(RETURN VALUE)
The &cw(rmr_get_rcvfd) function returns a file descriptor greater or equal to 0 on success
-and -1 on error.
-If this function is called from a user application linked against the Nanomsg RMr library,
-calls will always return -1 with errno set to EINVAL.
+and -1 on error.
&h2(ERRORS)
The following error values are specifically set by this RMR function. In some cases the
rmr_mbuf_t* msg = NULL;
int nready;
int i;
-
+
mrc = rmr_init( "43086", RMR_MAX_RCV_BYTES, RMRFL_NONE );
rcv_fd = rmr_get_rcvfd( mrc );
-
- ep_fd = epoll_create1( 0 ); // initialise epoll environment
+
+ ep_fd = epoll_create1( 0 ); // initialise epoll environment
epe.events = EPOLLIN;
epe.data.fd = rcv_fd;
epoll_ctl( ep_fd, EPOLL_CTL_ADD, rcv_fd, &epe ); // add our info to the mix
-
+
while( 1 ) {
- nready = epoll_wait( ep_fd, events, 10, -1 ); // -1 == block forever (no timeout)
- for( i = 0; i < nready && i < 10; i++ ) { // loop through to find what is ready
- if( events[i].data.fd == rcv_fd ) { // RMr has something
+ nready = epoll_wait( ep_fd, events, 10, -1 ); // -1 == block forever (no timeout)
+ for( i = 0; i < nready && i < 10; i++ ) { // loop through to find what is ready
+ if( events[i].data.fd == rcv_fd ) { // RMR has something
msg = rmr_rcv_msg( mrc, msg );
if( msg ) {
// do something with msg
}
}
-
+
// check for other ready fds....
}
}
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
.fi
.if false
- Mnemonic rmr_get_src.xfm
- Abstract The manual page for the rmr_get_src function.
- Author E. Scott Daniels
- Date 8 March 2019
+ Mnemonic rmr_get_src.xfm
+ Abstract The manual page for the rmr_get_src function.
+ Author E. Scott Daniels
+ Date 8 March 2019
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_get_src
+ rmr_get_src
&h2(SYNOPSIS)
&indent
On failure, a nil pointer is returned and the value of errno is set.
&h2(ERRORS)
-If an error occurs, the value of the global variable &cw( errno ) will be set to one of
+If an error occurs, the value of the global variable &cw(errno) will be set to one of
the following with the indicated meaning.
&beg_dlist(.75i : ^&bold_font )
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
.fi
.if false
- Mnemonic rmr_get_srcip.xfm
- Abstract The manual page for the rmr_get_srcip function.
- Author E. Scott Daniels
- Date 11 June 2019
+ Mnemonic rmr_get_srcip.xfm
+ Abstract The manual page for the rmr_get_srcip function.
+ Author E. Scott Daniels
+ Date 11 June 2019
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_get_srcip
+ rmr_get_srcip
&h2(SYNOPSIS)
&indent
The &cw(rmr_get_srcip) function will copy the &ital(source IP address) from the message to a buffer
(dest) supplied by the user.
In an RMr message, the source IP address is the sender's information that is used for return to sender
-function calls; this function makes it available to the user application.
+function calls; this function makes it available to the user application.
The address is maintained as IP:port where &ital(IP) could be either an IPv6 or IPv4 address depending
on what was provided by the sending application.
.sp
The maximum size allowed by RMr is 64 bytes (including the nil string terminator), so the user
-must ensure that the destination buffer given is at least 64 bytes. The user application should use
+must ensure that the destination buffer given is at least 64 bytes. The user application should use
the RMr constant RMR_MAX_SRC to ensure that the buffer supplied is large enough, and to protect
against future RMr enhancements which might increase the address buffer size requirement.
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
.fi
.if false
- Mnemonic rmr_get_trace.3.xfm
- Abstract The manual page for the rmr_get_trace function.
- Author E. Scott Daniels
- Date 19 April 2019
+ Mnemonic rmr_get_trace.3.xfm
+ Abstract The manual page for the rmr_get_trace function.
+ Author E. Scott Daniels
+ Date 19 April 2019
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_get_trace
+ rmr_get_trace
&h2(SYNOPSIS)
&indent
&h2(DESCRIPTION)
The &cw(rmr_get_trace) function will copy the trace information from the message into the user's
-allocated memory referenced by &cw(dest.)
+allocated memory referenced by &cw(dest.)
The &cw(size) parameter is assumed to be the maximum number of bytes which can be copied (size
of the destination buffer).
&h2(RETURN VALUE)
-On success, the number of bytes actually copied is returned.
+On success, the number of bytes actually copied is returned.
If the return value is 0, no bytes copied, then the reason could be that the message pointer
was nil, or the size parameter was <= 0.
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
==================================================================================
.fi
.if false
- Mnemonic rmr_get_trlen
- Abstract The manual page for the get trace len function.
- Author E. Scott Daniels
- Date 19 April 2019
+ Mnemonic rmr_get_trlen
+ Abstract The manual page for the get trace len function.
+ Author E. Scott Daniels
+ Date 19 April 2019
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_get_trlen
+ rmr_get_trlen
&h2(SYNOPSIS )
&indent
&h2(DESCRIPTION)
Given a message buffer, this function returns the amount of space (bytes)
-that have been allocated for trace data.
+that have been allocated for trace data.
If no trace data has been allocated, then 0 is returned.
&h2(RETURN VALUE)
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
.fi
.if false
- Mnemonic rmr_get_xact.xfm
- Abstract The manual page for the rmr_get_xact function.
- Author E. Scott Daniels
- Date 13 August 2019
+ Mnemonic rmr_get_xact.xfm
+ Abstract The manual page for the rmr_get_xact function.
+ Author E. Scott Daniels
+ Date 13 August 2019
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_get_xact
+ rmr_get_xact
&h2(SYNOPSIS)
&indent
&h2(DESCRIPTION)
The &cw(rmr_get_xact) function will copy the transaction field from the message
-into the &ital(dest) buffer provided by the user.
+into the &ital(dest) buffer provided by the user.
The buffer referenced by &ital(dest) is assumed to be at least &cw(RMR_MAX_XID) bytes in length.
If &ital(dest) is NULL, then a buffer is allocated (the calling application is expected
to free when the buffer is no longer needed).
&h2(RETURN VALUE)
-On success, a pointer to the extracted string is returned.
+On success, a pointer to the extracted string is returned.
If &ital(dest) was supplied, then this is just a pointer to the caller's buffer.
If &ital(dest) was NULL, this is a pointer to the allocated buffer.
If an error occurs, a nil pointer is returned and errno is set as described below.
&h2(ERRORS)
-If an error occurs, the value of the global variable &cw(errno) will be set to one of
+If an error occurs, the value of the global variable &cw(errno) will be set to one of
the following with the indicated meaning.
&beg_dlist(.75i : ^&bold_font )
&di(EINVAL) The message, or an internal portion of the message, was corrupted or the pointer was invalid.
&half_space
-&di(ENOMEM) A nil pointer was passed for &ital(dest,) however it was not possible to allocate a
- buffer using malloc().
+&di(ENOMEM) A nil pointer was passed for &ital(dest,) however it was not possible to allocate a
+ buffer using malloc().
&end_dlist
.if false
==================================================================================
- Copyright (c) 2019-2020 Nokia
- Copyright (c) 2018-2020 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 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.
.fi
.if false
- Mnemonic rmr_init_man.xfm
- Abstract The manual page for the rmr_init function.
- Author E. Scott Daniels
- Date 28 January 2019
+ Mnemonic rmr_init_man.xfm
+ Abstract The manual page for the rmr_init function.
+ Author E. Scott Daniels
+ Date 28 January 2019
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_init
+ rmr_init
&h2(SYNOPSIS)
&indent
&h2(DESCRIPTION)
The &cw(rmr_init) function prepares the environment for sending and receiving messages.
It does so by establishing a worker thread (pthread) which subscribes to a route table
-generator which provides the necessary routing information for the RMR library to
+generator which provides the necessary routing information for the RMR library to
send messages.
&space
&ital(Port) is used to listen for connection requests from other RMR based applications.
The &ital(max_msg_size) parameter is used to allocate receive buffers and is the
-maximum message size which the application expects to receive.
+maximum message size which the application expects to receive.
This value is the sum of &bold(both) the maximum payload size &bold(and) the maximum
-trace data size.
+trace data size.
This value is also used as the default message size when allocating message buffers.
-Messages arriving which are longer than the given maximum will be dropped without
-notification to the application.
+Messages arriving which are longer than the given maximum will be dropped without
+notification to the application.
A warning is written to standard error for the first message which is too large on
each connection.
&space
-&ital(Flags) allows for selection of some RMr options at the time of initialisation.
-These are set by ORing &cw(RMRFL) constants from the RMr header file. Currently the
+&ital(Flags) allows for selection of some RMr options at the time of initialisation.
+These are set by ORing &cw(RMRFL) constants from the RMr header file. Currently the
following flags are supported:
&half_space
&beg_dlist(1i : &bold_font )
-&ditem(RMRFL_NONE)
- No flags are set.
+&ditem(RMRFL_NONE)
+ No flags are set.
&half_space
&ditem(RMRFL_NOTHREAD)
- The route table collector thread is not to be started. This should only be used
- by the route table generator application if it is based on RMr.
+ The route table collector thread is not to be started. This should only be used
+ by the route table generator application if it is based on RMr.
&half_space
&ditem(RMRFL_MTCALL)
- Enable multi-threaded call support.
+ Enable multi-threaded call support.
&half_space
&ditem(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.
+ 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.
&end_dlist
&h3(Multi-threaded Calling)
The support for an application to issue a &ital(blocking call) by the &cw(rmr_call()) function
was limited such that only user applications which were operating in a single thread
could safely use the function.
-Further, timeouts were message count based and not time unit based.
+Further, timeouts were message count based and not time unit based.
Multi-threaded call support adds the ability for a user application with multiple threads
-to invoke a blocking call function with the guarantee that the correct response message
-is delivered to the thread.
+to invoke a blocking call function with the guarantee that the correct response message
+is delivered to the thread.
The additional support is implemented with the &ital(rmr_mt_call()) and &ital(rmr_mt_rcv())
-function calls.
+function calls.
&space
Multi-threaded call support requires the user application to specifically enable it
-when RMr is initialised.
-This is necessary because a second, dedicated, receiver thread must be started, and
+when RMr is initialised.
+This is necessary because a second, dedicated, receiver thread must be started, and
requires all messages to be examined and queued by this thread.
The additional overhead is minimal, queuing information is all in the RMr message
-header, but as an additional process is necessary the user application must "opt in"
+header, but as an additional process is necessary the user application must "opt in"
to this approach.
&space
&h2(ENVIRONMENT)
-As a part of the initialisation process &cw(rmr_init) will look into the available
-environment variables to influence it's setup.
-The following variables will be used when found.
-&half_space
+As a part of the initialisation process &cw(rmr_init) reads
+environment variables to configure itself.
+The following variables are used if found.
+&half_space
.** the list of environment vars supported
.im &{lib}/man/env_var_list.im
&h2(RETURN VALUE)
The &cw(rmr_init) function returns a void pointer (a contex if you will) that is passed
-as the first parameter to nearly all other RMR functions.
+as the first parameter to nearly all other RMR functions.
If &cw(rmr_init) is unable to properly initialise the environment, NULL is returned and
errno is set to an appropriate value.
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
.fi
.if false
- Mnemonic rmr_init_trace_man.xfm
- Abstract The manual page for the rmr_init_trace function.
- Author E. Scott Daniels
- Date 19 April 2019
+ Mnemonic rmr_init_trace_man.xfm
+ Abstract The manual page for the rmr_init_trace function.
+ Author E. Scott Daniels
+ Date 19 April 2019
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_init_trace
+ rmr_init_trace
&h2(SYNOPSIS)
&indent
&uindent
&h2(DESCRIPTION)
-The &cw(rmr_init_trace) function establishes the default trace space placed in each
+The &cw(rmr_init_trace) function establishes the default trace space placed in each
message buffer allocated with &cw(rmr_alloc_msg().)
If this function is never called, then no trace space is allocated by default into
-any message buffer.
+any message buffer.
.sp
Trace space allows the user application to pass some trace token, or other data
with the message, but outside of the payload.
Trace data may be added to any message with &cw(rmr_set_trace(),) and may be extracted
-from a message with &cw(rmr_get_trace().)
+from a message with &cw(rmr_get_trace().)
The number of bytes that a message contains for/with trace data can be determined by
-invoking &cw(rmr_get_trlen().)
+invoking &cw(rmr_get_trlen().)
.sp
This function may be safely called at any time during the life of the user programme
-to (re)set the default trace space reserved.
+to (re)set the default trace space reserved.
If the user programme needs to allocate a message with trace space of a different
-size than is allocated by default, without fear of extra overhead of reallocating
+size than is allocated by default, without fear of extra overhead of reallocating
a message later, the &cw(rmr_tralloc_msg()) function can be used.
&h2(RETURN VALUE)
-A value of 1 is returned on success, and 0 on failure. A failure indicates that the
+A value of 1 is returned on success, and 0 on failure. A failure indicates that the
RMr context (a void pointer passed to this function was not valid.
&h2(SEE ALSO )
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
.if false
- Mnemonic rmr_mt_call_man.xfm
- Abstract The manual page for the rmr multi-threaded call function.
- Author E. Scott Daniels
- Date 24 May 2019
+ Mnemonic rmr_mt_call_man.xfm
+ Abstract The manual page for the rmr multi-threaded call function.
+ Author E. Scott Daniels
+ Date 24 May 2019
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_mt_call
+ rmr_mt_call
&h2(SYNOPSIS )
&indent
a &cw(rmr_send_msg) call, but unlike with a send, the buffer returned will have
the response from the application that received the message.
The thread invoking the &ital(rmr_mt_call()) will block until a message arrives
-or until &ital(timeout) milliseconds has passed; which ever comes first.
+or until &ital(timeout) milliseconds has passed; which ever comes first.
Using a timeout value of zero (0) will cause the thread to block without a timeout.
&space
The &ital(id) supplied as the third parameter is an integer in the range of 2 through
-255 inclusive.
+255 inclusive.
This is a caller defined "thread number" and is used to match the response message
with the correct user application thread.
If the ID value is not in the proper range, the attempt to make the call will fail.
&space
Messages which are received while waiting for the response are queued on a &ital(normal)
-receive queue and will be delivered to the user application with the next invocation
-of &ital(rmr_mt_rcv()) or &ital(rmr_rvv_msg().)
-by RMR, and are returned to the user application when &cw(rmr_rcv_msg) is
+receive queue and will be delivered to the user application with the next invocation
+of &ital(rmr_mt_rcv()) or &ital(rmr_rvv_msg().)
+by RMR, and are returned to the user application when &cw(rmr_rcv_msg) is
invoked.
-These messages are returned in th order received, one per call to &cw(rmr_rcv_msg.)
-
-&space
-NOTE: Currently the multi-threaded functions are supported only when the NNG
-transport mechanism is being used. It will not be possible to link a programme
-using the Nanomsg version of the library when references to this function are
-present.
+These messages are returned in the order received, one per call to &cw(rmr_rcv_msg.)
&h3(The Transaction ID)
The user application is responsible for setting the value of the transaction ID field
-before invoking &ital(rmr_mt_call.)
-The transaction ID is a &cw(RMR_MAX_XID) byte field that is used to match the
-response message when it arrives.
-RMr will compare &bold(all) of the bytes in the field, so the caller must ensure
-that they are set correctly to avoid missing the response message.
-(The application which returns the response message is also expected to ensure that
+before invoking &ital(rmr_mt_call.)
+The transaction ID is a &cw(RMR_MAX_XID) byte field that is used to match the
+response message when it arrives.
+RMR will compare &bold(all) of the bytes in the field, so the caller must ensure
+that they are set correctly to avoid missing the response message.
+The application which returns the response message is also expected to ensure that
the return buffer has the matching transaction ID. This can be done transparently if
-the application uses the &ital(rmr_rts_msg()) function and does not adjust the
+the application uses the &ital(rmr_rts_msg()) function and does not adjust the
transaction ID.
.** pull in common retry text
-.im &{lib}/man/retry.im
+.im &{lib}/man/retry.im
&h2(RETURN VALUE)
The &cw(rmr_mt_call) function returns a pointer to a message buffer with the state set to reflect
&space
If no response message is received when the timeout period has expired, a nil pointer
-will be returned (NULL).
+will be returned (NULL).
&h2(ERRORS)
-These values are reflected in the state field of the returned message.
+These values are reflected in the state field of the returned message.
&half_space
&beg_dlist(.75i : ^&bold_font )
&di(RMR_ERR_BADARG) An argument passed to the function was invalid.
&half_space
-&di(RMR_ERR_CALLFAILED) The call failed and the value of &ital(errno,) as described below,
- should be checked for the specific reason.
+&di(RMR_ERR_CALLFAILED) The call failed and the value of &ital(errno,) as described below,
+ should be checked for the specific reason.
&half_space
&di(RMR_ERR_NOENDPT) An endpoint associated with the message type could not be found in the
- route table.
+ route table.
&half_space
&di(RMR_ERR_RETRY) The underlying transport mechanism was unable to accept the message
- for sending. The user application can retry the call operation if appropriate to
- do so.
+ for sending. The user application can retry the call operation if appropriate to
+ do so.
&end_dlist
&space
-The global "variable" &ital(errno) will be set to one of the following values if the
-overall call processing was not successful.
+The global "variable" &ital(errno) will be set to one of the following values if the
+overall call processing was not successful.
&half_space
&beg_dlist(.75i : ^&bold_font )
&half_space
&di(EAGAIN) The underlying message system wsa interrupted or the device was busy;
- the message was &bold(not) sent, and user application should call
- this function with the message again.
+ the message was &bold(not) sent, and user application should call
+ this function with the message again.
&end_dlist
&h2(EXAMPLE)
static rmr_mbuf_t* mbuf = NULL; // response msg
msg_t* pm; // private message (payload)
- // get a send buffer and reference the payload
+ // get a send buffer and reference the payload
mbuf = rmr_alloc_msg( mr, RMR_MAX_RCV_BYTES );
pm = (msg_t*) mbuf->payload;
- // generate an xaction ID and fill in payload with data and msg type
+ // generate an xaction ID and fill in payload with data and msg type
rmr_bytes2xact( mbuf, xid, RMR_MAX_XID );
snprintf( pm->req, sizeof( pm->req ), "{ \"req\": \"num users\"}" );
mbuf->mtype = MT_USR_RESP;
-
- msg = rmr_mt_call( mr, msg, my_id, 100 ); // wait up to 100ms
+
+ msg = rmr_mt_call( mr, msg, my_id, 100 ); // wait up to 100ms
if( ! msg ) { // probably a timeout and no msg received
return NULL; // let errno trickle up
- }
+ }
if( mbuf->state != RMR_OK ) {
while( retries_left-- > 0 && // loop as long as eagain
- mbuf->state == RMR_ERR_RETRY &&
- (msg = rmr_mt_call( mr, msg )) != NULL &&
+ mbuf->state == RMR_ERR_RETRY &&
+ (msg = rmr_mt_call( mr, msg )) != NULL &&
mbuf->state != RMR_OK ) {
usleep( retry_delay );
}
-
+
if( mbuf == NULL || mbuf->state != RMR_OK ) {
rmr_free_msg( mbuf ); // safe if nil
return NULL;
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
==================================================================================
.fi
.if false
- Mnemonic rmr_mt_rcv_man.xfm
- Abstract The manual page for the rmr_mt_rcv function.
- Author E. Scott Daniels
- Date 24 May 2019
+ Mnemonic rmr_mt_rcv_man.xfm
+ Abstract The manual page for the rmr_mt_rcv function.
+ Author E. Scott Daniels
+ Date 24 May 2019
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_mt_rcv
+ rmr_mt_rcv
&h2(SYNOPSIS )
&indent
&h2(DESCRIPTION)
The &cw(rmr_mt_rcv) function blocks until a message is received, or the timeout
-period (milliseconds) has passed.
-The result is an RMr message buffer which references a received message.
+period (milliseconds) has passed.
+The result is an RMr message buffer which references a received message.
In the case of a timeout the state will be reflected in an "empty buffer" (if old_msg
was not nil, or simply with the return of a nil pointer.
If a timeout value of zero (0) is given, then the function will block until
&space
The &ital(vctx) pointer is the pointer returned by the &cw(rmr_init) function.
-&ital(Old_msg) is a pointer to a previously used message buffer or NULL.
+&ital(Old_msg) is a pointer to a previously used message buffer or NULL.
The ability to reuse message buffers helps to avoid alloc/free cycles in the
-user application.
+user application.
When no buffer is available to supply, the receive function will allocate one.
&space
-The &ital(old_msg) parameter allows the user to pass a previously generated RMr
-message back to RMr for reuse.
+The &ital(old_msg) parameter allows the user to pass a previously generated RMR
+message back to RMR for reuse.
Optionally, the user application may pass a nil pointer if no reusable message
-is available.
-When a timeout occurs, and old_msg was not nil, the state will be returned
-by returning a pointer to the old message with the state set.
+is available.
+When a timeout occurs, and old_msg was not nil, the state will be returned
+by returning a pointer to the old message with the state set.
&space
-It is possible to use the &ital(rmr_rcv_msg()) function instead of this function.
-Doing so might be advantagous if the user programme does not always start the
+It is possible to use the &ital(rmr_rcv_msg()) function instead of this function.
+Doing so might be advantageous if the user programme does not always start the
multi-threaded mode and the use of &ital(rmr_rcv_msg()) would make the flow of
-the code more simple.
-The advantags of using this function are the ability to set a timeout without
+the code more simple.
+The advantages of using this function are the ability to set a timeout without
using epoll, and a small performance gain (if multi-threaded mode is enabled, and the
&ital(rmr_rcv_msg()) function is used, it simply invokes this function without
a timeout value, thus there is the small cost of a second call that results).
Similarly, the &ital(rmr_torcv_msg()) call can be used when in multi-threaded
mode with the same "pass through" overhead to using this function directly.
-&space
-NOTE: Currently the multi-threaded functions are supported only when the NNG
-transport mechanism is being used. It will not be possible to link a programme
-using the nanomsg version of the library when references to this function are
-present.
-
&h2(RETURN VALUE)
-When a message is received before the timeout period expires, a pointer to the
-RMr message buffer which describes the message is returned.
+When a message is received before the timeout period expires, a pointer to the
+RMr message buffer which describes the message is returned.
This will, with a high probability, be a different message buffer than &ital(old_msg;)
the user application should not continue to use &ital(old_msg) after it is passed
-to this function.
+to this function.
&space
-In the event of a timeout the return value will be the old msg with the state set,
+In the event of a timeout the return value will be the old msg with the state set,
or a nil pointer if no old message was provided.
&h2(ERRORS)
The &ital(state) field in the message buffer will be set to one of the following
-values:
+values:
&space
&beg_dlist(.75i : ^&bold_font )
&di(RMR_ERR_BADARG) A parameter passed to the function was not valid (e.g. a nil pointer).
indicate either &cw(RMR_OK) or
-&cw(RMR_ERR_EMPTY) if an empty message was received.
+&cw(RMR_ERR_EMPTY) if an empty message was received.
&half_space
-&di(RMR_ERR_EMPTY) The message received had no associated data. The length of the
- message will be 0.
+&di(RMR_ERR_EMPTY) The message received had no associated data. The length of the
+ message will be 0.
&half_space
-&di(RMR_ERR_NOTSUPP) The multi-threaded option was not enabled when RMr was
+&di(RMR_ERR_NOTSUPP) The multi-threaded option was not enabled when RMr was
initialised. See the man page for &ital(rmr_init()) for details.
&half_space
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
==================================================================================
.fi
.if false
- Mnemonic rmr_payload_size_man.xfm
- Abstract The manual page for the rmr_payload_size function.
- Author E. Scott Daniels
- Date 29 January 2019
+ Mnemonic rmr_payload_size_man.xfm
+ Abstract The manual page for the rmr_payload_size function.
+ Author E. Scott Daniels
+ Date 29 January 2019
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_payload_size
+ rmr_payload_size
&h2(SYNOPSIS )
&indent
&h2(DESCRIPTION)
Given a message buffer, this function returns the amount of space (bytes)
available for the user application to consume in the message payload.
-This is different than the message length available as a field in the
+This is different than the message length available as a field in the
message buffer.
&h2(RETURN VALUE)
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
==================================================================================
.fi
.if false
- Mnemonic rmr_rcv_msg_man.xfm
- Abstract The manual page for the rmr_rcv_msg function.
- Author E. Scott Daniels
- Date 29 January 2019
+ Mnemonic rmr_rcv_msg_man.xfm
+ Abstract The manual page for the rmr_rcv_msg function.
+ Author E. Scott Daniels
+ Date 29 January 2019
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_rcv_msg
+ rmr_rcv_msg
&h2(SYNOPSIS )
&indent
&h2(DESCRIPTION)
The &cw(rmr_rcv_msg) function blocks until a message is received, returning
the message to the caller via a pointer to a &cw(rmr_mbuf_t) structure type.
-If messages were queued while waiting for the response to a previous invocation
-of &cw(rmr_call,) the oldest message is removed from the queue and returned
+If messages were queued while waiting for the response to a previous invocation
+of &cw(rmr_call,) the oldest message is removed from the queue and returned
without delay.
&space
The &ital(vctx) pointer is the pointer returned by the &cw(rmr_init) function.
-&ital(Old_msg) is a pointer to a previously used message buffer or NULL.
+&ital(Old_msg) is a pointer to a previously used message buffer or NULL.
The ability to reuse message buffers helps to avoid alloc/free cycles in the
-user application.
+user application.
When no buffer is available to supply, the receive function will allocate one.
&h2(RETURN VALUE)
The function returns a pointer to the &cw(rmr_mbuf_t) structure which references
-the message information (state, length, payload), or a NULL pointer in the case
+the message information (state, length, payload), or a nil pointer in the case
of an extreme error.
&h2(ERRORS)
-The &ital(state) field in the message buffer will indicate either &cw(RMR_OK)
+The &ital(state) field in the message buffer will indicate &cw(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
+Depending on the underlying transport mechanism, one of the following RMR
error stats may be returned:
&half_space
&half_space
&di(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
+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.
&end_dlist
might accompany the states listed above:
&half_space
-&cw(RMR_ERR_EMPTY) if an empty message was received.
+&cw(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, &cw(errno) will be set to one of the following:
&space
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
==================================================================================
.fi
.if false
- Mnemonic rmr_ready_man.xfm
- Abstract The manual page for the rmr_ready function.
- Author E. Scott Daniels
- Date 28 January 2019
+ Mnemonic rmr_ready_man.xfm
+ Abstract The manual page for the rmr_ready function.
+ Author E. Scott Daniels
+ Date 28 January 2019
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_ready
+ rmr_ready
&h2(SYNOPSIS )
&indent
&h2(RETURN VALUE)
A return value of 1 (true) indicates that the routing table is in place and
-attempts to send messages can be made.
+attempts to send messages can be made.
When 0 is returned (false) the routing table has not been received and thus
attempts to send messages will fail with &ital(no endpoint) errors.
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
.if false
- Mnemonic rmr_realloc_payload.3.xfm
- Abstract The manual page for the rmr_realloc_payload function.
- Author E. Scott Daniels
- Date 30 October 2019
+ Mnemonic rmr_realloc_payload.3.xfm
+ Abstract The manual page for the rmr_realloc_payload function.
+ Author E. Scott Daniels
+ Date 30 October 2019
.fi
.gv e LIB lib
&h1(RMR Library Functions)
&h2(NAME)
- rmr_realloc_payload
+ rmr_realloc_payload
&h2(SYNOPSIS )
&indent
The &cw(rmr_realloc_payload) function returns a pointer to the message buffer with the
payload which is large enough to hold &ital(new_len) bytes.
If the &ital(clone) option is true, this will be a pointer to the newly cloned
-message buffer; the original message buffer pointer may still be used to referenced
+message buffer; the original message buffer pointer may still be used to reference
that message.
It is the calling application's responsibility to free the memory associateed with
both messages using the rmr_free_msg() function.
&half_space
&di(EINVAL) The pointer passed in was nil, or refrenced an invalid message, or the required
- length was not valid.
+ length was not valid.
&end_dlist
if( msg == NULL ) {
fprintf( stderr, "[ERR] realloc returned a nil pointer: %s\n", strerror( errno ) );
} else {
- // populate and send ack message
- }
+ // populate and send ack message
+ }
}
&ex_end
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
==================================================================================
.fi
.if false
- Mnemonic rmr_rts_msg_man.xfm
- Abstract The manual page for the rmr_rts_msg function.
- Author E. Scott Daniels
- Date 28 January 2019
+ Mnemonic rmr_rts_msg_man.xfm
+ Abstract The manual page for the rmr_rts_msg function.
+ Author E. Scott Daniels
+ Date 28 January 2019
.fi
.gv e LIB lib
&h1(RMR Library Functions)
&h2(NAME)
- rmr_rts_msg
+ rmr_rts_msg
&h2(SYNOPSIS )
&indent
has.
In the case of a received message, it is possible that the response needs to be
larger than the payload associated with the inbound message.
-In order to use the return to sender function, the source infomration in the orignal
+In order to use the return to sender function, the source information in the original
message must be present in the response; information which cannot be added to a
message buffer allocated through the standard RMR allocation function.
To allocate a buffer with a larger payload, and which retains the necessary sender
&cw(RMR_OK.)
&space
-If the state in the returned buffer is anything other than &cw(UT_OK,) the user application
+If the state in the returned buffer is anything other than &cw(RMR_OK,) the user application
may need to attempt a retransmission of the message, or take other action depending on the
setting of &cw(errno) as described below.
&space
-In the event of extreme failure, a NULL pointer is returned. In this case the value of
+In the event of extreme failure, a nil pointer is returned. In this case the value of
&cw(errno) might be of some use, for documentation, but there will be little that the
user application can do other than to move on.
&di(EMSGSIZE) The underlying transport refused to accept the message because of a size value issue (message was not attempted to be sent).
&half_space
-&di(EFAULT) The message referenced by the message buffer is corrupt (NULL pointer or bad internal length).
+&di(EFAULT) The message referenced by the message buffer is corrupt (nil pointer or bad internal length).
&half_space
&di(EBADF) Internal RMR error; information provided to the message transport environment was not valid.
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
==================================================================================
.fi
.if false
- Mnemonic rmr_send_msg_man.xfm
- Abstract The manual page for the rmr_send_msg function.
- Author E. Scott Daniels
- Date 28 January 2019
+ Mnemonic rmr_send_msg_man.xfm
+ Abstract The manual page for the rmr_send_msg function.
+ Author E. Scott Daniels
+ Date 28 January 2019
.fi
.gv e LIB lib
&h1(RMR Library Functions)
&h2(NAME)
- rmr_send_msg
+ rmr_send_msg
&h2(SYNOPSIS )
&indent
is known.
&space
-In the event of extreme failure, a NULL pointer is returned. In this case the value of
+In the event of extreme failure, a nil pointer is returned. In this case the value of
&cw(errno) might be of some use, for documentation, but there will be little that the
user application can do other than to move on.
&space
&beg_dlist(.75i : ^&bold_font )
-&di(RMR_RETRY) The message could not be sent, but the underlying transport mechanism
- indicates that the failure is temporary. If the send operation is tried again
- it might be successful.
+&di(RMR_RETRY) The message could not be sent, but the underlying transport mechanism
+ indicates that the failure is temporary. If the send operation is tried again
+ it might be successful.
&di(RMR_SEND_FAILED) The send operation was not successful and the underlying transport
- mechanism indicates a permanent (hard) failure; retrying the send is not possible.
+ mechanism indicates a permanent (hard) failure; retrying the send is not possible.
&di(RMR_ERR_BADARG) The message buffer pointer did not refer to a valid message.
&di(RMR_ERR_NOHDR) The header in the message buffer was not valid or corrupted.
&di(RMR_ERR_NOENDPT) The message type in the message buffer did not map to a known endpoint.
&di(EMSGSIZE) The underlying transport refused to accept the message because of a size value issue (message was not attempted to be sent).
&half_space
-&di(EFAULT) The message referenced by the message buffer is corrupt (NULL pointer or bad internal length).
+&di(EFAULT) The message referenced by the message buffer is corrupt (nil pointer or bad internal length).
&half_space
&di(EBADF) Internal RMR error; information provided to the message transport environment was not valid.
msg_t* send_pm; // payload for send
msg_t* pm; // our message format in the received payload
- if( send_msg == NULL ) {
- send_msg = rmr_alloc_msg( mr, MAX_SIZE ); // new buffer to send
- }
+ if( send_msg == NULL ) {
+ send_msg = rmr_alloc_msg( mr, MAX_SIZE ); // new buffer to send
+ }
- // reference payload and fill in message type
+ // reference payload and fill in message type
pm = (msg_t*) send_msg->payload;
send_msg->mtype = MT_ANSWER;
msg->len = generate_data( pm ); // something that fills the payload in
msg = rmr_send_msg( mr, send_msg ); // ensure new pointer used after send
- if( ! msg ) {
- return ERROR;
- } else {
- if( msg->state != RMR_OK ) {
- // check for RMR_ERR_RETRY, and resend if needed
- // else return error
- }
- }
-
- return OK;
+ if( ! msg ) {
+ return ERROR;
+ } else {
+ if( msg->state != RMR_OK ) {
+ // check for RMR_ERR_RETRY, and resend if needed
+ // else return error
+ }
+ }
+ return OK;
&ex_end
.if false
==================================================================================
- Copyright (c) 2019-2020 Nokia
- Copyright (c) 2018-2020 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 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.
==================================================================================
.fi
.if false
- Mnemonic rmr_set_fack.3.xfm
- Abstract The manual page for the set fast ack function.
- Author E. Scott Daniels
- Date 19 Fabruary 2020
+ Mnemonic rmr_set_fack.3.xfm
+ Abstract The manual page for the set fast ack function.
+ Author E. Scott Daniels
+ Date 19 Fabruary 2020
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_set_fack
+ rmr_set_fack
&h2(SYNOPSIS )
&indent
&h2(DESCRIPTION)
The &cw(rmr_set_fack) function enables &ital(fast TCP acknowledgements) if
-the underlying transport library supports it.
-This might be useful for applications which must send messages as a maximum
-rate.
+the underlying transport library supports it.
+This might be useful for applications which must send messages at a maximum
+rate.
&h2(RETURN VALUE)
There is no return value.
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
==================================================================================
.fi
.if false
- Mnemonic rmr_set_stimeout.xfm
- Abstract The manual page for the rmr_set_stimeout function.
- Author E. Scott Daniels
- Date 28 January 2019
+ Mnemonic rmr_set_stimeout.xfm
+ Abstract The manual page for the rmr_set_stimeout function.
+ Author E. Scott Daniels
+ Date 28 January 2019
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&ex_start
#define NO_FLAGS 0
- char* port = "43086"; // port for message router listen
- int max_size = 4096; // max message size for default allocations
- void* mr_context; // message router context
+ char* port = "43086"; // port for message router listen
+ int max_size = 4096; // max message size for default allocations
+ void* mr_context; // message router context
mr_context = rmr_init( port, max_size, NO_FLAGS );
if( mr_context != NULL ) {
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
.fi
.if false
- Mnemonic rmr_set_trace.xfm
- Abstract The manual page for the rmr_set_trace function.
- Author E. Scott Daniels
- Date 19 April 2019
+ Mnemonic rmr_set_trace.xfm
+ Abstract The manual page for the rmr_set_trace function.
+ Author E. Scott Daniels
+ Date 19 April 2019
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_set_trace
+ rmr_set_trace
&h2(SYNOPSIS)
&indent
&uindent
&h2(DESCRIPTION)
-The &cw(rmr_set_trace) function will copy &cw(len) bytes from &cw(data) into the trace portion of
-&cw(mbuf.)
+The &cw(rmr_set_trace) function will copy &cw(len) bytes from &cw(data) into the trace portion of
+&cw(mbuf.)
If the trace area of &cw(mbuf) is not the correct size, the message buffer will be reallocated
to ensure that enough space is available for the trace data.
.if false
==================================================================================
- Copyright (c) 2019-2020 Nokia
- Copyright (c) 2018-2020 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 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.
.fi
.if false
- Mnemonic rmr_set_vlevel.3.xfm
- Abstract The manual page for the function which sets the verbosity level
- in RMR logging.
- Author E. Scott Daniels
- Date 28 January 2020
+ Mnemonic rmr_set_vlevel.3.xfm
+ Abstract The manual page for the function which sets the verbosity level in RMR logging.
+ Author E. Scott Daniels
+ Date 28 January 2020
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_set_trace
+ rmr_set_vlevel
&h2(SYNOPSIS)
&indent
&uindent
&h2(DESCRIPTION)
-The &cw(rmr_set_vlevel) allows the user programme to set the verbosity level
+The &cw(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 &cw(new_vlevel) value must be one of the following constants which have the
+The &cw(new_vlevel) value must be one of the following constants which have the
indicated meanings:
&beg_dlist(1i : &bold_font )
-&ditem(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).
+&ditem(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).
&half_space
-&ditem(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.
-
-&ditem(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.
-
-&ditem(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.
-
-&ditem(RMR_VL_INFO)
- Include informational messagees in the output.
- Informational messages include some diagnostic information which explain the activities
- of RMR.
-
-&ditem(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.
+&ditem(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.
+
+&ditem(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.
+
+&ditem(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.
+
+&ditem(RMR_VL_INFO)
+ Include informational messagees in the output.
+ Informational messages include some diagnostic information which explain the activities
+ of RMR.
+
+&ditem(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.
&end_dlist
&space
-generally RMR does not write messages to the standard error device from &ital(critical path)
-functions, therefore it is usually not harmful to enable a verbosity level of either RMR_VL_CRIT, or RMR_VL_ERR.
+Generally RMR does not write messages to the standard error device from &ital(critical path)
+functions, therefore it is usually not harmful to enable a verbosity level of either RMR_VL_CRIT or RMR_VL_ERR.
&space
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.
+only when logging is completely disabled by passing RMR_VL_OFF to this function.
&space
-The verbosity level can also be set via an environment variable prior to the start of the
+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.
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
.fi
.if false
- Mnemonic rmr_str2meid.xfm
- Abstract The manual page for the rmr_str2meid function.
- Author E. Scott Daniels
- Date 8 March 2019
+ Mnemonic rmr_str2meid.xfm
+ Abstract The manual page for the rmr_str2meid function.
+ Author E. Scott Daniels
+ Date 8 March 2019
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_str2meid
+ rmr_str2meid
&h2(SYNOPSIS)
&indent
&uindent
&h2(DESCRIPTION)
-The &cw(rmr_str2meid) function will copy the string pointed to by src to the
-managed entity ID (meid) field in the given message.
+The &cw(rmr_str2meid) function will copy the string pointed to by src to the
+managed entity ID (meid) field in the given message.
The field is a fixed length, gated by the constant &cw(RMR_MAX_MEID) and if string length is larger
than this value, then &bold(nothing) will be copied. (Note, this differs slightly from the
behaviour of the &cw(lrmr_bytes2meid()) function.)
&h2(RETURN VALUE)
-On success, the value RMR_OK is returned.
-If the string cannot be copied to the message, the return value will be one of the
+On success, the value RMR_OK is returned.
+If the string cannot be copied to the message, the return value will be one of the
errors listed below.
&h2(ERRORS)
&half_space
&di(RMR_ERR_OVERFLOW) The length passed in was larger than the maximum length of the field; only a portion of
- the source bytes were copied.
+ the source bytes were copied.
&end_dlist
&h2(EXAMPLE)
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
.fi
.if false
- Mnemonic rmr_str2xact.xfm
- Abstract The manual page for the rmr_str2xact function.
- Author E. Scott Daniels
- Date 8 March 2019
+ Mnemonic rmr_str2xact.xfm
+ Abstract The manual page for the rmr_str2xact function.
+ Author E. Scott Daniels
+ Date 8 March 2019
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_str2xact
+ rmr_str2xact
&h2(SYNOPSIS)
&indent
&uindent
&h2(DESCRIPTION)
-The &cw(rmr_str2xact) function will copy the string pointed to by src to the
-transaction ID (xaction) field in the given message.
+The &cw(rmr_str2xact) function will copy the string pointed to by src to the
+transaction ID (xaction) field in the given message.
The field is a fixed length, gated by the constant &cw(RMR_MAX_XID) and if string length is larger
than this value, then &bold(nothing) will be copied. (Note, this differs slightly from the
behaviour of the &cw(lrmr_bytes2xact()) function.)
&beg_dlist(.75i : ^&bold_font )
&h2(RETURN VALUE)
-On success, the value RMR_OK is returned.
-If the string cannot be copied to the message, the return value will be one of the
+On success, the value RMR_OK is returned.
+If the string cannot be copied to the message, the return value will be one of the
errors listed below.
&h2(ERRORS)
&half_space
&di(RMR_ERR_OVERFLOW) The length passed in was larger than the maximum length of the field; only a portion of
- the source bytes were copied.
+ the source bytes were copied.
&end_dlist
&h2(EXAMPLE)
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
==================================================================================
.fi
.if false
- Mnemonic rmr_support_man.xfm
- Abstract The manual page for the rmr_ functions that support the library
- and are available to support other applications such as the route
- table generator, but are not directly related to message sending
- and receiving. These "second class" functions therefore are
- likely not to need a dedicated man page, so we lump them all
- here.
- Author E. Scott Daniels
- Date 28 January 2019
+ Mnemonic rmr_support_man.xfm
+ Abstract The manual page for the rmr_ functions that support the library
+ and are available to support other applications such as the route
+ table generator, but are not directly related to message sending
+ and receiving. These "second class" functions therefore are
+ likely not to need a dedicated man page, so we lump them all
+ here.
+ Author E. Scott Daniels
+ Date 28 January 2019
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- RMR support functions
+ RMR support functions
&h2(SYNOPSIS )
&indent
The &cw(rmr_fib) function accepts a file name and reads the entire file into a single buffer.
-The intent is to provide an easy way to load a static route table without a lot of
+The intent is to provide an easy way to load a static route table without a lot of
buffered I/O hoops.
&space
&space
The &cw(rmr_tokenise) function is a simple tokeniser which splits &ital(buf) into tokens
-at each occurrence of &ital(sep).
+at each occurrence of &ital(sep).
Multiple occurrences of the separator character (e.g. a,,b) result in a nil token.
Pointers to the tokens are placed into the &ital(tokens) array provided by the caller which
is assumed to have at least enough space for &ital(max) entries.
&space
The &cw(rmr_ring_insert) and &cw(rmr_ring_extract) functions are provided as static inline functions
via the &ital(rmr/ring_inline.h) header file.
-These functions both accept the ring &ital(context) returned by &cw(mk_ring,) and either insert a
+These functions both accept the ring &ital(context) returned by &cw(mk_ring,) and either insert a
pointer at the next available slot (tail) or extract the data at the head.
&h2(RETURN VALUES)
The following are the return values for each of these functions.
&space
-The &cw(rmr_fib) function returns a pointer to the buffer containing the contents of the
-file.
+The &cw(rmr_fib) function returns a pointer to the buffer containing the contents of the
+file.
The buffer is terminated with a single nil character (0) making it a legitimate C string.
-If the file was empty or nonexistent, a buffer with an immediate nil character.
-If it is important to the calling programme to know if the file was empty or did not exist,
+If the file was empty or nonexistent, a buffer with an immediate nil character.
+If it is important to the calling programme to know if the file was empty or did not exist,
the caller should use the system stat function call to make that determination.
&space
0 if the ring is full and the pointer could not be deposited.
&space
-The &cw(rmr_ring_extract) will return the data which is at the head of the ring, or NULL if the
+The &cw(rmr_ring_extract) will return the data which is at the head of the ring, or NULL if the
ring is empty.
&h2(ERRORS)
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
==================================================================================
.fi
.if false
- Mnemonic rmr_torcv_msg_man.xfm
- Abstract The manual page for the rmr_torcv_msg function.
- Author E. Scott Daniels
- Date 29 January 2019
+ Mnemonic rmr_torcv_msg_man.xfm
+ Abstract The manual page for the rmr_torcv_msg function.
+ Author E. Scott Daniels
+ Date 29 January 2019
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_torcv_msg
+ rmr_torcv_msg
&h2(SYNOPSIS )
&indent
&h2(DESCRIPTION)
The &cw(rmr_torcv_msg) function will pause for &ital(ms_to) milliseconds waiting
-for a message to arrive.
+for a message to arrive.
If a message arrives before the timeout expires the message buffer returned
will have a status of RMR_OK and the payload will contain the data received.
-If the timeout expires before the message is received, the status will
+If the timeout expires before the message is received, the status will
have the value RMR_ERR_TIMEOUT.
When a received message is returned the message buffer will also contain the
message type and length set by the sender.
-If messages were queued while waiting for the response to a previous invocation
-of &cw(rmr_call,) the oldest message is removed from the queue and returned
+If messages were queued while waiting for the response to a previous invocation
+of &cw(rmr_call,) the oldest message is removed from the queue and returned
without delay.
&space
The &ital(vctx) pointer is the pointer returned by the &cw(rmr_init) function.
-&ital(Old_msg) is a pointer to a previously used message buffer or NULL.
+&ital(Old_msg) is a pointer to a previously used message buffer or NULL.
The ability to reuse message buffers helps to avoid alloc/free cycles in the
-user application.
+user application.
When no buffer is available to supply, the receive function will allocate one.
&h2(RETURN VALUE)
The function returns a pointer to the &cw(rmr_mbuf_t) structure which references
-the message information (state, length, payload), or a NULL pointer in the case
+the message information (state, length, payload), or a nil pointer in the case
of an extreme error.
&h2(ERRORS)
&space
&di(RMR_ERR_INITFAILED) The first call to this function must initialise an underlying
- system notification mechanism. On failure, this error is returned and errno
- will have the system error status set. If this function fails to intialise,
- the poll mechansim, it is likely that message receives will never be successful.
+ system notification mechanism. On failure, this error is returned and errno
+ will have the system error status set. If this function fails to intialise,
+ the poll mechansim, it is likely that message receives will never be successful.
&space
&di(RMR_ERR_TIMEOUT) The timeout expired before a complete message was received.
- All other fields in the message buffer are not valid.
+ All other fields in the message buffer are not valid.
&space
-&di(RMR_ERR_EMPTY) A message was received, but it had no payload. All other
- fields in the message buffer are not valid.
+&di(RMR_ERR_EMPTY) A message was received, but it had no payload. All other
+ fields in the message buffer are not valid.
&end_dlist
&space
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
.fi
.if false
- Mnemonic rmr_trace_ref.3.xfm
- Abstract The manual page for the rmr_trace_ref function.
- Author E. Scott Daniels
- Date 11 July 2019
+ Mnemonic rmr_trace_ref.3.xfm
+ Abstract The manual page for the rmr_trace_ref function.
+ Author E. Scott Daniels
+ Date 11 July 2019
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_trace_ref
+ rmr_trace_ref
&h2(SYNOPSIS)
&indent
&uindent
&h2(DESCRIPTION)
-The &cw(rmr_trace_ref) function return a pointer to the trace area in the message, and optionally
-populate the user programme supplied size integer with the trace area size, if &ital(sizeptr) is
+The &cw(rmr_trace_ref) function returns a pointer to the trace area in the message, and optionally
+populates the user programme supplied size integer with the trace area size, if &ital(sizeptr) is
not nil.
&h2(RETURN VALUE)
-On success, a void pointer to the trace area of the message is returned.
+On success, a void pointer to the trace area of the message is returned.
A nil pointer is returned if the message has no trace data area allocated, or if the message
itself is invalid.
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
==================================================================================
.fi
.if false
- Mnemonic rmr_tralloc_msg.xfm
- Abstract The manual page for the rmr_tralloc_msg function.
- Author E. Scott Daniels
- Date 19 April 2019
+ Mnemonic rmr_tralloc_msg.xfm
+ Abstract The manual page for the rmr_tralloc_msg function.
+ Author E. Scott Daniels
+ Date 19 April 2019
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_tralloc_msg
+ rmr_tralloc_msg
&h2(SYNOPSIS )
&indent
&ex_start
#include <rmr/rmr.h>
-rmr_mbuf_t* rmr_tralloc_msg( void* vctx, int size,
+rmr_mbuf_t* rmr_tralloc_msg( void* vctx, int size,
int trace_size, unsigned const char *tr_data );
&ex_end
&uindent
&h2(DESCRIPTION)
-The &cw(rmr_alloc_msg) function is used to allocate a buffer which the user
-programme can write into and then send through the a library.
+The &cw(rmr_tralloc_msg) function is used to allocate a buffer which the user
+programme can write into and then send through the library.
The buffer is allocated such that sending it requires no additional copying
-from the buffer as it passes through the underlying transport mechanism.
+from the buffer as it passes through the underlying transport mechanism.
.sp
-The &ital(size) parameter is used to set the payload length in the message and
-If it is 0, then the default size supplied on the &ital(rmr_init) call will be used.
-In addition to allocating the payload, a space in the buffer is
+The &ital(size) parameter is used to set the payload length in the message.
+If it is 0, then the default size supplied on the &ital(rmr_init) call will be used.
+In addition to allocating the payload, a space in the buffer is
reserved for &ital(trace) data (tr_size bytes), and the bytes pointed to
by &ital(tr_data) are copied into that portion of the message.
&space
-The pointer to the message buffer returned is a structure which has some
+The pointer to the message buffer returned is a structure which has some
user application visible fields; the structure is described in &cw(rmr.h,)
and is illustrated below.
&space
&beg_dlist(.75i : ^&bold_font )
-&diitem(state ) Is the current buffer state. Following a call to &cw(rmr_send_msg)
+&diitem(state ) Is the current buffer state. Following a call to &cw(rmr_send_msg)
the state indicates whether the buffer was successfully sent which determines
exactly what the payload points to. If the send failed, the payload referenced
-by the buffer is the message that failed to send (allowing the application to
-attempt a retransmission).
+by the buffer is the message that failed to send (allowing the application to
+attempt a retransmission).
When the state is &cw(a_OK) the buffer represents an empty buffer that the application
may fill in in preparation to send.
to the appropriate message type value (as determined by the user programme). Upon send
this value determines how the a library will route the message.
For a buffer which has been received, this field will contain the message type that was
-set by the sending application.
+set by the sending application.
&half_space
&diitem(len ) The application using a buffer to send a message is expected to set the
length value to the actual number of bytes that it placed into the message. This
is likely less than the total number of bytes that the message can carry.
For a message buffer that is passed to the application as the result of a receive
-call, this will be the value that the sending application supplied and should
+call, this will be the value that the sending application supplied and should
indicate the number of bytes in the payload which are valid.
&half_space
&diitem(payload ) The payload is a pointer to the actual received data. The
user programme may read and write from/to the memory referenced by the payload
up until the point in time that the buffer is used on a &cw(rmr_send, rmr_call)
-or &cw(rmr_reply) function call.
+or &cw(rmr_reply) function call.
Once the buffer has been passed back to a a library function the user programme
should &bold(NOT) make use of the payload pointer.
&half_space
-&diitem(xaction) The &ital(xaction) field is a pointer to a fixed sized area in
-the message into which the user may write a transaction ID.
+&diitem(xaction) The &ital(xaction) field is a pointer to a fixed sized area in
+the message into which the user may write a transaction ID.
The ID is optional with the exception of when the user application uses the &cw(rmr_call)
-function to send a message and wait for the reply; the underlying a processing
+function to send a message and wait for the reply; the underlying processing
expects that the matching reply message will also contain the same data in the
&ital(xaction) field.
&end_dlist
.if false
==================================================================================
- Copyright (c) 2020 Nokia
- Copyright (c) 2020 AT&T Intellectual Property.
+ Copyright (c) 2020 Nokia
+ Copyright (c) 2020 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.
==================================================================================
.fi
.if false
- Mnemonic rmr_wh_call_3.xfm
- Abstract The manual page for the rmr_wh_call function.
- Author E. Scott Daniels
- Date 28 January 2019
+ Mnemonic rmr_wh_call_3.xfm
+ Abstract The manual page for the rmr_wh_call function.
+ Author E. Scott Daniels
+ Date 28 January 2019
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_wh_call
+ rmr_wh_call
&h2(SYNOPSIS )
&indent
&uindent
&h2(DESCRIPTION)
-The &cw(rmr_wh_call) function accepts a message buffer (msg) from the user application
+The &cw(rmr_wh_call) function accepts a message buffer (msg) from the user application
and attempts to send it using the wormhole ID provided (whid).
If the send is successful, the call will block until either a response message is
received, or the &cw(max_wait) number of milliseconds has passed.
&space
Like &ital(rmr_wh_send_msg,) this function attempts to send the message directly
-to a process at the other end of a wormhole which was created with &ital(rmr_wh-open().)
-When sending message via wormholes, the normal RMr routing based on message type is
+to a process at the other end of a wormhole which was created with &ital(rmr_wh_open().)
+When sending message via wormholes, the normal RMR routing based on message type is
ignored, and the caller may leave the message type unspecified in the message buffer
(unless it is needed by the receiving process).
-The &cw(call_id) parameter is a number in the range of 2 through 255 and is used to
+The &cw(call_id) parameter is a number in the range of 2 through 255 and is used to
identify the calling thread in order to properly match a response message when it
arrives.
-Providing this value, and ensuring the proper uniqueness, is the responsibility of the
-user application and as such the ability to use the &cw(rmr_wh_call()) function from
+Providing this value, and ensuring the proper uniqueness, is the responsibility of the
+user application and as such the ability to use the &cw(rmr_wh_call()) function from
potentially non-threaded concurrent applications (such as Go's goroutines) is possible.
.** pull in common retry text
-.im &{lib}/man/retry.im
+.im &{lib}/man/retry.im
&h2(RETURN VALUE)
-On success, new message buffer, with the payload containing the response from the remote
+On success, new message buffer, with the payload containing the response from the remote
endpoint is returned.
The state in this buffer will reflect the overall send operation state and should be
&cw(RMR_OK.)
&h2(ERRORS)
The following values may be passed back in the &ital(state) field of the returned message
-buffer.
+buffer.
&space
&beg_dlist(.75i : ^&bold_font )
&space
&ex_start
-#include <rmr/rmr.h> // system headers omitted for clarity
+#include <rmr/rmr.h> // system headers omitted for clarity
int main() {
rmr_whid_t whid = -1; // wormhole id for sending
mrc = rmr_init( "43086", RMR_MAX_RCV_BYTES, RMRFL_NONE );
if( mrc == NULL ) {
- fprintf( stderr, "[FAIL] unable to initialise RMr environment\n" );
+ fprintf( stderr, "[FAIL] unable to initialise RMR environment\n" );
exit( 1 );
}
- while( ! rmr_ready( mrc ) ) { // wait for routing table info
+ while( ! rmr_ready( mrc ) ) { // wait for routing table info
sleep( 1 );
}
while( 1 ) {
if( whid < 0 ) {
whid = rmr_wh_open( mrc, "localhost:6123" ); // open fails if endpoint refuses conn
- if( RMR_WH_CONNECTED( wh ) ) {
+ if( RMR_WH_CONNECTED( wh ) ) {
snprintf( sbuf->payload, 1024, "periodic update from sender: %d", count++ );
sbuf->len = strlen( sbuf->payload );
- sbuf = rmr_wh_call( mrc, whid, sbuf, 1000 ); // expect a response in 1s or less
+ sbuf = rmr_wh_call( mrc, whid, sbuf, 1000 ); // expect a response in 1s or less
if( sbuf != NULL && sbuf->state = RMR_OK ) {
- sprintf( stderr, "response: %s\n", sbuf->payload ); // assume they sent a string
+ sprintf( stderr, "response: %s\n", sbuf->payload ); // assume they sent a string
} else {
sprintf( stderr, "response not received, or send error\n" );
}
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
.fi
.if false
- Mnemonic rmr_wh_close.xfm
- Abstract The manual page for the rmr_wh_close function.
- Author E. Scott Daniels
- Date 21 February 2019
+ Mnemonic rmr_wh_close.xfm
+ Abstract The manual page for the rmr_wh_close function.
+ Author E. Scott Daniels
+ Date 21 February 2019
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_wh_open
+ rmr_wh_close
&h2(SYNOPSIS)
&indent
&h2(DESCRIPTION)
The &cw(rmr_wh_close) function closes the wormhole associated with the wormhole id passed
-in.
+in.
Future calls to &cw(rmr_wh_send_msg) with this ID will fail.
&space
-The underlying TCP connection to the remote endpoint is &bold(not) closed as this
-session may be reqruired for regularlly routed messages (messages routed based on message
-type).
+The underlying TCP connection to the remote endpoint is &bold(not) closed as this
+session may be required for regularly routed messages (messages routed based on message
+type).
There is no way to force a TCP session to be closed at this point in time.
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
.fi
.if false
- Mnemonic rmr_wh_open.xfm
- Abstract The manual page for the rmr_wh_open function.
- Author E. Scott Daniels
- Date 20 February 2019
+ Mnemonic rmr_wh_open.xfm
+ Abstract The manual page for the rmr_wh_open function.
+ Author E. Scott Daniels
+ Date 20 February 2019
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_wh_open
+ rmr_wh_open
&h2(SYNOPSIS)
&indent
be passed to the &cw(rmr_wh_send_msg) function.
&space
-&ital(Target) is the &ital(name:port,) or &ital(IP-address:port,) combination of the
-processess that the wormhole should be connected to.
+&ital(Target) is the &ital(name:port,) or &ital(IP-address:port,) combination of the
+processess that the wormhole should be connected to.
&ital(Vctx) is the RMr void context pointer that was returned by the &cw(rmr_init) function.
&space
-When invoked, this function immediatly attempts to connect to the target process.
-If the connection cannot be established, an error is returned to the caller, and no
-direct messages can be sent to the target.
+When invoked, this function immediatly attempts to connect to the target process.
+If the connection cannot be established, an error is returned to the caller, and no
+direct messages can be sent to the target.
Once a wormhole is connected, the underlying transport mechanism (e.g. NNG) will provide
reconnects should the connection be lost, however the handling of messages sent when
a connection is broken is undetermined as each underlying transport mechanism may handle
&h2(RETURN VALUE)
-The &cw(rmr_wh_open) function returns a type &cw(rmr_whid_t) which must be passed to
-the &cw(rmr_wh_send_msg) function when sending a message.
+The &cw(rmr_wh_open) function returns a type &cw(rmr_whid_t) which must be passed to
+the &cw(rmr_wh_send_msg) function when sending a message.
The id may also be tested to determine success or failure of the connection by
-using the RMR_WH_CONNECTED macro and passing the ID as the parameter; a result of
+using the RMR_WH_CONNECTED macro and passing the ID as the parameter; a result of
1 indicates that the connection was esablished and that the ID is valid.
&h2(ERRORS)
&beg_dlist(.75i : ^&bold_font )
&di(EINVAL) A parameter passed was not valid.
-&di(EACCESS) The user applicarion does not have the ability to establish a wormhole to the
- indicated target (or maybe any target).
+&di(EACCESS) The user application does not have the ability to establish a wormhole to the
+ indicated target (or maybe any target).
&di(ECONNREFUSED) The connection was refused.
&end_dlist
rmc = rmr_init( "43086", 4096, 0 ); // init context
wh = rmr_wh_open( rmc, "localhost:6123" );
- if( !RMR_WH_CONNECTED( wh ) ) {
- fprintf( stderr, "unable to connect wormhole: %s\n",
+ if( !RMR_WH_CONNECTED( wh ) ) {
+ fprintf( stderr, "unable to connect wormhole: %s\n",
strerror( errno ) );
}
&ex_end
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
==================================================================================
.fi
.if false
- Mnemonic rmr_wh_send_msg_man.xfm
- Abstract The manual page for the rmr_wh_send_msg function.
- Author E. Scott Daniels
- Date 28 January 2019
+ Mnemonic rmr_wh_send_msg_man.xfm
+ Abstract The manual page for the rmr_wh_send_msg function.
+ Author E. Scott Daniels
+ Date 28 January 2019
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_wh_send_msg
+ rmr_wh_send_msg
&h2(SYNOPSIS )
&indent
&uindent
&h2(DESCRIPTION)
-The &cw(rmr_wh_send_msg) function accepts a message buffer from the user application
+The &cw(rmr_wh_send_msg) function accepts a message buffer from the user application
and attempts to send it using the wormhole ID provided (id).
Unlike &ital(rmr_send_msg,) this function attempts to send the message directly
-to a process at the other end of a wormhole which was created with &ital(rmr_wh-open().)
-When sending message via wormholes, the normal RMr routing based on message type is
+to a process at the other end of a wormhole which was created with &ital(rmr_wh_open().)
+When sending message via wormholes, the normal RMR routing based on message type is
ignored, and the caller may leave the message type unspecified in the message buffer
(unless it is needed by the receiving process).
.sp
-The message buffer (msg) used to send is the same format as used for regular RMr
+The message buffer (msg) used to send is the same format as used for regular RMR
send and reply to sender operations, thus any buffer allocated by these means, or
calls to &ital(rmr_rcv_msg()) can be passed to this function.
.** pull in common retry text
-.im &{lib}/man/retry.im
+.im &{lib}/man/retry.im
&h2(RETURN VALUE)
On success, a new message buffer, with an empty payload, is returned for the application
&cw(RMR_OK.)
&space
-If the state in the returned buffer is anything other than &cw(RMR_OK,) the user application
+If the state in the returned buffer is anything other than &cw(RMR_OK,) the user application
may need to attempt a retransmission of the message, or take other action depending on the
-setting of &cw(errno) as described below.
+setting of &cw(errno) as described below.
&space
-In the event of extreme failure, a NULL pointer is returned. In this case the value of
-&cw(errno) might be of some use, for documentation, but there will be little that the
+In the event of extreme failure, a nil pointer is returned. In this case the value of
+&cw(errno) might be of some use, for documentation, but there will be little that the
user application can do other than to move on.
&h2(ERRORS)
The following values may be passed back in the &ital(state) field of the returned message
-buffer.
+buffer.
&space
&beg_dlist(.75i : ^&bold_font )
&di(EMSGSIZE) The underlying transport refused to accept the message because of a size value issue (message was not attempted to be sent).
&half_space
-&di(EFAULT) The message referenced by the message buffer is corrupt (NULL pointer or bad internal length).
+&di(EFAULT) The message referenced by the message buffer is corrupt (nil pointer or bad internal length).
&half_space
&di(EBADF) Internal RMR error; information provided to the message transport environment was not valid.
&space
&ex_start
-#include <rmr/rmr.h> // system headers omitted for clarity
+#include <rmr/rmr.h> // system headers omitted for clarity
int main() {
rmr_whid_t whid = -1; // wormhole id for sending
mrc = rmr_init( "43086", RMR_MAX_RCV_BYTES, RMRFL_NONE );
if( mrc == NULL ) {
- fprintf( stderr, "[FAIL] unable to initialise RMr environment\n" );
+ fprintf( stderr, "[FAIL] unable to initialise RMR environment\n" );
exit( 1 );
}
- while( ! rmr_ready( mrc ) ) { // wait for routing table info
+ while( ! rmr_ready( mrc ) ) { // wait for routing table info
sleep( 1 );
}
while( 1 ) {
if( whid < 0 ) {
whid = rmr_wh_open( mrc, "localhost:6123" ); // open fails if endpoint refuses conn
- if( RMR_WH_CONNECTED( wh ) ) {
+ if( RMR_WH_CONNECTED( wh ) ) {
snprintf( sbuf->payload, 1024, "periodic update from sender: %d", count++ );
sbuf->len = strlen( sbuf->payload );
sbuf = rmr_wh_send_msg( mrc, whid, sbuf );
- }
- }
+ }
+ }
- sleep( 5 );
+ sleep( 5 );
}
}
&ex_end
.if false
==================================================================================
- Copyright (c) 2020 Nokia
- Copyright (c) 2020 AT&T Intellectual Property.
+ Copyright (c) 2020 Nokia
+ Copyright (c) 2020 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.
.fi
.if false
- Mnemonic rmr_wh_state.xfm
- Abstract The manual page for the rmr_wh_state function.
- Author E. Scott Daniels
- Date 6 March 2020
+ Mnemonic rmr_wh_state.xfm
+ Abstract The manual page for the rmr_wh_state function.
+ Author E. Scott Daniels
+ Date 6 March 2020
.fi
.gv e LIB lib
-.im &{lib}/man/setup.im
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_wh_state
+ rmr_wh_state
&h2(SYNOPSIS)
&indent
&h2(DESCRIPTION)
The &cw(rmr_wh_state) function will return the current state of the connection
-associated with the given wormhole (whid).
+associated with the given wormhole (whid).
The return value indicates whether the connection is open (RMR_OK), or closed
(any other return value).
&space
&beg_dlist(.75i : ^&bold_font )
-&di(RMR_OK)
- The wormhole ID is valid and the connection is "open."
- &half_space
+&di(RMR_OK)
+ The wormhole ID is valid and the connection is "open."
+ &half_space
&di(RMR_ERR_WHID)
- THe wormhole ID passed into the function was not valid.
- &half_space
+ THe wormhole ID passed into the function was not valid.
+ &half_space
&di(RMR_ERR_NOENDPT)
- The wormhole is not open (not connected).
- &half_space
+ The wormhole is not open (not connected).
+ &half_space
&di(RMR_ERR_BADARG)
- The context passed to the function was nil or invalid.
- &half_space
+ The context passed to the function was nil or invalid.
+ &half_space
&di(RMR_ERR_NOWHOPEN)
- Wormholes have not been initialised (no wormhole open call has been made).
- &half_space
+ Wormholes have not been initialised (no wormhole open call has been made).
+ &half_space
&end_dlist
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
.fi
.if false
- Mnemonic: setup.im
- Abstract: Look at environment variables and pull in the correct setup prep
- imbed file based on the desired output type (when running tfm).
- Obviously, when running pfm we are always generating postscirpt
- so this isn't really doing much.
- Date: 29 July 2019
+ Mnemonic: setup.im
+ Abstract: Look at environment variables and pull in the correct setup prep
+ imbed file based on the desired output type (when running tfm).
+ Obviously, when running pfm we are always generating postscirpt
+ so this isn't really doing much.
+ Date: 29 July 2019
.fi
-.if ! _setup_im
+.if ! _setup_im
.gv e LIB lib
.if ! lib
- .dv lib ..
+ .dv lib ..
.fi
.** CAUTION: xfm comparisons are reverse polish so "a b =" is true if a == b.
.if pfm
- .im &{lib}/generic_ps.im
+ .im &{lib}/generic_ps.im
.ei
- .gv e OUTPUT_TYPE ot
- .if "&ot" "txt" =
- .im &{lib}/txt.im
- .fi
- .if "&ot" "rst" =
- .im &{lib}/rst.im
- .fi
- .if "&ot" "markdown" =
- .im &{lib}/markdown.im
- .fi
- .if "&ot" "troff" =
- .im &{lib}/roff.im
- .fi
+ .gv e OUTPUT_TYPE ot
+ .if "&ot" "txt" =
+ .im &{lib}/txt.im
+ .fi
+ .if "&ot" "rst" =
+ .im &{lib}/rst.im
+ .fi
+ .if "&ot" "markdown" =
+ .im &{lib}/markdown.im
+ .fi
+ .if "&ot" "troff" =
+ .im &{lib}/roff.im
+ .fi
.fi
.dv _setup_im 1
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)
+ 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
+ the application to continue unimpeded 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.
+ 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
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.
+ the Route Manager's 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.
+ To maintain backwards compatibility 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
+ 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
**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.
+ 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
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)
+ start and end records).
RMR_SRC_ID
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
+messaging transport environment (e.g., SI95) 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.
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)
+ 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
+ the application to continue unimpeded 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.
+ 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
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.
+ the Route Manager's 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.
+ To maintain backwards compatibility 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
+ 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
**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.
+ 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
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)
+ start and end records).
RMR_SRC_ID
--------------------------------------------------------------------------------------------
+2020 April 6; version 3.6.6
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Correct bug in SI95 address conversion module (RIC-327)
+Correct bug in SI initialisation module
+
+
2020 April 2; version 3.6.5
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
int len;
unsigned char* payload;
unsigned char* xaction;
- uint sub_id;
- uint tp_state;
+ int sub_id;
+ int tp_state;
} rmr_mbuf_t;
Messages which are received while waiting for the response
are queued internally by RMR, and are returned to the user
application when rmr_rcv_msg is invoked. These messages are
-returned in th order received, one per call to rmr_rcv_msg.
+returned in the order received, one per call to rmr_rcv_msg.
Call Timeout
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
prevent, in most cases, the function from blocking forever.
The timeout period is **not** based on time (calls to clock
are deemed too expensive for a low latency system level
-library, but instead the period is based on the number of
+library), but instead the period is based on the number of
received messages which are not the response. Using a
non-time mechanism for *timeout* prevents the async queue
from filling (which would lead to message drops) in an
Retries
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The send operations in RMr will retry *soft* send failures
+The send operations in RMR will retry *soft* send failures
until one of three conditions occurs:
2.
- The underlying transport reports a * hard * failure
+ The underlying transport reports a *hard* failure
3.
The maximum number of retry loops has been attempted
-A retry loop consists of approximately 1000 send attemps **
-without** any intervening calls to * sleep() * or * usleep().
-* The number of retry loops defaults to 1, thus a maximum of
+A retry loop consists of approximately 1000 send attempts
+**without** any intervening calls to *sleep()* or *usleep().*
+The number of retry loops defaults to 1, thus a maximum of
1000 send attempts is performed before returning to the user
application. This value can be set at any point after RMr
-initialisation using the * rmr_set_stimeout() * function
+initialisation using the *rmr_set_stimeout()* function
allowing the user application to completely disable retires
(set to 0), or to increase the number of retry loops.
immediately to the user application.
It should be noted that depending on the underlying transport
-mechanism being used, it is extremly possible that during
-normal operations that retry conditions are very likely to
-happen. These are completely out of RMr's control, and there
-is nothing that RMr can do to avoid or midigate these other
-than by allowing RMr to retry the send operation, and even
-then it is possible (e.g. during connection reattempts), that
-a single retry loop is not enough to guarentee a successful
-send.
+mechanism being used, it is extremely likely that retry
+conditions will happen during normal operations. These are
+completely out of RMR's control, and there is nothing that
+RMR can do to avoid or mitigate these other than by allowing
+RMR to retry the send operation, and even then it is possible
+(e.g., during connection reattempts), that a single retry
+loop is not enough to guarantee a successful send.
RETURN VALUE
--------------------------------------------------------------------------------------------
EAGAIN
- The underlying message system wsa interrupted or the
- device was busy; the message was **not** sent, and user
- application should call this function with the message
- again.
+ The underlying message system was interrupted or the
+ device was busy; the message was **not** sent, and the
+ user application should call this function with the
+ message again.
EXAMPLE
--------------------------------------------------------------------------------------------
-The following code bit shows one way of using the rmr_call
-function, and illustrates how the transaction ID must be set.
+The following code snippet shows one way of using the
+rmr_call function, and illustrates how the transaction ID
+must be set.
::
int retry_delay = 50000; // retry delay (usec)
static rmr_mbuf_t* mbuf = NULL; // response msg
msg_t* pm; // private message (payload)
- m// get a send buffer and reference the payload
+ // get a send buffer and reference the payload
mbuf = rmr_alloc_msg( mr, RMR_MAX_RCV_BYTES );
pm = (msg_t*) mbuf->payload;
- p// generate an xaction ID and fill in payload with data and msg type
+ // generate an xaction ID and fill in payload with data and msg type
snprintf( mbuf->xaction, RMR_MAX_XID, "%s", gen_xaction() );
snprintf( pm->req, sizeof( pm->req ), "{ \\"req\\": \\"num users\\"}" );
mbuf->mtype = MT_REQ;
-
msg = rmr_call( mr, msg );
if( ! msg ) { // probably a timeout and no msg received
return NULL; // let errno trickle up
- }
+ }
if( mbuf->state != RMR_OK ) {
while( retries_left-- > 0 && // loop as long as eagain
- errno == EAGAIN &&
- (msg = rmr_call( mr, msg )) != NULL &&
+ errno == EAGAIN &&
+ (msg = rmr_call( mr, msg )) != NULL &&
mbuf->state != RMR_OK ) {
usleep( retry_delay );
}
-
if( mbuf == NULL || mbuf->state != RMR_OK ) {
rmr_free_msg( mbuf ); // safe if nil
return NULL;
NAME
--------------------------------------------------------------------------------------------
-rmr_wh_open
+rmr_close
SYNOPSIS
--------------------------------------------------------------------------------------------
The context (ctx) pointer passed in is the pointer returned
by the call to rmr_init().
-**NOTE:** There is no support for epoll in Nanomsg, thus his
-function is only supported when linking with the NNG version
-of RMr and the file descriptor returned when using the
-Nanomsg verfsion will always return an error.
-
RETURN VALUE
--------------------------------------------------------------------------------------------
The rmr_get_rcvfd function returns a file descriptor greater
-or equal to 0 on success and -1 on error. If this function is
-called from a user application linked against the Nanomsg RMr
-library, calls will always return -1 with errno set to
-EINVAL.
+or equal to 0 on success and -1 on error.
ERRORS
--------------------------------------------------------------------------------------------
rmr_mbuf_t* msg = NULL;
int nready;
int i;
-
mrc = rmr_init( "43086", RMR_MAX_RCV_BYTES, RMRFL_NONE );
rcv_fd = rmr_get_rcvfd( mrc );
-
- rep_fd = epoll_create1( 0 ); _ B ,// initialise epoll environment
+ ep_fd = epoll_create1( 0 ); // initialise epoll environment
epe.events = EPOLLIN;
epe.data.fd = rcv_fd;
epoll_ctl( ep_fd, EPOLL_CTL_ADD, rcv_fd, &epe ); // add our info to the mix
-
while( 1 ) {
- nready = epoll_wait( ep_fd, events, 10, -1 ); // -1 == block forever (no timeout)
- for( i = 0; i < nready && i < 10; i++ ) { // loop through to find what is ready
- if( events[i].data.fd == rcv_fd ) { // RMr has something
+ nready = epoll_wait( ep_fd, events, 10, -1 ); // -1 == block forever (no timeout)
+ for( i = 0; i < nready && i < 10; i++ ) { // loop through to find what is ready
+ if( events[i].data.fd == rcv_fd ) { // RMR has something
msg = rmr_rcv_msg( mrc, msg );
if( msg ) {
// do something with msg
}
}
-
// check for other ready fds....
}
}
ENVIRONMENT
--------------------------------------------------------------------------------------------
-As a part of the initialisation process rmr_init will look
-into the available environment variables to influence it's
-setup. The following variables will be used when found.
+As a part of the initialisation process rmr_init reads
+environment variables to configure itself. The following
+variables are used if found.
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)
+ 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
+ the application to continue unimpeded 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.
+ 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
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.
+ the Route Manager's 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.
+ To maintain backwards compatibility 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
+ 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
**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.
+ 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
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)
+ start and end records).
RMR_SRC_ID
to the user application with the next invocation of
*rmr_mt_rcv()* or *rmr_rvv_msg().* by RMR, and are returned
to the user application when rmr_rcv_msg is invoked. These
-messages are returned in th order received, one per call to
+messages are returned in the order received, one per call to
rmr_rcv_msg.
-NOTE: Currently the multi-threaded functions are supported
-only when the NNG transport mechanism is being used. It will
-not be possible to link a programme using the Nanomsg version
-of the library when references to this function are present.
-
The Transaction ID
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The user application is responsible for setting the value of
the transaction ID field before invoking *rmr_mt_call.* The
transaction ID is a RMR_MAX_XID byte field that is used to
-match the response message when it arrives. RMr will compare
+match the response message when it arrives. RMR will compare
**all** of the bytes in the field, so the caller must ensure
that they are set correctly to avoid missing the response
-message. (The application which returns the response message
+message. The application which returns the response message
is also expected to ensure that the return buffer has the
matching transaction ID. This can be done transparently if
the application uses the *rmr_rts_msg()* function and does
Retries
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The send operations in RMr will retry *soft* send failures
+The send operations in RMR will retry *soft* send failures
until one of three conditions occurs:
2.
- The underlying transport reports a * hard * failure
+ The underlying transport reports a *hard* failure
3.
The maximum number of retry loops has been attempted
-A retry loop consists of approximately 1000 send attemps **
-without** any intervening calls to * sleep() * or * usleep().
-* The number of retry loops defaults to 1, thus a maximum of
+A retry loop consists of approximately 1000 send attempts
+**without** any intervening calls to *sleep()* or *usleep().*
+The number of retry loops defaults to 1, thus a maximum of
1000 send attempts is performed before returning to the user
application. This value can be set at any point after RMr
-initialisation using the * rmr_set_stimeout() * function
+initialisation using the *rmr_set_stimeout()* function
allowing the user application to completely disable retires
(set to 0), or to increase the number of retry loops.
immediately to the user application.
It should be noted that depending on the underlying transport
-mechanism being used, it is extremly possible that during
-normal operations that retry conditions are very likely to
-happen. These are completely out of RMr's control, and there
-is nothing that RMr can do to avoid or midigate these other
-than by allowing RMr to retry the send operation, and even
-then it is possible (e.g. during connection reattempts), that
-a single retry loop is not enough to guarentee a successful
-send.
+mechanism being used, it is extremely likely that retry
+conditions will happen during normal operations. These are
+completely out of RMR's control, and there is nothing that
+RMR can do to avoid or mitigate these other than by allowing
+RMR to retry the send operation, and even then it is possible
+(e.g., during connection reattempts), that a single retry
+loop is not enough to guarantee a successful send.
RETURN VALUE
--------------------------------------------------------------------------------------------
int retries_left = 5; // max retries on dev not available
static rmr_mbuf_t* mbuf = NULL; // response msg
msg_t* pm; // private message (payload)
- m// get a send buffer and reference the payload
+ // get a send buffer and reference the payload
mbuf = rmr_alloc_msg( mr, RMR_MAX_RCV_BYTES );
pm = (msg_t*) mbuf->payload;
- p// generate an xaction ID and fill in payload with data and msg type
+ // generate an xaction ID and fill in payload with data and msg type
rmr_bytes2xact( mbuf, xid, RMR_MAX_XID );
snprintf( pm->req, sizeof( pm->req ), "{ \\"req\\": \\"num users\\"}" );
mbuf->mtype = MT_USR_RESP;
-
- msg = rmr_mt_call( mr, msg, my_id, 100 ); e :// wait up to 100ms
+ msg = rmr_mt_call( mr, msg, my_id, 100 ); // wait up to 100ms
if( ! msg ) { // probably a timeout and no msg received
return NULL; // let errno trickle up
- }
+ }
if( mbuf->state != RMR_OK ) {
while( retries_left-- > 0 && // loop as long as eagain
- mbuf->state == RMR_ERR_RETRY &&
- (msg = rmr_mt_call( mr, msg )) != NULL &&
+ mbuf->state == RMR_ERR_RETRY &&
+ (msg = rmr_mt_call( mr, msg )) != NULL &&
mbuf->state != RMR_OK ) {
usleep( retry_delay );
}
-
+
if( mbuf == NULL || mbuf->state != RMR_OK ) {
rmr_free_msg( mbuf ); // safe if nil
return NULL;
allocate one.
The *old_msg* parameter allows the user to pass a previously
-generated RMr message back to RMr for reuse. Optionally, the
+generated RMR message back to RMR for reuse. Optionally, the
user application may pass a nil pointer if no reusable
message is available. When a timeout occurs, and old_msg was
not nil, the state will be returned by returning a pointer to
the old message with the state set.
It is possible to use the *rmr_rcv_msg()* function instead of
-this function. Doing so might be advantagous if the user
+this function. Doing so might be advantageous if the user
programme does not always start the multi-threaded mode and
the use of *rmr_rcv_msg()* would make the flow of the code
-more simple. The advantags of using this function are the
+more simple. The advantages of using this function are the
ability to set a timeout without using epoll, and a small
performance gain (if multi-threaded mode is enabled, and the
*rmr_rcv_msg()* function is used, it simply invokes this
mode with the same "pass through" overhead to using this
function directly.
-NOTE: Currently the multi-threaded functions are supported
-only when the NNG transport mechanism is being used. It will
-not be possible to link a programme using the nanomsg version
-of the library when references to this function are present.
-
RETURN VALUE
--------------------------------------------------------------------------------------------
ERRORS
--------------------------------------------------------------------------------------------
-The *state* field in the message buffer will indicate either
-RMR_OK when the message receive process was successful and
-the message can be used by the caller. Depending on the
+The *state* field in the message buffer will indicate 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:
message buffer with the payload which is large enough to hold
*new_len* bytes. If the *clone* option is true, this will be
a pointer to the newly cloned message buffer; the original
-message buffer pointer may still be used to referenced that
+message buffer pointer may still be used to reference that
message. It is the calling application's responsibility to
free the memory associateed with both messages using the
rmr_free_msg() function.
if( msg == NULL ) {
fprintf( stderr, "[ERR] realloc returned a nil pointer: %s\\n", strerror( errno ) );
} else {
- } e// populate and send ack message
- }}
+ // populate and send ack message
+ }
}
Retries
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The send operations in RMr will retry *soft* send failures
+The send operations in RMR will retry *soft* send failures
until one of three conditions occurs:
2.
- The underlying transport reports a * hard * failure
+ The underlying transport reports a *hard* failure
3.
The maximum number of retry loops has been attempted
-A retry loop consists of approximately 1000 send attemps **
-without** any intervening calls to * sleep() * or * usleep().
-* The number of retry loops defaults to 1, thus a maximum of
+A retry loop consists of approximately 1000 send attempts
+**without** any intervening calls to *sleep()* or *usleep().*
+The number of retry loops defaults to 1, thus a maximum of
1000 send attempts is performed before returning to the user
application. This value can be set at any point after RMr
-initialisation using the * rmr_set_stimeout() * function
+initialisation using the *rmr_set_stimeout()* function
allowing the user application to completely disable retires
(set to 0), or to increase the number of retry loops.
immediately to the user application.
It should be noted that depending on the underlying transport
-mechanism being used, it is extremly possible that during
-normal operations that retry conditions are very likely to
-happen. These are completely out of RMr's control, and there
-is nothing that RMr can do to avoid or midigate these other
-than by allowing RMr to retry the send operation, and even
-then it is possible (e.g. during connection reattempts), that
-a single retry loop is not enough to guarentee a successful
-send.
+mechanism being used, it is extremely likely that retry
+conditions will happen during normal operations. These are
+completely out of RMR's control, and there is nothing that
+RMR can do to avoid or mitigate these other than by allowing
+RMR to retry the send operation, and even then it is possible
+(e.g., during connection reattempts), that a single retry
+loop is not enough to guarantee a successful send.
PAYLOAD SIZE
--------------------------------------------------------------------------------------------
case of a received message, it is possible that the response
needs to be larger than the payload associated with the
inbound message. In order to use the return to sender
-function, the source infomration in the orignal message must
+function, the source information in the original message must
be present in the response; information which cannot be added
to a message buffer allocated through the standard RMR
allocation function. To allocate a buffer with a larger
state and should be RMR_OK.
If the state in the returned buffer is anything other than
-UT_OK, the user application may need to attempt a
+RMR_OK, the user application may need to attempt a
retransmission of the message, or take other action depending
on the setting of errno as described below.
Retries
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The send operations in RMr will retry *soft* send failures
+The send operations in RMR will retry *soft* send failures
until one of three conditions occurs:
2.
- The underlying transport reports a * hard * failure
+ The underlying transport reports a *hard* failure
3.
The maximum number of retry loops has been attempted
-A retry loop consists of approximately 1000 send attemps **
-without** any intervening calls to * sleep() * or * usleep().
-* The number of retry loops defaults to 1, thus a maximum of
+A retry loop consists of approximately 1000 send attempts
+**without** any intervening calls to *sleep()* or *usleep().*
+The number of retry loops defaults to 1, thus a maximum of
1000 send attempts is performed before returning to the user
application. This value can be set at any point after RMr
-initialisation using the * rmr_set_stimeout() * function
+initialisation using the *rmr_set_stimeout()* function
allowing the user application to completely disable retires
(set to 0), or to increase the number of retry loops.
immediately to the user application.
It should be noted that depending on the underlying transport
-mechanism being used, it is extremly possible that during
-normal operations that retry conditions are very likely to
-happen. These are completely out of RMr's control, and there
-is nothing that RMr can do to avoid or midigate these other
-than by allowing RMr to retry the send operation, and even
-then it is possible (e.g. during connection reattempts), that
-a single retry loop is not enough to guarentee a successful
-send.
+mechanism being used, it is extremely likely that retry
+conditions will happen during normal operations. These are
+completely out of RMR's control, and there is nothing that
+RMR can do to avoid or mitigate these other than by allowing
+RMR to retry the send operation, and even then it is possible
+(e.g., during connection reattempts), that a single retry
+loop is not enough to guarantee a successful send.
RETURN VALUE
--------------------------------------------------------------------------------------------
static rmr_mbuf_t* send_msg = NULL; // message to send; reused on each call
msg_t* send_pm; // payload for send
msg_t* pm; // our message format in the received payload
- mif( send_msg == NULL ) {
- send_msg = rmr_alloc_msg( mr, MAX_SIZE ); r// new buffer to send
- }
- // reference payload and fill in message type
+ if( send_msg == NULL ) {
+ send_msg = rmr_alloc_msg( mr, MAX_SIZE ); // new buffer to send
+ }
+ // reference payload and fill in message type
pm = (msg_t*) send_msg->payload;
send_msg->mtype = MT_ANSWER;
msg->len = generate_data( pm ); // something that fills the payload in
msg = rmr_send_msg( mr, send_msg ); // ensure new pointer used after send
- mif( ! msg ) {
- m !return ERROR;
- m} else {
- m sif( msg->state != RMR_OK ) {
- m s m// check for RMR_ERR_RETRY, and resend if needed
- m s m// else return error
- m s}
- m}
- mreturn OK;
+ if( ! msg ) {
+ return ERROR;
+ } else {
+ if( msg->state != RMR_OK ) {
+ // check for RMR_ERR_RETRY, and resend if needed
+ // else return error
+ }
+ }
+ return OK;
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
+be useful for applications which must send messages at a
maximum rate.
RETURN VALUE
::
#define NO_FLAGS 0
- char* Oport = "43086"; // port for message router listen
- int rmax_size = 4096; // max message size for default allocations
- void* mr_context; // message router context
+ char* port = "43086"; // port for message router listen
+ int max_size = 4096; // max message size for default allocations
+ void* mr_context; // message router context
mr_context = rmr_init( port, max_size, NO_FLAGS );
if( mr_context != NULL ) {
rmr_set_stimeout( mr_context, 0 ); // turn off retries
NAME
--------------------------------------------------------------------------------------------
-rmr_set_trace
+rmr_set_vlevel
SYNOPSIS
--------------------------------------------------------------------------------------------
as it can grossly affect performance.
-generally RMR does not write messages to the standard error
+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.
+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
DESCRIPTION
--------------------------------------------------------------------------------------------
-The rmr_trace_ref function return a pointer to the trace area
-in the message, and optionally populate the user programme
-supplied size integer with the trace area size, if *sizeptr*
-is not nil.
+The rmr_trace_ref function returns a pointer to the trace
+area in the message, and optionally populates the user
+programme supplied size integer with the trace area size, if
+*sizeptr* is not nil.
RETURN VALUE
--------------------------------------------------------------------------------------------
::
#include <rmr/rmr.h>
- rmr_mbuf_t* rmr_tralloc_msg( void* vctx, int size,
+ rmr_mbuf_t* rmr_tralloc_msg( void* vctx, int size,
int trace_size, unsigned const char *tr_data );
DESCRIPTION
--------------------------------------------------------------------------------------------
-The rmr_alloc_msg function is used to allocate a buffer which
-the user programme can write into and then send through the a
-library. The buffer is allocated such that sending it
+The rmr_tralloc_msg function is used to allocate a buffer
+which the user programme can write into and then send through
+the library. The buffer is allocated such that sending it
requires no additional copying from the buffer as it passes
through the underlying transport mechanism.
The *size* parameter is used to set the payload length in the
-message and If it is 0, then the default size supplied on the
+message. If it is 0, then the default size supplied on the
*rmr_init* call will be used. In addition to allocating the
payload, a space in the buffer is reserved for *trace* data
(tr_size bytes), and the bytes pointed to by *tr_data* are
the message into which the user may write a transaction
ID. The ID is optional with the exception of when the user
application uses the rmr_call function to send a message
- and wait for the reply; the underlying a processing
- expects that the matching reply message will also contain
- the same data in the *xaction* field.
+ and wait for the reply; the underlying processing expects
+ that the matching reply message will also contain the same
+ data in the *xaction* field.
RETURN VALUE
Like *rmr_wh_send_msg,* this function attempts to send the
message directly to a process at the other end of a wormhole
-which was created with *rmr_wh-open().* When sending message
-via wormholes, the normal RMr routing based on message type
+which was created with *rmr_wh_open().* When sending message
+via wormholes, the normal RMR routing based on message type
is ignored, and the caller may leave the message type
unspecified in the message buffer (unless it is needed by the
receiving process). The call_id parameter is a number in the
Retries
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The send operations in RMr will retry *soft* send failures
+The send operations in RMR will retry *soft* send failures
until one of three conditions occurs:
2.
- The underlying transport reports a * hard * failure
+ The underlying transport reports a *hard* failure
3.
The maximum number of retry loops has been attempted
-A retry loop consists of approximately 1000 send attemps **
-without** any intervening calls to * sleep() * or * usleep().
-* The number of retry loops defaults to 1, thus a maximum of
+A retry loop consists of approximately 1000 send attempts
+**without** any intervening calls to *sleep()* or *usleep().*
+The number of retry loops defaults to 1, thus a maximum of
1000 send attempts is performed before returning to the user
application. This value can be set at any point after RMr
-initialisation using the * rmr_set_stimeout() * function
+initialisation using the *rmr_set_stimeout()* function
allowing the user application to completely disable retires
(set to 0), or to increase the number of retry loops.
immediately to the user application.
It should be noted that depending on the underlying transport
-mechanism being used, it is extremly possible that during
-normal operations that retry conditions are very likely to
-happen. These are completely out of RMr's control, and there
-is nothing that RMr can do to avoid or midigate these other
-than by allowing RMr to retry the send operation, and even
-then it is possible (e.g. during connection reattempts), that
-a single retry loop is not enough to guarentee a successful
-send.
+mechanism being used, it is extremely likely that retry
+conditions will happen during normal operations. These are
+completely out of RMR's control, and there is nothing that
+RMR can do to avoid or mitigate these other than by allowing
+RMR to retry the send operation, and even then it is possible
+(e.g., during connection reattempts), that a single retry
+loop is not enough to guarantee a successful send.
RETURN VALUE
--------------------------------------------------------------------------------------------
::
- #include <rmr/rmr.h> .// system headers omitted for clarity
+ #include <rmr/rmr.h> // system headers omitted for clarity
int main() {
rmr_whid_t whid = -1; // wormhole id for sending
void* mrc; //msg router context
int count = 0;
mrc = rmr_init( "43086", RMR_MAX_RCV_BYTES, RMRFL_NONE );
if( mrc == NULL ) {
- fprintf( stderr, "[FAIL] unable to initialise RMr environment\\n" );
+ fprintf( stderr, "[FAIL] unable to initialise RMR environment\\n" );
exit( 1 );
}
- while( ! rmr_ready( mrc ) ) { e i// wait for routing table info
+ while( ! rmr_ready( mrc ) ) { // wait for routing table info
sleep( 1 );
}
sbuf = rmr_alloc_msg( mrc, 2048 );
while( 1 ) {
if( whid < 0 ) {
whid = rmr_wh_open( mrc, "localhost:6123" ); // open fails if endpoint refuses conn
- w if( RMR_WH_CONNECTED( wh ) ) {
+ if( RMR_WH_CONNECTED( wh ) ) {
snprintf( sbuf->payload, 1024, "periodic update from sender: %d", count++ );
sbuf->len = strlen( sbuf->payload );
- sbuf = rmr_wh_call( mrc, whid, sbuf, 1000 ); f s// expect a response in 1s or less
+ sbuf = rmr_wh_call( mrc, whid, sbuf, 1000 ); // expect a response in 1s or less
if( sbuf != NULL && sbuf->state = RMR_OK ) {
- sprintf( stderr, "response: %s\\n", sbuf->payload ); x// assume they sent a string
+ sprintf( stderr, "response: %s\\n", sbuf->payload ); // assume they sent a string
} else {
sprintf( stderr, "response not received, or send error\\n" );
}
NAME
--------------------------------------------------------------------------------------------
-rmr_wh_open
+rmr_wh_close
SYNOPSIS
--------------------------------------------------------------------------------------------
with this ID will fail.
The underlying TCP connection to the remote endpoint is
-**not** closed as this session may be reqruired for
-regularlly routed messages (messages routed based on message
-type). There is no way to force a TCP session to be closed at
-this point in time.
+**not** closed as this session may be required for regularly
+routed messages (messages routed based on message type).
+There is no way to force a TCP session to be closed at this
+point in time.
SEE ALSO
--------------------------------------------------------------------------------------------
EACCESS
- The user applicarion does not have the ability to
+ The user application does not have the ability to
establish a wormhole to the indicated target (or maybe any
target).
rmr_whid_t wh;
rmc = rmr_init( "43086", 4096, 0 ); // init context
wh = rmr_wh_open( rmc, "localhost:6123" );
- if( !RMR_WH_CONNECTED( wh ) ) {
- f fprintf( stderr, "unable to connect wormhole: %s\\n",
+ if( !RMR_WH_CONNECTED( wh ) ) {
+ fprintf( stderr, "unable to connect wormhole: %s\\n",
strerror( errno ) );
}
wormhole ID provided (id). Unlike *rmr_send_msg,* this
function attempts to send the message directly to a process
at the other end of a wormhole which was created with
-*rmr_wh-open().* When sending message via wormholes, the
-normal RMr routing based on message type is ignored, and the
+*rmr_wh_open().* When sending message via wormholes, the
+normal RMR routing based on message type is ignored, and the
caller may leave the message type unspecified in the message
buffer (unless it is needed by the receiving process).
The message buffer (msg) used to send is the same format as
-used for regular RMr send and reply to sender operations,
+used for regular RMR send and reply to sender operations,
thus any buffer allocated by these means, or calls to
*rmr_rcv_msg()* can be passed to this function.
Retries
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The send operations in RMr will retry *soft* send failures
+The send operations in RMR will retry *soft* send failures
until one of three conditions occurs:
2.
- The underlying transport reports a * hard * failure
+ The underlying transport reports a *hard* failure
3.
The maximum number of retry loops has been attempted
-A retry loop consists of approximately 1000 send attemps **
-without** any intervening calls to * sleep() * or * usleep().
-* The number of retry loops defaults to 1, thus a maximum of
+A retry loop consists of approximately 1000 send attempts
+**without** any intervening calls to *sleep()* or *usleep().*
+The number of retry loops defaults to 1, thus a maximum of
1000 send attempts is performed before returning to the user
application. This value can be set at any point after RMr
-initialisation using the * rmr_set_stimeout() * function
+initialisation using the *rmr_set_stimeout()* function
allowing the user application to completely disable retires
(set to 0), or to increase the number of retry loops.
immediately to the user application.
It should be noted that depending on the underlying transport
-mechanism being used, it is extremly possible that during
-normal operations that retry conditions are very likely to
-happen. These are completely out of RMr's control, and there
-is nothing that RMr can do to avoid or midigate these other
-than by allowing RMr to retry the send operation, and even
-then it is possible (e.g. during connection reattempts), that
-a single retry loop is not enough to guarentee a successful
-send.
+mechanism being used, it is extremely likely that retry
+conditions will happen during normal operations. These are
+completely out of RMR's control, and there is nothing that
+RMR can do to avoid or mitigate these other than by allowing
+RMR to retry the send operation, and even then it is possible
+(e.g., during connection reattempts), that a single retry
+loop is not enough to guarantee a successful send.
RETURN VALUE
--------------------------------------------------------------------------------------------
::
- #include <rmr/rmr.h> .// system headers omitted for clarity
+ #include <rmr/rmr.h> // system headers omitted for clarity
int main() {
rmr_whid_t whid = -1; // wormhole id for sending
void* mrc; //msg router context
int count = 0;
mrc = rmr_init( "43086", RMR_MAX_RCV_BYTES, RMRFL_NONE );
if( mrc == NULL ) {
- fprintf( stderr, "[FAIL] unable to initialise RMr environment\\n" );
+ fprintf( stderr, "[FAIL] unable to initialise RMR environment\\n" );
exit( 1 );
}
- while( ! rmr_ready( mrc ) ) { e i// wait for routing table info
+ while( ! rmr_ready( mrc ) ) { // wait for routing table info
sleep( 1 );
}
sbuf = rmr_alloc_msg( mrc, 2048 );
while( 1 ) {
if( whid < 0 ) {
whid = rmr_wh_open( mrc, "localhost:6123" ); // open fails if endpoint refuses conn
- w if( RMR_WH_CONNECTED( wh ) ) {
+ if( RMR_WH_CONNECTED( wh ) ) {
snprintf( sbuf->payload, 1024, "periodic update from sender: %d", count++ );
sbuf->len = strlen( sbuf->payload );
sbuf = rmr_wh_send_msg( mrc, whid, sbuf );
- }
- }
- sleep( 5 );
+ }
+ }
+ sleep( 5 );
}
}
Code Review / ric-plt / lib / rmr.git / commitdiff