From 5157a97ada5447efcee4da6192798a3b6799884c Mon Sep 17 00:00:00 2001 From: "Lott, Christopher (cl778h)" Date: Mon, 6 Apr 2020 20:31:32 -0400 Subject: [PATCH] Fix minor typos in RMR man pages Remove some spaces within invocations of &bold() and other formatting macros to placate the RST/Sphinx formatter. Remove tab characters entirely, which cleans up code examples. Change text "NULL pointer" to "nil pointer". Signed-off-by: Lott, Christopher (cl778h) Change-Id: Ic9ab6304831c0b1db21f62159da4f02f0442bb98 --- doc/src/man/README | 10 +- doc/src/man/env_var_list.im | 278 +++++++++++----------- doc/src/man/retry.im | 43 ++-- doc/src/man/rmr.7.xfm | 18 +- doc/src/man/rmr_alloc_msg.3.xfm | 18 +- doc/src/man/rmr_bytes2meid.3.xfm | 22 +- doc/src/man/rmr_bytes2payload.3.xfm | 18 +- doc/src/man/rmr_bytes2xact.3.xfm | 22 +- doc/src/man/rmr_call.3.xfm | 66 +++--- doc/src/man/rmr_close.3.xfm | 18 +- doc/src/man/rmr_free_msg.3.xfm | 24 +- doc/src/man/rmr_get_meid.3.xfm | 26 +- doc/src/man/rmr_get_rcvfd.3.xfm | 44 ++-- doc/src/man/rmr_get_src.3.xfm | 18 +- doc/src/man/rmr_get_srcip.3.xfm | 20 +- doc/src/man/rmr_get_trace.3.xfm | 20 +- doc/src/man/rmr_get_trlen.3.xfm | 18 +- doc/src/man/rmr_get_xact.3.xfm | 26 +- doc/src/man/rmr_init.3.xfm | 76 +++--- doc/src/man/rmr_init_trace.3.xfm | 30 +-- doc/src/man/rmr_mt_call.3.xfm | 88 ++++--- doc/src/man/rmr_mt_rcv.3.xfm | 66 +++--- doc/src/man/rmr_payload_size.3.xfm | 18 +- doc/src/man/rmr_rcv_msg.3.xfm | 34 +-- doc/src/man/rmr_ready.3.xfm | 18 +- doc/src/man/rmr_realloc_payload.3.xfm | 22 +- doc/src/man/rmr_rts_msg.3.xfm | 22 +- doc/src/man/rmr_send_msg.3.xfm | 53 ++--- doc/src/man/rmr_set_fack.3.xfm | 22 +- doc/src/man/rmr_set_stimeout.3.xfm | 20 +- doc/src/man/rmr_set_trace.3.xfm | 20 +- doc/src/man/rmr_set_vlevel.3.xfm | 87 ++++--- doc/src/man/rmr_str2meid.3.xfm | 26 +- doc/src/man/rmr_str2xact.3.xfm | 26 +- doc/src/man/rmr_support.3.xfm | 42 ++-- doc/src/man/rmr_torcv_msg.3.xfm | 42 ++-- doc/src/man/rmr_trace_ref.3.xfm | 22 +- doc/src/man/rmr_tralloc_msg.3.xfm | 50 ++-- doc/src/man/rmr_wh_call.3.xfm | 46 ++-- doc/src/man/rmr_wh_close.3.xfm | 24 +- doc/src/man/rmr_wh_open.3.xfm | 40 ++-- doc/src/man/rmr_wh_send_msg.3.xfm | 52 ++-- doc/src/man/rmr_wh_state.3.xfm | 40 ++-- doc/src/man/setup.im | 48 ++-- docs/config-deploy.rst | 37 ++- docs/overview.rst | 39 ++- docs/rel-notes.rst | 7 + docs/user-guide.rst | 431 ++++++++++++++++------------------ 48 files changed, 1104 insertions(+), 1153 deletions(-) mode change 100644 => 100755 docs/config-deploy.rst mode change 100644 => 100755 docs/overview.rst mode change 100644 => 100755 docs/rel-notes.rst mode change 100644 => 100755 docs/user-guide.rst diff --git a/doc/src/man/README b/doc/src/man/README index 8fc0277..be8a99b 100644 --- a/doc/src/man/README +++ b/doc/src/man/README @@ -1,11 +1,11 @@ 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' diff --git a/doc/src/man/env_var_list.im b/doc/src/man/env_var_list.im index 1399e00..e8b1c4e 100644 --- a/doc/src/man/env_var_list.im +++ b/doc/src/man/env_var_list.im @@ -1,8 +1,8 @@ .** 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. @@ -19,157 +19,157 @@ .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 diff --git a/doc/src/man/retry.im b/doc/src/man/retry.im index 15ce24d..7ffd34a 100644 --- a/doc/src/man/retry.im +++ b/doc/src/man/retry.im @@ -1,7 +1,7 @@ .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. @@ -18,35 +18,35 @@ .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. @@ -61,10 +61,9 @@ reported immediately to the user application. &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. diff --git a/doc/src/man/rmr.7.xfm b/doc/src/man/rmr.7.xfm index 70f55af..a82b42c 100644 --- a/doc/src/man/rmr.7.xfm +++ b/doc/src/man/rmr.7.xfm @@ -1,7 +1,7 @@ .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. @@ -17,10 +17,10 @@ ================================================================================== .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 @@ -30,12 +30,12 @@ &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. @@ -99,7 +99,7 @@ meid_map | end | 2 &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. diff --git a/doc/src/man/rmr_alloc_msg.3.xfm b/doc/src/man/rmr_alloc_msg.3.xfm index 44bcce0..d892915 100644 --- a/doc/src/man/rmr_alloc_msg.3.xfm +++ b/doc/src/man/rmr_alloc_msg.3.xfm @@ -1,7 +1,7 @@ .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. @@ -17,10 +17,10 @@ ================================================================================== .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 @@ -29,7 +29,7 @@ &line_len(6i) &h1(RMR Library Functions) &h2(NAME) - rmr_alloc_msg + rmr_alloc_msg &h2(SYNOPSIS ) &indent @@ -63,8 +63,8 @@ typedef struct { 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 diff --git a/doc/src/man/rmr_bytes2meid.3.xfm b/doc/src/man/rmr_bytes2meid.3.xfm index 7332c7b..cab519a 100644 --- a/doc/src/man/rmr_bytes2meid.3.xfm +++ b/doc/src/man/rmr_bytes2meid.3.xfm @@ -1,7 +1,7 @@ .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. @@ -18,20 +18,20 @@ .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 @@ -44,8 +44,8 @@ int rmr_bytes2meid( rmr_mbuf_t* mbuf, unsigned char* src, int len ) &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. @@ -65,7 +65,7 @@ of the following constants with the meaning listed below. &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) diff --git a/doc/src/man/rmr_bytes2payload.3.xfm b/doc/src/man/rmr_bytes2payload.3.xfm index 9deeef4..0f81756 100644 --- a/doc/src/man/rmr_bytes2payload.3.xfm +++ b/doc/src/man/rmr_bytes2payload.3.xfm @@ -1,7 +1,7 @@ .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. @@ -18,20 +18,20 @@ .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 @@ -48,7 +48,7 @@ This is a convenience function as some wrapper languages might not have the abil 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. diff --git a/doc/src/man/rmr_bytes2xact.3.xfm b/doc/src/man/rmr_bytes2xact.3.xfm index b7b79e5..5c145e7 100644 --- a/doc/src/man/rmr_bytes2xact.3.xfm +++ b/doc/src/man/rmr_bytes2xact.3.xfm @@ -1,7 +1,7 @@ .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. @@ -18,20 +18,20 @@ .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 @@ -44,8 +44,8 @@ int rmr_bytes2xact( rmr_mbuf_t* mbuf, unsigned char* src, int len ) &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. @@ -64,7 +64,7 @@ of the following constants with the meaning listed below. &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) diff --git a/doc/src/man/rmr_call.3.xfm b/doc/src/man/rmr_call.3.xfm index 592544f..dfd5e64 100644 --- a/doc/src/man/rmr_call.3.xfm +++ b/doc/src/man/rmr_call.3.xfm @@ -1,7 +1,7 @@ .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. @@ -19,20 +19,20 @@ .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 @@ -53,49 +53,49 @@ the response from the application that received the message. &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 ) @@ -105,13 +105,13 @@ overall call processing was not successful. &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 @@ -121,29 +121,29 @@ how the transaction ID must be set. 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; diff --git a/doc/src/man/rmr_close.3.xfm b/doc/src/man/rmr_close.3.xfm index 469c993..a8c97a9 100644 --- a/doc/src/man/rmr_close.3.xfm +++ b/doc/src/man/rmr_close.3.xfm @@ -1,7 +1,7 @@ .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. @@ -18,20 +18,20 @@ .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 @@ -46,7 +46,7 @@ void rmr_close( void* vctx ) &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. diff --git a/doc/src/man/rmr_free_msg.3.xfm b/doc/src/man/rmr_free_msg.3.xfm index 2f18b73..000856c 100644 --- a/doc/src/man/rmr_free_msg.3.xfm +++ b/doc/src/man/rmr_free_msg.3.xfm @@ -1,7 +1,7 @@ .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. @@ -18,20 +18,20 @@ .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 @@ -44,14 +44,14 @@ void rmr_free_msg( rmr_mbuf_t* mbuf ); &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. diff --git a/doc/src/man/rmr_get_meid.3.xfm b/doc/src/man/rmr_get_meid.3.xfm index 39fcafd..5745e04 100644 --- a/doc/src/man/rmr_get_meid.3.xfm +++ b/doc/src/man/rmr_get_meid.3.xfm @@ -1,7 +1,7 @@ .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. @@ -18,20 +18,20 @@ .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 @@ -45,19 +45,19 @@ char* rmr_get_meid( rmr_mbuf_t* mbuf, unsigned char* dest ) &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 ) @@ -65,8 +65,8 @@ the following with the indicated meaning. &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 diff --git a/doc/src/man/rmr_get_rcvfd.3.xfm b/doc/src/man/rmr_get_rcvfd.3.xfm index 9ed86b8..5ad6f06 100644 --- a/doc/src/man/rmr_get_rcvfd.3.xfm +++ b/doc/src/man/rmr_get_rcvfd.3.xfm @@ -1,7 +1,7 @@ .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. @@ -18,20 +18,20 @@ .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 @@ -48,22 +48,14 @@ The &cw(rmr_get_rcvfd) function returns a file descriptor which may be given to 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 @@ -93,25 +85,25 @@ int main() { 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.... } } diff --git a/doc/src/man/rmr_get_src.3.xfm b/doc/src/man/rmr_get_src.3.xfm index c46a2a5..31d82ff 100644 --- a/doc/src/man/rmr_get_src.3.xfm +++ b/doc/src/man/rmr_get_src.3.xfm @@ -1,7 +1,7 @@ .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. @@ -18,20 +18,20 @@ .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 @@ -61,7 +61,7 @@ On success, a pointer to the destination buffer is given as a convenience to the 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 ) diff --git a/doc/src/man/rmr_get_srcip.3.xfm b/doc/src/man/rmr_get_srcip.3.xfm index 9e3103b..ee55ebf 100644 --- a/doc/src/man/rmr_get_srcip.3.xfm +++ b/doc/src/man/rmr_get_srcip.3.xfm @@ -1,7 +1,7 @@ .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. @@ -18,20 +18,20 @@ .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 @@ -47,13 +47,13 @@ unsigned char* rmr_get_srcip( rmr_mbuf_t* mbuf, unsigned char* dest ) 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. diff --git a/doc/src/man/rmr_get_trace.3.xfm b/doc/src/man/rmr_get_trace.3.xfm index 69f48cf..6a3ee2c 100644 --- a/doc/src/man/rmr_get_trace.3.xfm +++ b/doc/src/man/rmr_get_trace.3.xfm @@ -1,7 +1,7 @@ .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. @@ -18,20 +18,20 @@ .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 @@ -45,12 +45,12 @@ int rmr_get_trace( rmr_mbuf_t* mbuf, unsigned char* dest, int size ) &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. diff --git a/doc/src/man/rmr_get_trlen.3.xfm b/doc/src/man/rmr_get_trlen.3.xfm index 507c8c6..618f097 100644 --- a/doc/src/man/rmr_get_trlen.3.xfm +++ b/doc/src/man/rmr_get_trlen.3.xfm @@ -1,7 +1,7 @@ .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. @@ -17,21 +17,21 @@ ================================================================================== .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 @@ -44,7 +44,7 @@ int rmr_get_trlen( rmr_mbuf_t* msg ); &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) diff --git a/doc/src/man/rmr_get_xact.3.xfm b/doc/src/man/rmr_get_xact.3.xfm index 6506614..01aa507 100644 --- a/doc/src/man/rmr_get_xact.3.xfm +++ b/doc/src/man/rmr_get_xact.3.xfm @@ -1,7 +1,7 @@ .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. @@ -18,20 +18,20 @@ .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 @@ -45,19 +45,19 @@ char* rmr_get_xact( rmr_mbuf_t* mbuf, unsigned char* dest ) &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 ) @@ -65,8 +65,8 @@ the following with the indicated meaning. &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 diff --git a/doc/src/man/rmr_init.3.xfm b/doc/src/man/rmr_init.3.xfm index a190ef7..99d28bc 100644 --- a/doc/src/man/rmr_init.3.xfm +++ b/doc/src/man/rmr_init.3.xfm @@ -1,7 +1,7 @@ .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. @@ -18,20 +18,20 @@ .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 @@ -46,83 +46,83 @@ void* rmr_init( char* proto_port, int max_msg_size, int flags ); &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. diff --git a/doc/src/man/rmr_init_trace.3.xfm b/doc/src/man/rmr_init_trace.3.xfm index 9168c68..c698c3a 100644 --- a/doc/src/man/rmr_init_trace.3.xfm +++ b/doc/src/man/rmr_init_trace.3.xfm @@ -1,7 +1,7 @@ .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. @@ -18,20 +18,20 @@ .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 @@ -44,28 +44,28 @@ void* rmr_init_trace( void* ctx ) &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 ) diff --git a/doc/src/man/rmr_mt_call.3.xfm b/doc/src/man/rmr_mt_call.3.xfm index 6ba797d..0acd455 100644 --- a/doc/src/man/rmr_mt_call.3.xfm +++ b/doc/src/man/rmr_mt_call.3.xfm @@ -1,7 +1,7 @@ .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. @@ -19,20 +19,20 @@ .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 @@ -51,44 +51,38 @@ The user application supplies a completed message buffer, as it would for 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 @@ -98,10 +92,10 @@ the state indicates the error encountered while attempting to send the message. &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 ) @@ -111,23 +105,23 @@ These values are reflected in the state field of the returned message. &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 ) @@ -141,8 +135,8 @@ overall call processing was not successful. &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) @@ -155,29 +149,29 @@ how the transaction ID must be set. 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; diff --git a/doc/src/man/rmr_mt_rcv.3.xfm b/doc/src/man/rmr_mt_rcv.3.xfm index 9584c49..25b418a 100644 --- a/doc/src/man/rmr_mt_rcv.3.xfm +++ b/doc/src/man/rmr_mt_rcv.3.xfm @@ -1,7 +1,7 @@ .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. @@ -17,20 +17,20 @@ ================================================================================== .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 @@ -43,8 +43,8 @@ rmr_mbuf_t* rmr_mt_rcv( void* vctx, rmr_mbuf_t* old_msg, int timeout ); &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 @@ -52,51 +52,45 @@ the next message received. &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 ) @@ -106,14 +100,14 @@ values: &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 diff --git a/doc/src/man/rmr_payload_size.3.xfm b/doc/src/man/rmr_payload_size.3.xfm index e4c0d97..e8723bf 100644 --- a/doc/src/man/rmr_payload_size.3.xfm +++ b/doc/src/man/rmr_payload_size.3.xfm @@ -1,7 +1,7 @@ .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. @@ -17,21 +17,21 @@ ================================================================================== .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 @@ -45,7 +45,7 @@ int rmr_payload_size( rmr_mbuf_t* msg ); &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) diff --git a/doc/src/man/rmr_rcv_msg.3.xfm b/doc/src/man/rmr_rcv_msg.3.xfm index c53dcf5..1287ff4 100644 --- a/doc/src/man/rmr_rcv_msg.3.xfm +++ b/doc/src/man/rmr_rcv_msg.3.xfm @@ -1,7 +1,7 @@ .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. @@ -17,20 +17,20 @@ ================================================================================== .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 @@ -44,27 +44,27 @@ rmr_mbuf_t* rmr_rcv_msg( void* vctx, rmr_mbuf_t* old_msg ); &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 @@ -74,7 +74,7 @@ error stats may be returned: &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 @@ -87,7 +87,7 @@ provide more information. The following is a list of possible values that 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 diff --git a/doc/src/man/rmr_ready.3.xfm b/doc/src/man/rmr_ready.3.xfm index 9f0a2cd..a846749 100644 --- a/doc/src/man/rmr_ready.3.xfm +++ b/doc/src/man/rmr_ready.3.xfm @@ -1,7 +1,7 @@ .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. @@ -17,20 +17,20 @@ ================================================================================== .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 @@ -48,7 +48,7 @@ The return value indicates the state of readiness. &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. diff --git a/doc/src/man/rmr_realloc_payload.3.xfm b/doc/src/man/rmr_realloc_payload.3.xfm index f745be3..28c6da4 100644 --- a/doc/src/man/rmr_realloc_payload.3.xfm +++ b/doc/src/man/rmr_realloc_payload.3.xfm @@ -1,7 +1,7 @@ .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. @@ -19,10 +19,10 @@ .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 @@ -32,7 +32,7 @@ &h1(RMR Library Functions) &h2(NAME) - rmr_realloc_payload + rmr_realloc_payload &h2(SYNOPSIS ) &indent @@ -70,7 +70,7 @@ uninitialised value (-1) for type and ID, and the length is set to 0. 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. @@ -92,7 +92,7 @@ These value of &ital(errno) will reflect the error condition if a nil pointer is &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 @@ -108,8 +108,8 @@ is larger than the message received. 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 diff --git a/doc/src/man/rmr_rts_msg.3.xfm b/doc/src/man/rmr_rts_msg.3.xfm index dfdbab1..f20065b 100644 --- a/doc/src/man/rmr_rts_msg.3.xfm +++ b/doc/src/man/rmr_rts_msg.3.xfm @@ -1,7 +1,7 @@ .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. @@ -17,10 +17,10 @@ ================================================================================== .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 @@ -30,7 +30,7 @@ &h1(RMR Library Functions) &h2(NAME) - rmr_rts_msg + rmr_rts_msg &h2(SYNOPSIS ) &indent @@ -57,7 +57,7 @@ take care not to write more bytes to the message payload than the allocated mess 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 @@ -71,12 +71,12 @@ The state in this buffer will reflect the overall send operation state and shoul &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. @@ -107,7 +107,7 @@ The following values may be assigned to &cw(errno) on failure. &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. diff --git a/doc/src/man/rmr_send_msg.3.xfm b/doc/src/man/rmr_send_msg.3.xfm index 50f4383..1d486ed 100644 --- a/doc/src/man/rmr_send_msg.3.xfm +++ b/doc/src/man/rmr_send_msg.3.xfm @@ -1,7 +1,7 @@ .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. @@ -17,10 +17,10 @@ ================================================================================== .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 @@ -30,7 +30,7 @@ &h1(RMR Library Functions) &h2(NAME) - rmr_send_msg + rmr_send_msg &h2(SYNOPSIS ) &indent @@ -71,7 +71,7 @@ The value of &ital(errno) may also be set to reflect a more detailed failure rea 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. @@ -91,11 +91,11 @@ buffer. &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. @@ -116,7 +116,7 @@ The following values may be assigned to &cw(errno) on failure. &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. @@ -151,26 +151,25 @@ eliminating alloc/free cycles. 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 diff --git a/doc/src/man/rmr_set_fack.3.xfm b/doc/src/man/rmr_set_fack.3.xfm index 61ebfc3..88dea3b 100644 --- a/doc/src/man/rmr_set_fack.3.xfm +++ b/doc/src/man/rmr_set_fack.3.xfm @@ -1,7 +1,7 @@ .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. @@ -17,20 +17,20 @@ ================================================================================== .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 @@ -44,9 +44,9 @@ void rmr_set_fack( void* vctx ); &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. diff --git a/doc/src/man/rmr_set_stimeout.3.xfm b/doc/src/man/rmr_set_stimeout.3.xfm index 4f5dd35..ce587c1 100644 --- a/doc/src/man/rmr_set_stimeout.3.xfm +++ b/doc/src/man/rmr_set_stimeout.3.xfm @@ -1,7 +1,7 @@ .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. @@ -17,14 +17,14 @@ ================================================================================== .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) @@ -81,9 +81,9 @@ The following is a simple example of how the &cw(rmr_set_stimeout) function is c &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 ) { diff --git a/doc/src/man/rmr_set_trace.3.xfm b/doc/src/man/rmr_set_trace.3.xfm index 67c53bf..11e16d9 100644 --- a/doc/src/man/rmr_set_trace.3.xfm +++ b/doc/src/man/rmr_set_trace.3.xfm @@ -1,7 +1,7 @@ .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. @@ -18,20 +18,20 @@ .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 @@ -44,8 +44,8 @@ int rmr_set_trace( rmr_mbuf_t* mbuf, unsigned char* data, int len ) &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. diff --git a/doc/src/man/rmr_set_vlevel.3.xfm b/doc/src/man/rmr_set_vlevel.3.xfm index 763cab1..2a64d82 100644 --- a/doc/src/man/rmr_set_vlevel.3.xfm +++ b/doc/src/man/rmr_set_vlevel.3.xfm @@ -1,7 +1,7 @@ .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. @@ -18,21 +18,20 @@ .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 @@ -46,56 +45,56 @@ void rmr_set_vlevel( int new_level ) &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. diff --git a/doc/src/man/rmr_str2meid.3.xfm b/doc/src/man/rmr_str2meid.3.xfm index c646c28..d4ece5f 100644 --- a/doc/src/man/rmr_str2meid.3.xfm +++ b/doc/src/man/rmr_str2meid.3.xfm @@ -1,7 +1,7 @@ .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. @@ -18,20 +18,20 @@ .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 @@ -44,15 +44,15 @@ int rmr_str2meid( rmr_mbuf_t* mbuf, unsigned char* src, int len ) &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) @@ -65,7 +65,7 @@ If the return value is not RMR_OK, then it will be set to one of the values belo &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) diff --git a/doc/src/man/rmr_str2xact.3.xfm b/doc/src/man/rmr_str2xact.3.xfm index e27c5f6..0c7c252 100644 --- a/doc/src/man/rmr_str2xact.3.xfm +++ b/doc/src/man/rmr_str2xact.3.xfm @@ -1,7 +1,7 @@ .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. @@ -18,20 +18,20 @@ .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 @@ -44,16 +44,16 @@ int rmr_str2xact( rmr_mbuf_t* mbuf, unsigned char* src, int len ) &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) @@ -64,7 +64,7 @@ If the return value is not RMR_OK, then it will be set to one of the values belo &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) diff --git a/doc/src/man/rmr_support.3.xfm b/doc/src/man/rmr_support.3.xfm index ca73298..f9b3618 100644 --- a/doc/src/man/rmr_support.3.xfm +++ b/doc/src/man/rmr_support.3.xfm @@ -1,7 +1,7 @@ .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. @@ -17,25 +17,25 @@ ================================================================================== .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 @@ -61,7 +61,7 @@ as some (e.g. route table generators) might need and/or want to make use of them 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 @@ -73,7 +73,7 @@ before checking. &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. @@ -87,18 +87,18 @@ The &cw(rmr_ring_free) function accepts a pointer to a ring context and frees th &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 @@ -117,7 +117,7 @@ The &cw(rmr_ring_insert) function returns 1 if the data was successfully inserte 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) diff --git a/doc/src/man/rmr_torcv_msg.3.xfm b/doc/src/man/rmr_torcv_msg.3.xfm index d160f53..89cbb57 100644 --- a/doc/src/man/rmr_torcv_msg.3.xfm +++ b/doc/src/man/rmr_torcv_msg.3.xfm @@ -1,7 +1,7 @@ .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. @@ -17,20 +17,20 @@ ================================================================================== .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 @@ -43,27 +43,27 @@ rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to ); &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) @@ -74,17 +74,17 @@ The &ital(state) field in the message buffer will be one of the following: &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 diff --git a/doc/src/man/rmr_trace_ref.3.xfm b/doc/src/man/rmr_trace_ref.3.xfm index 8b0fb9b..9768d22 100644 --- a/doc/src/man/rmr_trace_ref.3.xfm +++ b/doc/src/man/rmr_trace_ref.3.xfm @@ -1,7 +1,7 @@ .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. @@ -18,20 +18,20 @@ .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 @@ -44,12 +44,12 @@ int rmr_trace_ref( rmr_mbuf_t* mbuf, int* sizeptr ) &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. diff --git a/doc/src/man/rmr_tralloc_msg.3.xfm b/doc/src/man/rmr_tralloc_msg.3.xfm index da7ac6b..cd0d9c5 100644 --- a/doc/src/man/rmr_tralloc_msg.3.xfm +++ b/doc/src/man/rmr_tralloc_msg.3.xfm @@ -1,7 +1,7 @@ .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. @@ -17,41 +17,41 @@ ================================================================================== .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_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. @@ -60,7 +60,7 @@ the &ital(rmr_init) function. &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. @@ -77,11 +77,11 @@ typedef struct { &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. @@ -90,30 +90,30 @@ 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 diff --git a/doc/src/man/rmr_wh_call.3.xfm b/doc/src/man/rmr_wh_call.3.xfm index 7e1b935..cc3a82b 100644 --- a/doc/src/man/rmr_wh_call.3.xfm +++ b/doc/src/man/rmr_wh_call.3.xfm @@ -1,7 +1,7 @@ .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. @@ -17,20 +17,20 @@ ================================================================================== .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 @@ -43,7 +43,7 @@ rmr_mbuf_t* rmr_wh_call( void* vctx, rmr_whid_t whid, rmr_mbuf_t* msg, int call_ &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. @@ -52,23 +52,23 @@ use &cw(rmr_rts_msg()) to send their response. &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.) @@ -82,7 +82,7 @@ received within the timeout (max_wait) period of time. &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 ) @@ -100,7 +100,7 @@ Some error checking is omitted for clarity. &space &ex_start -#include // system headers omitted for clarity +#include // system headers omitted for clarity int main() { rmr_whid_t whid = -1; // wormhole id for sending @@ -111,11 +111,11 @@ int main() { 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 ); } @@ -124,12 +124,12 @@ int main() { 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" ); } diff --git a/doc/src/man/rmr_wh_close.3.xfm b/doc/src/man/rmr_wh_close.3.xfm index fbd94cf..0fd388a 100644 --- a/doc/src/man/rmr_wh_close.3.xfm +++ b/doc/src/man/rmr_wh_close.3.xfm @@ -1,7 +1,7 @@ .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. @@ -18,20 +18,20 @@ .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 @@ -45,13 +45,13 @@ void rmr_close( void* vctx, rmr_whid_t whid ) &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. diff --git a/doc/src/man/rmr_wh_open.3.xfm b/doc/src/man/rmr_wh_open.3.xfm index 704af91..738090a 100644 --- a/doc/src/man/rmr_wh_open.3.xfm +++ b/doc/src/man/rmr_wh_open.3.xfm @@ -1,7 +1,7 @@ .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. @@ -18,20 +18,20 @@ .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 @@ -51,14 +51,14 @@ by the user application (via this function), and that the ID returned by &cw(rmr 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 @@ -66,10 +66,10 @@ buffering and retries differently. &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) @@ -78,8 +78,8 @@ error message of a system call is propagated up, and thus this list might be inc &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 @@ -90,8 +90,8 @@ error message of a system call is propagated up, and thus this list might be inc 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 diff --git a/doc/src/man/rmr_wh_send_msg.3.xfm b/doc/src/man/rmr_wh_send_msg.3.xfm index 6dcdbe8..169c25d 100644 --- a/doc/src/man/rmr_wh_send_msg.3.xfm +++ b/doc/src/man/rmr_wh_send_msg.3.xfm @@ -1,7 +1,7 @@ .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. @@ -17,20 +17,20 @@ ================================================================================== .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 @@ -42,21 +42,21 @@ rmr_mbuf_t* rmr_wh_send_msg( void* vctx, rmr_whid_t id, rmr_mbuf_t* msg ); &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 @@ -65,18 +65,18 @@ The state in this buffer will reflect the overall send operation state and shoul &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 ) @@ -101,7 +101,7 @@ The following values may be assigned to &cw(errno) on failure. &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. @@ -133,7 +133,7 @@ Some error checking is omitted for clarity. &space &ex_start -#include // system headers omitted for clarity +#include // system headers omitted for clarity int main() { rmr_whid_t whid = -1; // wormhole id for sending @@ -144,11 +144,11 @@ int main() { 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 ); } @@ -157,14 +157,14 @@ int main() { 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 diff --git a/doc/src/man/rmr_wh_state.3.xfm b/doc/src/man/rmr_wh_state.3.xfm index ea4c960..70780c6 100644 --- a/doc/src/man/rmr_wh_state.3.xfm +++ b/doc/src/man/rmr_wh_state.3.xfm @@ -1,7 +1,7 @@ .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. @@ -18,20 +18,20 @@ .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 @@ -45,7 +45,7 @@ int rmr_wh_state( void* vctx, rmr_whid_t whid ) &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). @@ -59,25 +59,25 @@ The following values are potential return values. &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 diff --git a/doc/src/man/setup.im b/doc/src/man/setup.im index fbd95fe..3d36416 100644 --- a/doc/src/man/setup.im +++ b/doc/src/man/setup.im @@ -1,7 +1,7 @@ .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. @@ -18,39 +18,39 @@ .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 diff --git a/docs/config-deploy.rst b/docs/config-deploy.rst old mode 100644 new mode 100755 index a7b77b8..58154e1 --- a/docs/config-deploy.rst +++ b/docs/config-deploy.rst @@ -37,23 +37,23 @@ development package for more details. 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 @@ -66,17 +66,16 @@ 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 @@ -168,8 +167,8 @@ RMR_RTG_ISRAW **Deprecated.** Should be set to 1 if the route table generator is sending "plain" messages (not using RMR to - send messages, 0 if the rtg is using RMR to send. The - default is 1 as we don't expect the rtg to use RMR. + 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 @@ -189,7 +188,7 @@ RMR_SEED_RT 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 diff --git a/docs/overview.rst b/docs/overview.rst old mode 100644 new mode 100755 index 8ca7f86..8168b9f --- a/docs/overview.rst +++ b/docs/overview.rst @@ -25,7 +25,7 @@ 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) 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. @@ -185,23 +185,23 @@ if undefined. 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 @@ -214,17 +214,16 @@ 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 @@ -316,8 +315,8 @@ RMR_RTG_ISRAW **Deprecated.** Should be set to 1 if the route table generator is sending "plain" messages (not using RMR to - send messages, 0 if the rtg is using RMR to send. The - default is 1 as we don't expect the rtg to use RMR. + 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 @@ -337,7 +336,7 @@ RMR_SEED_RT 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 diff --git a/docs/rel-notes.rst b/docs/rel-notes.rst old mode 100644 new mode 100755 index bcbd826..f5b40d7 --- a/docs/rel-notes.rst +++ b/docs/rel-notes.rst @@ -28,6 +28,13 @@ Core RMR Changes -------------------------------------------------------------------------------------------- +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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/user-guide.rst b/docs/user-guide.rst old mode 100644 new mode 100755 index e4cb20c..cc84a2c --- a/docs/user-guide.rst +++ b/docs/user-guide.rst @@ -69,8 +69,8 @@ is described in rmr.h, and is illustrated below. int len; unsigned char* payload; unsigned char* xaction; - uint sub_id; - uint tp_state; + int sub_id; + int tp_state; } rmr_mbuf_t; @@ -407,7 +407,7 @@ that received the message. 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -416,7 +416,7 @@ The rmr_call function implements a timeout failsafe to 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 @@ -433,7 +433,7 @@ parameter which the user application may set. 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: @@ -445,7 +445,7 @@ until one of three conditions occurs: 2. - The underlying transport reports a * hard * failure + The underlying transport reports a *hard* failure 3. @@ -453,12 +453,12 @@ until one of three conditions occurs: 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. @@ -476,14 +476,13 @@ underlying mechanisms (software or hardware) will be reported 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 -------------------------------------------------------------------------------------------- @@ -538,17 +537,18 @@ EINVAL 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. :: @@ -557,26 +557,24 @@ 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; @@ -599,7 +597,7 @@ rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3) NAME -------------------------------------------------------------------------------------------- -rmr_wh_open +rmr_close SYNOPSIS -------------------------------------------------------------------------------------------- @@ -771,19 +769,11 @@ has been received. 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 -------------------------------------------------------------------------------------------- @@ -820,25 +810,21 @@ function. Error checking has been omitted for clarity. 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.... } } @@ -1257,32 +1243,32 @@ an additional process is necessary the user application must 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 @@ -1295,17 +1281,16 @@ 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 @@ -1397,8 +1382,8 @@ RMR_RTG_ISRAW **Deprecated.** Should be set to 1 if the route table generator is sending "plain" messages (not using RMR to - send messages, 0 if the rtg is using RMR to send. The - default is 1 as we don't expect the rtg to use RMR. + 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 @@ -1418,7 +1403,7 @@ RMR_SEED_RT 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 @@ -1599,24 +1584,19 @@ are queued on a *normal* receive queue and will be delivered 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 @@ -1625,7 +1605,7 @@ not adjust the transaction ID. 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: @@ -1637,7 +1617,7 @@ until one of three conditions occurs: 2. - The underlying transport reports a * hard * failure + The underlying transport reports a *hard* failure 3. @@ -1645,12 +1625,12 @@ until one of three conditions occurs: 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. @@ -1668,14 +1648,13 @@ underlying mechanisms (software or hardware) will be reported 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 -------------------------------------------------------------------------------------------- @@ -1769,26 +1748,25 @@ function, and illustrates how the transaction ID must be set. 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; @@ -1845,17 +1823,17 @@ buffer is available to supply, the receive function will 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 @@ -1865,11 +1843,6 @@ cost of a second call that results). Similarly, the 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 -------------------------------------------------------------------------------------------- @@ -2103,9 +2076,9 @@ payload), or a NULL pointer in the case of an extreme error. 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: @@ -2294,7 +2267,7 @@ The rmr_realloc_payload function returns a pointer to the 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. @@ -2341,8 +2314,8 @@ received. 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 + } } @@ -2385,7 +2358,7 @@ as rmr_send_msg. 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: @@ -2397,7 +2370,7 @@ until one of three conditions occurs: 2. - The underlying transport reports a * hard * failure + The underlying transport reports a *hard* failure 3. @@ -2405,12 +2378,12 @@ until one of three conditions occurs: 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. @@ -2428,14 +2401,13 @@ underlying mechanisms (software or hardware) will be reported 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 -------------------------------------------------------------------------------------------- @@ -2446,7 +2418,7 @@ the message payload than the allocated message 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 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 @@ -2464,7 +2436,7 @@ state in this buffer will reflect the overall send operation 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. @@ -2623,7 +2595,7 @@ library.) 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: @@ -2635,7 +2607,7 @@ until one of three conditions occurs: 2. - The underlying transport reports a * hard * failure + The underlying transport reports a *hard* failure 3. @@ -2643,12 +2615,12 @@ until one of three conditions occurs: 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. @@ -2666,14 +2638,13 @@ underlying mechanisms (software or hardware) will be reported 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 -------------------------------------------------------------------------------------------- @@ -2827,23 +2798,23 @@ cycles. 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; @@ -2877,7 +2848,7 @@ DESCRIPTION The rmr_set_fack function enables *fast TCP acknowledgements* if the underlying transport library supports it. This might -be useful for applications which must send messages as a +be useful for applications which must send messages at a maximum rate. RETURN VALUE @@ -2966,9 +2937,9 @@ function is called. :: #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 @@ -3035,7 +3006,7 @@ rmr_wh_open(3), rmr_wh_send_msg(3) NAME -------------------------------------------------------------------------------------------- -rmr_set_trace +rmr_set_vlevel SYNOPSIS -------------------------------------------------------------------------------------------- @@ -3100,10 +3071,10 @@ RMR_VL_DEBUG 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 @@ -3542,10 +3513,10 @@ SYNOPSIS 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 -------------------------------------------------------------------------------------------- @@ -3581,7 +3552,7 @@ SYNOPSIS :: #include - 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 ); @@ -3589,14 +3560,14 @@ SYNOPSIS 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 @@ -3675,9 +3646,9 @@ xaction 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 @@ -3736,8 +3707,8 @@ process **must** use rmr_rts_msg() to send their response. 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 @@ -3752,7 +3723,7 @@ Go's goroutines) is possible. 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: @@ -3764,7 +3735,7 @@ until one of three conditions occurs: 2. - The underlying transport reports a * hard * failure + The underlying transport reports a *hard* failure 3. @@ -3772,12 +3743,12 @@ until one of three conditions occurs: 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. @@ -3795,14 +3766,13 @@ underlying mechanisms (software or hardware) will be reported 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 -------------------------------------------------------------------------------------------- @@ -3859,7 +3829,7 @@ clarity. :: - #include .// system headers omitted for clarity + #include // system headers omitted for clarity int main() { rmr_whid_t whid = -1; // wormhole id for sending void* mrc; //msg router context @@ -3868,22 +3838,22 @@ clarity. 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" ); } @@ -3909,7 +3879,7 @@ rmr_wh_state(3) NAME -------------------------------------------------------------------------------------------- -rmr_wh_open +rmr_wh_close SYNOPSIS -------------------------------------------------------------------------------------------- @@ -3930,10 +3900,10 @@ the wormhole id passed in. Future calls to rmr_wh_send_msg 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 -------------------------------------------------------------------------------------------- @@ -4011,7 +3981,7 @@ EINVAL 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). @@ -4030,8 +4000,8 @@ EXAMPLE 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 ) ); } @@ -4072,20 +4042,20 @@ the user application and attempts to send it using the 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: @@ -4097,7 +4067,7 @@ until one of three conditions occurs: 2. - The underlying transport reports a * hard * failure + The underlying transport reports a *hard* failure 3. @@ -4105,12 +4075,12 @@ until one of three conditions occurs: 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. @@ -4128,14 +4098,13 @@ underlying mechanisms (software or hardware) will be reported 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 -------------------------------------------------------------------------------------------- @@ -4268,7 +4237,7 @@ clarity. :: - #include .// system headers omitted for clarity + #include // system headers omitted for clarity int main() { rmr_whid_t whid = -1; // wormhole id for sending void* mrc; //msg router context @@ -4277,23 +4246,23 @@ clarity. 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 ); } } -- 2.16.6