From ece5bbead6922f59982227c9941babdd6054cf17 Mon Sep 17 00:00:00 2001 From: "E. Scott Daniels" Date: Tue, 21 Jul 2020 13:39:18 -0400 Subject: [PATCH] Fix potential pointer use err in SI95 In SIconnect it was possible for a freed struct to be used if the session didn't connect. This change also picks up whitespace changes to the docs. Issue-ID: RIC-626 Signed-off-by: E. Scott Daniels Change-Id: Ie23f4925c6a29b301f0143e938c11f57f0ed5631 --- CHANGES_CORE.txt | 3 + CMakeLists.txt | 2 +- doc/src/library/Makefile | 2 +- doc/src/library/setup.im | 5 - doc/src/rtd/Makefile | 2 +- doc/src/rtd/publish_man.sh | 2 +- docs/config-deploy.rst | 424 ++++---- docs/developer-guide.rst | 184 ++-- docs/msg_types.rst | 664 ++++++------- docs/rel-notes.rst | 8 + docs/rmr.7.rst | 746 +++++++-------- docs/rmr_alloc_msg.3.rst | 310 +++--- docs/rmr_bytes2meid.3.rst | 114 +-- docs/rmr_bytes2payload.3.rst | 72 +- docs/rmr_bytes2xact.3.rst | 110 +-- docs/rmr_call.3.rst | 380 ++++---- docs/rmr_close.3.rst | 62 +- docs/rmr_free_msg.3.rst | 68 +- docs/rmr_get_const.3.rst | 86 +- docs/rmr_get_meid.3.rst | 114 +-- docs/rmr_get_rcvfd.3.rst | 190 ++-- docs/rmr_get_src.3.rst | 114 +-- docs/rmr_get_srcip.3.rst | 120 +-- docs/rmr_get_trace.3.rst | 74 +- docs/rmr_get_trlen.3.rst | 82 +- docs/rmr_get_xact.3.rst | 114 +-- docs/rmr_init.3.rst | 664 ++++++------- docs/rmr_init_trace.3.rst | 98 +- docs/rmr_mt_call.3.rst | 430 ++++----- docs/rmr_mt_rcv.3.rst | 358 +++---- docs/rmr_payload_size.3.rst | 78 +- docs/rmr_rcv_msg.3.rst | 250 ++--- docs/rmr_ready.3.rst | 64 +- docs/rmr_realloc_payload.3.rst | 188 ++-- docs/rmr_rts_msg.3.rst | 376 ++++---- docs/rmr_send_msg.3.rst | 462 ++++----- docs/rmr_set_fack.3.rst | 54 +- docs/rmr_set_stimeout.3.rst | 142 +-- docs/rmr_set_trace.3.rst | 74 +- docs/rmr_set_vlevel.3.rst | 184 ++-- docs/rmr_str2meid.3.rst | 108 +-- docs/rmr_str2xact.3.rst | 110 +-- docs/rmr_support.3.rst | 212 ++-- docs/rmr_torcv_msg.3.rst | 256 ++--- docs/rmr_trace_ref.3.rst | 72 +- docs/rmr_tralloc_msg.3.rst | 260 ++--- docs/rmr_wh_call.3.rst | 352 +++---- docs/rmr_wh_close.3.rst | 68 +- docs/rmr_wh_open.3.rst | 180 ++-- docs/rmr_wh_send_msg.3.rst | 464 ++++----- docs/rmr_wh_state.3.rst | 116 +-- docs/rt_tables.rst | 1094 ++++++++++----------- docs/user-guide.rst | 2018 +++++++++++++++++++-------------------- src/rmr/si/src/si95/siconnect.c | 4 +- 54 files changed, 6397 insertions(+), 6391 deletions(-) diff --git a/CHANGES_CORE.txt b/CHANGES_CORE.txt index 1acf21c..27e05cd 100644 --- a/CHANGES_CORE.txt +++ b/CHANGES_CORE.txt @@ -5,6 +5,9 @@ # API and build change and fix summaries. Doc correctsions # and/or changes are not mentioned here; see the commit messages. +2020 July 21; Version 4.2.4 + Fix bug in SI95 -- possible use of pointer after free (RIC-626). + 2020 July 9; version 4.1.3 Allow RTS messages to be sent before the arrival of the initial route table. Calls to RTS (heart beat responses) prior to the diff --git a/CMakeLists.txt b/CMakeLists.txt index ed345f4..65226cf 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -41,7 +41,7 @@ cmake_minimum_required( VERSION 3.5 ) set( major_version "4" ) # should be automatically populated from git tag later, but until CI process sets a tag we use this set( minor_version "1" ) -set( patch_level "3" ) +set( patch_level "4" ) set( install_root "${CMAKE_INSTALL_PREFIX}" ) set( install_inc "include/rmr" ) diff --git a/doc/src/library/Makefile b/doc/src/library/Makefile index 7108614..60404c9 100644 --- a/doc/src/library/Makefile +++ b/doc/src/library/Makefile @@ -33,7 +33,7 @@ P2 = $(XP) XFM_PASS=2 %.rst: %.xfm $(P1) OUTPUT_TYPE=rst tfm $< /dev/null - $(P2) OUTPUT_TYPE=rst tfm $< stdout | sed 's/^ //' >$@ + $(P2) OUTPUT_TYPE=rst tfm $< stdout | sed 's/^ //; s/ *$$//' >$@ %.txt: %.xfm $(P1) OUTPUT_TYPE=txt tfm $< /dev/null diff --git a/doc/src/library/setup.im b/doc/src/library/setup.im index 9ad6ece..3a96aca 100644 --- a/doc/src/library/setup.im +++ b/doc/src/library/setup.im @@ -158,9 +158,4 @@ .pn on noline center f=%d 0 .fi -.** work around bug until change made (RouxWare issue #4) -.if tfm - .in 7p -.fi - .dv _setup_im diff --git a/doc/src/rtd/Makefile b/doc/src/rtd/Makefile index dc8f4be..6ef1743 100644 --- a/doc/src/rtd/Makefile +++ b/doc/src/rtd/Makefile @@ -23,7 +23,7 @@ %.rst:: %.xfm - OUTPUT_TYPE=rst tfm $< | sed 's/^ //' >$@ + OUTPUT_TYPE=rst tfm $< | sed 's/^ //; s/ *$$//' >$@ %.ps:: %.xfm OUTPUT_TYPE=ps pfm $< $@ diff --git a/doc/src/rtd/publish_man.sh b/doc/src/rtd/publish_man.sh index 1bbfc7f..1563f62 100755 --- a/doc/src/rtd/publish_man.sh +++ b/doc/src/rtd/publish_man.sh @@ -39,7 +39,7 @@ do out=stuff/${x%.*}.rst target=${sdir}/${out##*/} - INPUT_FILE=${x%%.*} GEN_TITLE=1 LIB=".." OUTPUT_TYPE=rst tfm ../man/$x stdout 2>/dev/null | sed 's/^ //' >$out + INPUT_FILE=${x%%.*} GEN_TITLE=1 LIB=".." OUTPUT_TYPE=rst tfm ../man/$x stdout 2>/dev/null | sed 's/^ //; s/ *$//' >$out new_m5=$( md5sum $out | sed 's/ .*//' ) if [[ ! -f $target || $new_m5 != $( md5sum $target | sed 's/ .*//' ) ]] then diff --git a/docs/config-deploy.rst b/docs/config-deploy.rst index 58fff4b..16e64f5 100644 --- a/docs/config-deploy.rst +++ b/docs/config-deploy.rst @@ -1,222 +1,222 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Configuration and Deployment -============================================================================================ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Configuration and Deployment +============================================================================================ OVERVIEW ======== -The RIC Message Router (RMR) is a library for peer-to-peer -communication. Applications use the library to send and -receive messages where the message routing and endpoint -selection is based on the message type rather than DNS host -name-IP port combinations. - -This document contains information regarding the -configuration of RMR when it is embedded by a *user -application* . RMR itself is a library, not a deployable -entity. +The RIC Message Router (RMR) is a library for peer-to-peer +communication. Applications use the library to send and +receive messages where the message routing and endpoint +selection is based on the message type rather than DNS host +name-IP port combinations. + +This document contains information regarding the +configuration of RMR when it is embedded by a *user +application* . RMR itself is a library, not a deployable +entity. Configuration ------------- -Many aspects of RMR behavior are controlled via environment -variables. These values are read when a user application -invokes the RMR initialization function. This allows these -variables to be set before the application is started as a -function of the true environment, or set by the application -as a means for the application to influence RMR's behaviour. -The following is a list of environment variables which RMR -recognizes. Also see the main RMR manual page in the -development package for more details. - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **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 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. - - * - **RMR_CTL_PORT** - - - This variable defines the port that RMR should open for - communications with Route Manager, and other RMR control - applications. If not defined, the port 4561 is assumed. - - Previously, the ``RMR_RTG_SVC`` (route table generator - service port) was used to define this port. However, a future - version of Route Manager will require RMR to connect and - request tables, thus that variable is now used to supply the - Route Manager's well-known address and port. - - 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 manager is - used (routemgr:4561). - - When ``RMR_CTL_PORT`` is **undefined:** RMR assumes that - Route Manager will connect and push table updates, thus the - default listen port (4561) is used. - - To avoid any possible misinterpretation and/or incorrect - assumptions on the part of RMR, it is recommended that both - the ``RMR_CTL_PORT`` and ``RMR_RTG_SVC`` be defined. In the - case where both variables are defined, RMR will behave - exactly as is communicated with the variable's values. - - * - **RMR_RTG_SVC** - - - The value of this variable depends on the Route Manager in - use. - - When the Route Manager is expecting to connect to an xAPP and - push route tables, this variable must indicate the - ``port`` which RMR should use to listen for these - connections. - - When the Route Manager is expecting RMR to connect and - request a table update during initialisation, the variable - should be the ``host`` of the Route Manager process. - - The ``RMR_CTL_PORT`` variable (added with the support of - sending table update requests to Route manager), controls the - behaviour if this variable is not set. See the description of - that variable for details. - - * - **RMR_HR_LOG** - - - By default RMR writes messages to standard error (incorrectly - referred to as log messages) in human readable format. If - this environment variable is set to 0, the format of standard - error messages might be written in some format not easily - read by humans. If missing, a value of 1 is assumed. - - * - **RMR_LOG_VLEVEL** - - - This is a numeric value which corresponds to the verbosity - level used to limit messages written to standard error. The - lower the number the less chatty RMR functions are during - execution. The following is the current relationship between - the value set on this variable and the messages written: - - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **0** - - - Off; no messages of any sort are written. - - * - **1** - - - Only critical messages are written (default if this variable - does not exist) - - * - **2** - - - Errors and all messages written with a lower value. - - * - **3** - - - Warnings and all messages written with a lower value. - - * - **4** - - - Informational and all messages written with a lower value. - - * - **5** - - - Debugging mode -- all messages written, however this requires - RMR to have been compiled with debugging support enabled. - - - - * - **RMR_RTG_ISRAW** - - - **Deprecated.** Should be set to 1 if the route table - generator is sending "plain" messages (not using RMR to send - messages), 0 if the RTG is using RMR to send. The default is - 1 as we don't expect the RTG to use RMR. - - This variable is only recognised when using the NNG transport - library as it is not possible to support NNG "raw" - communications with other transport libraries. It is also - necessary to match the value of this variable with the - capabilities of the Route Manager; at some point in the - future RMR will assume that all Route Manager messages will - arrive via an RMR connection and will ignore this variable. - - * - **RMR_SEED_RT** - - - This is used to supply a static route table which can be used - for debugging, testing, or if no route table generator - process is being used to supply the route table. If not - defined, no static table is used and RMR will not report - *ready* until a table is received. The static route table may - contain both the route table (between newrt start and end - records), and the MEID map (between meid_map start and end - records). - - * - **RMR_SRC_ID** - - - This is either the name or IP address which is placed into - outbound messages as the message source. This will used when - an RMR based application uses the rmr_rts_msg() function to - return a response to the sender. If not supplied RMR will use - the hostname which in some container environments might not - be routable. - - The value of this variable is also used for Route Manager - messages which are sent via an RMR connection. - - * - **RMR_VCTL_FILE** - - - This supplies the name of a verbosity control file. The core - RMR functions do not produce messages unless there is a - critical failure. However, the route table collection thread, - not a part of the main message processing component, can - write additional messages to standard error. If this variable - is set, RMR will extract the verbosity level for these - messages (0 is silent) from the first line of the file. - Changes to the file are detected and thus the level can be - changed dynamically, however RMR will only suss out this - variable during initialisation, so it is impossible to enable - verbosity after startup. - - * - **RMR_WARNINGS** - - - If set to 1, RMR will write some warnings which are - non-performance impacting. If the variable is not defined, or - set to 0, RMR will not write these additional warnings. - - +Many aspects of RMR behavior are controlled via environment +variables. These values are read when a user application +invokes the RMR initialization function. This allows these +variables to be set before the application is started as a +function of the true environment, or set by the application +as a means for the application to influence RMR's behaviour. +The following is a list of environment variables which RMR +recognizes. Also see the main RMR manual page in the +development package for more details. + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **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 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. + + * - **RMR_CTL_PORT** + - + This variable defines the port that RMR should open for + communications with Route Manager, and other RMR control + applications. If not defined, the port 4561 is assumed. + + Previously, the ``RMR_RTG_SVC`` (route table generator + service port) was used to define this port. However, a future + version of Route Manager will require RMR to connect and + request tables, thus that variable is now used to supply the + Route Manager's well-known address and port. + + 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 manager is + used (routemgr:4561). + + When ``RMR_CTL_PORT`` is **undefined:** RMR assumes that + Route Manager will connect and push table updates, thus the + default listen port (4561) is used. + + To avoid any possible misinterpretation and/or incorrect + assumptions on the part of RMR, it is recommended that both + the ``RMR_CTL_PORT`` and ``RMR_RTG_SVC`` be defined. In the + case where both variables are defined, RMR will behave + exactly as is communicated with the variable's values. + + * - **RMR_RTG_SVC** + - + The value of this variable depends on the Route Manager in + use. + + When the Route Manager is expecting to connect to an xAPP and + push route tables, this variable must indicate the + ``port`` which RMR should use to listen for these + connections. + + When the Route Manager is expecting RMR to connect and + request a table update during initialisation, the variable + should be the ``host`` of the Route Manager process. + + The ``RMR_CTL_PORT`` variable (added with the support of + sending table update requests to Route manager), controls the + behaviour if this variable is not set. See the description of + that variable for details. + + * - **RMR_HR_LOG** + - + By default RMR writes messages to standard error (incorrectly + referred to as log messages) in human readable format. If + this environment variable is set to 0, the format of standard + error messages might be written in some format not easily + read by humans. If missing, a value of 1 is assumed. + + * - **RMR_LOG_VLEVEL** + - + This is a numeric value which corresponds to the verbosity + level used to limit messages written to standard error. The + lower the number the less chatty RMR functions are during + execution. The following is the current relationship between + the value set on this variable and the messages written: + + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **0** + - + Off; no messages of any sort are written. + + * - **1** + - + Only critical messages are written (default if this variable + does not exist) + + * - **2** + - + Errors and all messages written with a lower value. + + * - **3** + - + Warnings and all messages written with a lower value. + + * - **4** + - + Informational and all messages written with a lower value. + + * - **5** + - + Debugging mode -- all messages written, however this requires + RMR to have been compiled with debugging support enabled. + + + + * - **RMR_RTG_ISRAW** + - + **Deprecated.** Should be set to 1 if the route table + generator is sending "plain" messages (not using RMR to send + messages), 0 if the RTG is using RMR to send. The default is + 1 as we don't expect the RTG to use RMR. + + This variable is only recognised when using the NNG transport + library as it is not possible to support NNG "raw" + communications with other transport libraries. It is also + necessary to match the value of this variable with the + capabilities of the Route Manager; at some point in the + future RMR will assume that all Route Manager messages will + arrive via an RMR connection and will ignore this variable. + + * - **RMR_SEED_RT** + - + This is used to supply a static route table which can be used + for debugging, testing, or if no route table generator + process is being used to supply the route table. If not + defined, no static table is used and RMR will not report + *ready* until a table is received. The static route table may + contain both the route table (between newrt start and end + records), and the MEID map (between meid_map start and end + records). + + * - **RMR_SRC_ID** + - + This is either the name or IP address which is placed into + outbound messages as the message source. This will used when + an RMR based application uses the rmr_rts_msg() function to + return a response to the sender. If not supplied RMR will use + the hostname which in some container environments might not + be routable. + + The value of this variable is also used for Route Manager + messages which are sent via an RMR connection. + + * - **RMR_VCTL_FILE** + - + This supplies the name of a verbosity control file. The core + RMR functions do not produce messages unless there is a + critical failure. However, the route table collection thread, + not a part of the main message processing component, can + write additional messages to standard error. If this variable + is set, RMR will extract the verbosity level for these + messages (0 is silent) from the first line of the file. + Changes to the file are detected and thus the level can be + changed dynamically, however RMR will only suss out this + variable during initialisation, so it is impossible to enable + verbosity after startup. + + * - **RMR_WARNINGS** + - + If set to 1, RMR will write some warnings which are + non-performance impacting. If the variable is not defined, or + set to 0, RMR will not write these additional warnings. + + diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst index bdd8964..9bfeccc 100644 --- a/docs/developer-guide.rst +++ b/docs/developer-guide.rst @@ -1,122 +1,122 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Developer's Guide -============================================================================================ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Developer's Guide +============================================================================================ OVERVIEW ======== -The RIC Message Router (RMR) is a library for peer-to-peer -communication. Applications use the library to send and -receive messages where the message routing and endpoint -selection is based on the message type rather than DNS host -name-IP port combinations. - -This document contains information that developers need to -know to contribute to the RMR project. +The RIC Message Router (RMR) is a library for peer-to-peer +communication. Applications use the library to send and +receive messages where the message routing and endpoint +selection is based on the message type rather than DNS host +name-IP port combinations. + +This document contains information that developers need to +know to contribute to the RMR project. Language -------- -RMR is written in C, and thus a contributing developer to the -core library should have an excellent working knowledge of C. -There currently is one set of cross-languages bindings -supporting Python, and a developer wishing to contribute to -the bindings source should be familiar with Python (version -3.7+) and with the Python *ctypes* library. +RMR is written in C, and thus a contributing developer to the +core library should have an excellent working knowledge of C. +There currently is one set of cross-languages bindings +supporting Python, and a developer wishing to contribute to +the bindings source should be familiar with Python (version +3.7+) and with the Python *ctypes* library. Code Structure -------------- -RMR is designed to provide an insulation layer between user -applications and the actual transport mechanism. Initially -RMR was built on top of the third-party library Nanosmg, -shortly after was ported to the third-party library NNG -(Nanomsg Next Generation), and then was ported to an -internally developed socket library called SI95. RMR presents -the same API to the user application regardless of the -underlying transport library, but the resulting output when -compiling RMR is always a transport-specific library. As an -example, ``librmr_nng.a`` is the library generated for use -with the NNG transport. - -As such the library source is organised into multiple -components: - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **common** - - - Source in the common directory is agnostic to the underlying - transport mechanism (Nanomsg, NNG, SI95, ..), and thus can be - used when generating either library. - - * - **nano** - - - Source which is tightly coupled with the underlying Nanomsg - library. (Nanomsg has been deprecated, but the RMR source - remains as an example.) - - * - **nng** - - - Source which is tightly coupled with the underlying NNG - library. (NNG has been deprecated, but the RMR source remains - as an example.) - - * - **si** - - - Source which is tightly coupled with the underlying SI95 - library. - - - +RMR is designed to provide an insulation layer between user +applications and the actual transport mechanism. Initially +RMR was built on top of the third-party library Nanosmg, +shortly after was ported to the third-party library NNG +(Nanomsg Next Generation), and then was ported to an +internally developed socket library called SI95. RMR presents +the same API to the user application regardless of the +underlying transport library, but the resulting output when +compiling RMR is always a transport-specific library. As an +example, ``librmr_nng.a`` is the library generated for use +with the NNG transport. + +As such the library source is organised into multiple +components: + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **common** + - + Source in the common directory is agnostic to the underlying + transport mechanism (Nanomsg, NNG, SI95, ..), and thus can be + used when generating either library. + + * - **nano** + - + Source which is tightly coupled with the underlying Nanomsg + library. (Nanomsg has been deprecated, but the RMR source + remains as an example.) + + * - **nng** + - + Source which is tightly coupled with the underlying NNG + library. (NNG has been deprecated, but the RMR source remains + as an example.) + + * - **si** + - + Source which is tightly coupled with the underlying SI95 + library. + + + Internal Function Exposure -------------------------- -The decision to limit as much as practical the exposure of -truly internal RMR functions was made, and as a result most -of the RMR functions carry a ``static`` label. In order to -modularise the code as much as possible, this means that the -primary module (e.g. rmr_nng.c) directly includes other RMR -modules, rather than depending on referencing the internal -functions during linking. While this is an infrequently used -approach, it does mean that there are very few functions -visible for the user application to reference, all of them -having the prefix ``rmr\$1_``. This allows internal functions -to have shorter names while still being meaningful. +The decision to limit as much as practical the exposure of +truly internal RMR functions was made, and as a result most +of the RMR functions carry a ``static`` label. In order to +modularise the code as much as possible, this means that the +primary module (e.g. rmr_nng.c) directly includes other RMR +modules, rather than depending on referencing the internal +functions during linking. While this is an infrequently used +approach, it does mean that there are very few functions +visible for the user application to reference, all of them +having the prefix ``rmr\$1_``. This allows internal functions +to have shorter names while still being meaningful. Coding Style ------------ -There is a list of coding style guidelines in the top level -directory, and as such they are not expanded upon here. The -general practice is to follow the style when editing an -existing module, respect the author's choice where style -alternatives are not frowned upon. When creating new modules, -select a style that fits the guidelines and is easy for you -to work with. There are a few things that the RMR maintainers -insist on, but for the most part style is up to the creator -of a module. +There is a list of coding style guidelines in the top level +directory, and as such they are not expanded upon here. The +general practice is to follow the style when editing an +existing module, respect the author's choice where style +alternatives are not frowned upon. When creating new modules, +select a style that fits the guidelines and is easy for you +to work with. There are a few things that the RMR maintainers +insist on, but for the most part style is up to the creator +of a module. Building -------- -RMR is constructed using CMake. While CMake's project -description can be more cumbersome than most typical -Makefiles, the tool provides convenience especially when it -comes to creating DEB/RPM packages. +RMR is constructed using CMake. While CMake's project +description can be more cumbersome than most typical +Makefiles, the tool provides convenience especially when it +comes to creating DEB/RPM packages. diff --git a/docs/msg_types.rst b/docs/msg_types.rst index f2e6a99..090d112 100644 --- a/docs/msg_types.rst +++ b/docs/msg_types.rst @@ -29,15 +29,15 @@ These message types are not routable and a message passed to an RMR function with any of these constants set will not be sent. - .. list-table:: - :widths: 30,70 - :header-rows: 0 - :class: borderless + .. list-table:: + :widths: 30,70 + :header-rows: 0 + :class: borderless - * - **RIC_UNDEFINED** - - - Message type is unset or undefined. Newly allocated messages - have the type value set to this constant. + * - **RIC_UNDEFINED** + - + Message type is unset or undefined. Newly allocated messages + have the type value set to this constant. @@ -48,25 +48,25 @@ RMR Reserved Message Types These message types are reserved for RMR communications (e.g. with Route Manager). - .. list-table:: - :widths: 30,70 - :header-rows: 0 - :class: borderless + .. list-table:: + :widths: 30,70 + :header-rows: 0 + :class: borderless - * - **RMRRM_TABLE_DATA** - - - Table data from route manger. Route manager sends all route - mse, etc.) with this type. + * - **RMRRM_TABLE_DATA** + - + Table data from route manger. Route manager sends all route + mse, etc.) with this type. - * - **RMRRM_REQ_TABLE** - - - Request for table update. RMR will send a message with this a - table update from route manger. + * - **RMRRM_REQ_TABLE** + - + Request for table update. RMR will send a message with this a + table update from route manger. - * - **RMRRM_TABLE_STATE** - - - This message type conveys the state of the route table to the - end of a table is noticed. + * - **RMRRM_TABLE_STATE** + - + This message type conveys the state of the route table to the + end of a table is noticed. @@ -77,33 +77,33 @@ System Support Message Types These message types are used for systems level communications such as health checks, alarms and probes. - .. list-table:: - :widths: 30,70 - :header-rows: 0 - :class: borderless + .. list-table:: + :widths: 30,70 + :header-rows: 0 + :class: borderless - * - **RIC_HEALTH_CHECK_REQ** - - - When received the application is expected to return a - response to the current "health" of the application. + * - **RIC_HEALTH_CHECK_REQ** + - + When received the application is expected to return a + response to the current "health" of the application. - * - **RIC_HEALTH_CHECK_RESP** - - - Health responses are sent with a message of this type. + * - **RIC_HEALTH_CHECK_RESP** + - + Health responses are sent with a message of this type. - * - **RIC_ALARM** - - - Alarm messages with this type are routed to the alarm - collection process. + * - **RIC_ALARM** + - + Alarm messages with this type are routed to the alarm + collection process. - * - **RIC_ALARM_QUERY** - - - Unknown meaning + * - **RIC_ALARM_QUERY** + - + Unknown meaning - * - **RIC_METRICS** - - - This message type causes the message to be routed to the xAPP - responsible redistributing metrics. + * - **RIC_METRICS** + - + This message type causes the message to be routed to the xAPP + responsible redistributing metrics. @@ -114,385 +114,385 @@ Unclassified Message Types The following message types have not been clasified into a specific category. - .. list-table:: - :widths: 30,70 - :header-rows: 0 - :class: borderless + .. list-table:: + :widths: 30,70 + :header-rows: 0 + :class: borderless - * - **RIC_SCTP_CONNECTION_FAILURE** - - - | + * - **RIC_SCTP_CONNECTION_FAILURE** + - + | - * - **RIC_SCTP_CLEAR_ALL** - - - | + * - **RIC_SCTP_CLEAR_ALL** + - + | - * - **E2_TERM_INIT** - - - | + * - **E2_TERM_INIT** + - + | - * - **E2_TERM_KEEP_ALIVE_REQ** - - - | + * - **E2_TERM_KEEP_ALIVE_REQ** + - + | - * - **E2_TERM_KEEP_ALIVE_RESP** - - - | + * - **E2_TERM_KEEP_ALIVE_RESP** + - + | - * - **RAN_CONNECTED** - - - | + * - **RAN_CONNECTED** + - + | - * - **RAN_RESTARTED** - - - | + * - **RAN_RESTARTED** + - + | - * - **RAN_RECONFIGURED** - - - | + * - **RAN_RECONFIGURED** + - + | - * - **RIC_ENB_LOAD_INFORMATION** - - - | + * - **RIC_ENB_LOAD_INFORMATION** + - + | - * - **RIC_ERROR_INDICATION** - - - | + * - **RIC_ERROR_INDICATION** + - + | - * - **RIC_SN_STATUS_TRANSFER** - - - | + * - **RIC_SN_STATUS_TRANSFER** + - + | - * - **RIC_UE_CONTEXT_RELEASE** - - - | + * - **RIC_UE_CONTEXT_RELEASE** + - + | - * - **RIC_X2_SETUP_REQ** - - - | + * - **RIC_X2_SETUP_REQ** + - + | - * - **RIC_X2_SETUP_RESP** - - - | + * - **RIC_X2_SETUP_RESP** + - + | - * - **RIC_X2_SETUP_FAILURE** - - - | + * - **RIC_X2_SETUP_FAILURE** + - + | - * - **RIC_X2_RESET** - - - | + * - **RIC_X2_RESET** + - + | - * - **RIC_X2_RESET_RESP** - - - | + * - **RIC_X2_RESET_RESP** + - + | - * - **RIC_ENB_CONF_UPDATE** - - - | + * - **RIC_ENB_CONF_UPDATE** + - + | - * - **RIC_ENB_CONF_UPDATE_ACK** - - - | + * - **RIC_ENB_CONF_UPDATE_ACK** + - + | - * - **RIC_ENB_CONF_UPDATE_FAILURE** - - - | + * - **RIC_ENB_CONF_UPDATE_FAILURE** + - + | - * - **RIC_RES_STATUS_REQ** - - - | + * - **RIC_RES_STATUS_REQ** + - + | - * - **RIC_RES_STATUS_RESP** - - - | + * - **RIC_RES_STATUS_RESP** + - + | - * - **RIC_RES_STATUS_FAILURE** - - - | + * - **RIC_RES_STATUS_FAILURE** + - + | - * - **RIC_RESOURCE_STATUS_UPDATE** - - - | + * - **RIC_RESOURCE_STATUS_UPDATE** + - + | - * - **RIC_SGNB_ADDITION_REQ** - - - | + * - **RIC_SGNB_ADDITION_REQ** + - + | - * - **RIC_SGNB_ADDITION_ACK** - - - | + * - **RIC_SGNB_ADDITION_ACK** + - + | - * - **RIC_SGNB_ADDITION_REJECT** - - - | + * - **RIC_SGNB_ADDITION_REJECT** + - + | - * - **RIC_SGNB_RECONF_COMPLETE** - - - | + * - **RIC_SGNB_RECONF_COMPLETE** + - + | - * - **RIC_SGNB_MOD_REQUEST** - - - | + * - **RIC_SGNB_MOD_REQUEST** + - + | - * - **RIC_SGNB_MOD_REQUEST_ACK** - - - | + * - **RIC_SGNB_MOD_REQUEST_ACK** + - + | - * - **RIC_SGNB_MOD_REQUEST_REJ** - - - | + * - **RIC_SGNB_MOD_REQUEST_REJ** + - + | - * - **RIC_SGNB_MOD_REQUIRED** - - - | + * - **RIC_SGNB_MOD_REQUIRED** + - + | - * - **RIC_SGNB_MOD_CONFIRM** - - - | + * - **RIC_SGNB_MOD_CONFIRM** + - + | - * - **RIC_SGNB_MOD_REFUSE** - - - | + * - **RIC_SGNB_MOD_REFUSE** + - + | - * - **RIC_SGNB_RELEASE_REQUEST** - - - | + * - **RIC_SGNB_RELEASE_REQUEST** + - + | - * - **RIC_SGNB_RELEASE_REQUEST_ACK** - - - | + * - **RIC_SGNB_RELEASE_REQUEST_ACK** + - + | - * - **RIC_SGNB_RELEASE_REQUIRED** - - - | + * - **RIC_SGNB_RELEASE_REQUIRED** + - + | - * - **RIC_SGNB_RELEASE_CONFIRM** - - - | + * - **RIC_SGNB_RELEASE_CONFIRM** + - + | - * - **RIC_RRC_TRANSFER** - - - | + * - **RIC_RRC_TRANSFER** + - + | - * - **RIC_ENDC_X2_SETUP_REQ** - - - | + * - **RIC_ENDC_X2_SETUP_REQ** + - + | - * - **RIC_ENDC_X2_SETUP_RESP** - - - | + * - **RIC_ENDC_X2_SETUP_RESP** + - + | - * - **RIC_ENDC_X2_SETUP_FAILURE** - - - | + * - **RIC_ENDC_X2_SETUP_FAILURE** + - + | - * - **RIC_ENDC_CONF_UPDATE** - - - | + * - **RIC_ENDC_CONF_UPDATE** + - + | - * - **RIC_ENDC_CONF_UPDATE_ACK** - - - | + * - **RIC_ENDC_CONF_UPDATE_ACK** + - + | - * - **RIC_ENDC_CONF_UPDATE_FAILURE** - - - | + * - **RIC_ENDC_CONF_UPDATE_FAILURE** + - + | - * - **RIC_SECONDARY_RAT_DATA_USAGE_REPORT** - - - | + * - **RIC_SECONDARY_RAT_DATA_USAGE_REPORT** + - + | - * - **RIC_GNB_STATUS_INDICATION** - - - | + * - **RIC_GNB_STATUS_INDICATION** + - + | - * - **RIC_E2_SETUP_REQ** - - - | + * - **RIC_E2_SETUP_REQ** + - + | - * - **RIC_E2_SETUP_RESP** - - - | + * - **RIC_E2_SETUP_RESP** + - + | - * - **RIC_E2_SETUP_FAILURE** - - - | + * - **RIC_E2_SETUP_FAILURE** + - + | - * - **RIC_E2_RESET_REQ** - - - | + * - **RIC_E2_RESET_REQ** + - + | - * - **RIC_E2_RESET_RESP** - - - | + * - **RIC_E2_RESET_RESP** + - + | - * - **RIC_E2_RAN_ERROR_INDICATION** - - - | + * - **RIC_E2_RAN_ERROR_INDICATION** + - + | - * - **RIC_E2_RIC_ERROR_INDICATION** - - - | + * - **RIC_E2_RIC_ERROR_INDICATION** + - + | - * - **RAN_E2_RESET_REQ** - - - | + * - **RAN_E2_RESET_REQ** + - + | - * - **RAN_E2_RESET_RESP** - - - | + * - **RAN_E2_RESET_RESP** + - + | - * - **RIC_SUB_REQ** - - - | + * - **RIC_SUB_REQ** + - + | - * - **RIC_SUB_RESP** - - - | + * - **RIC_SUB_RESP** + - + | - * - **RIC_SUB_FAILURE** - - - | + * - **RIC_SUB_FAILURE** + - + | - * - **RIC_SUB_DEL_REQ** - - - | + * - **RIC_SUB_DEL_REQ** + - + | - * - **RIC_SUB_DEL_RESP** - - - | + * - **RIC_SUB_DEL_RESP** + - + | - * - **RIC_SUB_DEL_FAILURE** - - - | + * - **RIC_SUB_DEL_FAILURE** + - + | - * - **RIC_SERVICE_UPDATE** - - - | + * - **RIC_SERVICE_UPDATE** + - + | - * - **RIC_SERVICE_UPDATE_ACK** - - - | + * - **RIC_SERVICE_UPDATE_ACK** + - + | - * - **RIC_SERVICE_UPDATE_FAILURE** - - - | + * - **RIC_SERVICE_UPDATE_FAILURE** + - + | - * - **RIC_CONTROL_REQ** - - - | + * - **RIC_CONTROL_REQ** + - + | - * - **RIC_CONTROL_ACK** - - - | + * - **RIC_CONTROL_ACK** + - + | - * - **RIC_CONTROL_FAILURE** - - - | + * - **RIC_CONTROL_FAILURE** + - + | - * - **RIC_INDICATION** - - - | + * - **RIC_INDICATION** + - + | - * - **RIC_SERVICE_QUERY** - - - | + * - **RIC_SERVICE_QUERY** + - + | - * - **DC_ADM_INT_CONTROL** - - - | + * - **DC_ADM_INT_CONTROL** + - + | - * - **DC_ADM_INT_CONTROL_ACK** - - - | + * - **DC_ADM_INT_CONTROL_ACK** + - + | - * - **DC_ADM_GET_POLICY** - - - | + * - **DC_ADM_GET_POLICY** + - + | - * - **DC_ADM_GET_POLICY_ACK** - - - | + * - **DC_ADM_GET_POLICY_ACK** + - + | - * - **A1_POLICY_REQ** - - - | + * - **A1_POLICY_REQ** + - + | - * - **A1_POLICY_RESP** - - - | + * - **A1_POLICY_RESP** + - + | - * - **A1_POLICY_QUERY** - - - | + * - **A1_POLICY_QUERY** + - + | - * - **TS_UE_LIST** - - - | + * - **TS_UE_LIST** + - + | - * - **TS_QOE_PRED_REQ** - - - | + * - **TS_QOE_PRED_REQ** + - + | - * - **TS_QOE_PREDICTION** - - - | + * - **TS_QOE_PREDICTION** + - + | - * - **MC_REPORT** - - - | + * - **MC_REPORT** + - + | - * - **DCAPTERM_RTPM_RMR_MSGTYPE** - - - | + * - **DCAPTERM_RTPM_RMR_MSGTYPE** + - + | - * - **DCAPTERM_GEO_RMR_MSGTYPE** - - - | + * - **DCAPTERM_GEO_RMR_MSGTYPE** + - + | - * - **RIC_X2_SETUP** - - - deprecated + * - **RIC_X2_SETUP** + - + deprecated - * - **RIC_X2_RESPONSE** - - - deprecated + * - **RIC_X2_RESPONSE** + - + deprecated - * - **RIC_X2_RESOURCE_STATUS_REQUEST** - - - deprecated + * - **RIC_X2_RESOURCE_STATUS_REQUEST** + - + deprecated - * - **RIC_X2_RESOURCE_STATUS_RESPONSE** - - - deprecated + * - **RIC_X2_RESOURCE_STATUS_RESPONSE** + - + deprecated - * - **RIC_X2_LOAD_INFORMATION** - - - deprecated + * - **RIC_X2_LOAD_INFORMATION** + - + deprecated - * - **RIC_E2_TERMINATION_HC_REQUEST** - - - deprecated + * - **RIC_E2_TERMINATION_HC_REQUEST** + - + deprecated - * - **RIC_E2_TERMINATION_HC_RESPONSE** - - - deprecated + * - **RIC_E2_TERMINATION_HC_RESPONSE** + - + deprecated - * - **RIC_E2_MANAGER_HC_REQUEST** - - - deprecated + * - **RIC_E2_MANAGER_HC_REQUEST** + - + deprecated - * - **RIC_E2_MANAGER_HC_RESPONSE** - - - deprecated + * - **RIC_E2_MANAGER_HC_RESPONSE** + - + deprecated - * - **RIC_CONTROL_XAPP_CONFIG_REQUEST** - - - deprecated + * - **RIC_CONTROL_XAPP_CONFIG_REQUEST** + - + deprecated - * - **RIC_CONTROL_XAPP_CONFIG_RESPONSE** - - - deprecated + * - **RIC_CONTROL_XAPP_CONFIG_RESPONSE** + - + deprecated diff --git a/docs/rel-notes.rst b/docs/rel-notes.rst index 43a100b..f740768 100644 --- a/docs/rel-notes.rst +++ b/docs/rel-notes.rst @@ -22,6 +22,14 @@ the need to leap frog versions ceased, and beginning with version 4.0.0, the RMR versions should no longer skip. +2020 July 21; Version 4.2.4 +--------------------------- + +Fix bug in SI95 -- possible use of pointer after free +(RIC-626). + + + 2020 July 9; version 4.1.3 -------------------------- diff --git a/docs/rmr.7.rst b/docs/rmr.7.rst index e3df91c..05c1cd4 100644 --- a/docs/rmr.7.rst +++ b/docs/rmr.7.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr +============================================================================================ + + RMR LIBRARY @@ -19,395 +19,395 @@ RMR LIBRARY NAME ---- -RMR -- Ric Message Router Library +RMR -- Ric Message Router Library 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., 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. -This table is used to determine the destination endpoint of -each message sent by mapping the message type T (supplied by -the user application) to an endpoint entry. Once determined, -the message is sent directly to the endpoint. The user -application is unaware of which endpoint actually receives -the message, and in some cases whether that message was sent -to multiple applications. - -RMR functions do provide for the ability to respond to the -specific source instance of a message allowing for either a -request response, or call response relationship when needed. +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., 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. +This table is used to determine the destination endpoint of +each message sent by mapping the message type T (supplied by +the user application) to an endpoint entry. Once determined, +the message is sent directly to the endpoint. The user +application is unaware of which endpoint actually receives +the message, and in some cases whether that message was sent +to multiple applications. + +RMR functions do provide for the ability to respond to the +specific source instance of a message allowing for either a +request response, or call response relationship when needed. The Route Table --------------- -The library must be given a route table which maps message -types (integers) to endpoint groups such that each time a -message of type T is sent, the message is delivered to one -member of each group associated with T. For example, message -type 2 might route to two different groups where group A has -two members, worker1 and worker2, while group B has only one -member, logger1. - -The route table consists of a start record, one or more table -entry records, and an end record. All table records contain -fields separated with vertical bars (|), and allow for -trailing comments with the standard shell comment symbol -(hash, #) provided that the start of the comment is separated -from the last token on the record by one or more spaces. -Leading and trailing white space in each field is ignored. -The route table supports two entry types: *rte* and *mse*. - -A *rte* entry defines a message type, an optional sender -application, and the endpoint(s) which accept the indicated -message type. However, this format is deprecated and may be -removed in a future version. An example record appears next. - -:: - - rte | 1 | app10:4560 - - -The second type of entry is *mse*. This entry defines a -message type, an optional sender application, a subscription -ID, and a collection of endpoints. An example record appears -next. - -:: - - mse | 1000,forwarder:43086 | 10 | app2:43086 - - -It is the responsibility of the route table generator to know -which endpoints belong to which groups, and which groups -accept which message types. Once understood, the route table -generator publishes a table that is ingested by RMR and used -for mapping messages to end points. - -The following is a simple route table which causes message -types 0 through 9 to be routed to specific applications: - -:: - - newrt|start - mse|0|-1| %meid - mse|1|-1|app10:4560,app11:4560 - mse|2|-1|app12:4560 - mse|3|-1|app14:4560 - mse|4|-1|app18:4560 - mse|5|-1|app01:4560 - mse|6|-1|app02:4560 - mse|7|-1|app03:4560 - mse|8|-1|app04:4560 - mse|9|-1|app05:4560 - newrt|end - - -The special endpoint "%meid" indicates that the message type -(0 in this case) is to be routed to the endpoint which has -been listed as the "owner" for the meid appearing in the -message. MEID ownership is communicated to RMR using the same -Route Table Manager interface and by supplying a "table" such -as the one below: - -:: - - meid_map | start - mme_ar | control1 | meid000 meid001 meid002 meid003 meid004 meid005 - mme_ar | control2 | meid100 meid101 meid102 meid103 - meid_map | end | 2 - - -This table indicates that the application (endpoint) -*control1* "owns" 6 MEIDs and *control2* owns 4. When message -type 0 is sent, the MEID in the message will be used to -select the endpoint via this table. - -The MEID table will update the existing owner relationships, -and add new ones; it is necessary to send only the changes -with the add/replace (mme_ar) entries in the table. When -necessary, MEIDs can be deleted by adding an ``mme_del`` -record to the table. The following example illustrates how -this might look: - -:: - - meid_map | start - mme_ar | control1 | meid000 meid001 meid002 meid003 meid004 meid005 - mme_ar | control2 | meid100 meid101 meid102 meid103 - mme_del| meid200 meid401 - meid_map | end | 3 - +The library must be given a route table which maps message +types (integers) to endpoint groups such that each time a +message of type T is sent, the message is delivered to one +member of each group associated with T. For example, message +type 2 might route to two different groups where group A has +two members, worker1 and worker2, while group B has only one +member, logger1. + +The route table consists of a start record, one or more table +entry records, and an end record. All table records contain +fields separated with vertical bars (|), and allow for +trailing comments with the standard shell comment symbol +(hash, #) provided that the start of the comment is separated +from the last token on the record by one or more spaces. +Leading and trailing white space in each field is ignored. +The route table supports two entry types: *rte* and *mse*. + +A *rte* entry defines a message type, an optional sender +application, and the endpoint(s) which accept the indicated +message type. However, this format is deprecated and may be +removed in a future version. An example record appears next. + +:: + + rte | 1 | app10:4560 + + +The second type of entry is *mse*. This entry defines a +message type, an optional sender application, a subscription +ID, and a collection of endpoints. An example record appears +next. + +:: + + mse | 1000,forwarder:43086 | 10 | app2:43086 + + +It is the responsibility of the route table generator to know +which endpoints belong to which groups, and which groups +accept which message types. Once understood, the route table +generator publishes a table that is ingested by RMR and used +for mapping messages to end points. + +The following is a simple route table which causes message +types 0 through 9 to be routed to specific applications: + +:: + + newrt|start + mse|0|-1| %meid + mse|1|-1|app10:4560,app11:4560 + mse|2|-1|app12:4560 + mse|3|-1|app14:4560 + mse|4|-1|app18:4560 + mse|5|-1|app01:4560 + mse|6|-1|app02:4560 + mse|7|-1|app03:4560 + mse|8|-1|app04:4560 + mse|9|-1|app05:4560 + newrt|end + + +The special endpoint "%meid" indicates that the message type +(0 in this case) is to be routed to the endpoint which has +been listed as the "owner" for the meid appearing in the +message. MEID ownership is communicated to RMR using the same +Route Table Manager interface and by supplying a "table" such +as the one below: + +:: + + meid_map | start + mme_ar | control1 | meid000 meid001 meid002 meid003 meid004 meid005 + mme_ar | control2 | meid100 meid101 meid102 meid103 + meid_map | end | 2 + + +This table indicates that the application (endpoint) +*control1* "owns" 6 MEIDs and *control2* owns 4. When message +type 0 is sent, the MEID in the message will be used to +select the endpoint via this table. + +The MEID table will update the existing owner relationships, +and add new ones; it is necessary to send only the changes +with the add/replace (mme_ar) entries in the table. When +necessary, MEIDs can be deleted by adding an ``mme_del`` +record to the table. The following example illustrates how +this might look: + +:: + + meid_map | start + mme_ar | control1 | meid000 meid001 meid002 meid003 meid004 meid005 + mme_ar | control2 | meid100 meid101 meid102 meid103 + mme_del| meid200 meid401 + meid_map | end | 3 + Route Table Syntax ------------------ -The following illustrates the syntax for both types of route -table entries. - - -:: - - newrt | start - rte | [,] | [;]... - mse | [,] | | [;]... - newrt | end - - -A round robin group is one or more endpoints from which one -will be selected to receive the message. When multiple -endpoints are given in a group, they must be separated with a -comma. An endpoint is an IP address and port (e.g. -192.158.4.30:8219), or DNS name and port, of the application -that should receive the message type. If multiple round-robin -groups are given, they must be separated by a semicolon. +The following illustrates the syntax for both types of route +table entries. + + +:: + + newrt | start + rte | [,] | [;]... + mse | [,] | | [;]... + newrt | end + + +A round robin group is one or more endpoints from which one +will be selected to receive the message. When multiple +endpoints are given in a group, they must be separated with a +comma. An endpoint is an IP address and port (e.g. +192.158.4.30:8219), or DNS name and port, of the application +that should receive the message type. If multiple round-robin +groups are given, they must be separated by a semicolon. MEID Map Syntax --------------- -The MEID map is similar to the route table. Entries are used -to add or replace the ownership of one or more MEIDs (mme_ar) -or to delete one or more MEIDs (mme_del). The following is -the syntax for the MEID map. - - -:: - - meid_map | start - mme_ar | | [...] - mme_del | [...] - meid_map | end | | - - -The on the end record indicates the number of mme_ar -and mme_del records which were sent; if the count does not -match the whole map is refused and dropped. The - is the endpoint which should receive the -message when a message is routed based on the MEID it -contains. A MEID may be "owned" by only one endpoint, and if -supplied multiple times, the last observed relationship is -used. Each of the lists of MEIDs are blank separated. - -The optional on the *end* record should be the -computed MD5 hash for all records which appear between the -start and and records. This allows for a tighter verification -that all data was received exactly as the route manager -transmitted them. +The MEID map is similar to the route table. Entries are used +to add or replace the ownership of one or more MEIDs (mme_ar) +or to delete one or more MEIDs (mme_del). The following is +the syntax for the MEID map. + + +:: + + meid_map | start + mme_ar | | [...] + mme_del | [...] + meid_map | end | | + + +The on the end record indicates the number of mme_ar +and mme_del records which were sent; if the count does not +match the whole map is refused and dropped. The + is the endpoint which should receive the +message when a message is routed based on the MEID it +contains. A MEID may be "owned" by only one endpoint, and if +supplied multiple times, the last observed relationship is +used. Each of the lists of MEIDs are blank separated. + +The optional on the *end* record should be the +computed MD5 hash for all records which appear between the +start and and records. This allows for a tighter verification +that all data was received exactly as the route manager +transmitted them. Environment ----------- -To enable configuration of the library behaviour outside of -direct user application control, RMR supports a number of -environment variables which provide information to the -library. The following is a list of the various environment -variables, what they control and the defaults which RMR uses -if undefined. - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **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 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. - - * - **RMR_CTL_PORT** - - - This variable defines the port that RMR should open for - communications with Route Manager, and other RMR control - applications. If not defined, the port 4561 is assumed. - - Previously, the ``RMR_RTG_SVC`` (route table generator - service port) was used to define this port. However, a future - version of Route Manager will require RMR to connect and - request tables, thus that variable is now used to supply the - Route Manager's well-known address and port. - - 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 manager is - used (routemgr:4561). - - When ``RMR_CTL_PORT`` is **undefined:** RMR assumes that - Route Manager will connect and push table updates, thus the - default listen port (4561) is used. - - To avoid any possible misinterpretation and/or incorrect - assumptions on the part of RMR, it is recommended that both - the ``RMR_CTL_PORT`` and ``RMR_RTG_SVC`` be defined. In the - case where both variables are defined, RMR will behave - exactly as is communicated with the variable's values. - - * - **RMR_RTG_SVC** - - - The value of this variable depends on the Route Manager in - use. - - When the Route Manager is expecting to connect to an xAPP and - push route tables, this variable must indicate the - ``port`` which RMR should use to listen for these - connections. - - When the Route Manager is expecting RMR to connect and - request a table update during initialisation, the variable - should be the ``host`` of the Route Manager process. - - The ``RMR_CTL_PORT`` variable (added with the support of - sending table update requests to Route manager), controls the - behaviour if this variable is not set. See the description of - that variable for details. - - * - **RMR_HR_LOG** - - - By default RMR writes messages to standard error (incorrectly - referred to as log messages) in human readable format. If - this environment variable is set to 0, the format of standard - error messages might be written in some format not easily - read by humans. If missing, a value of 1 is assumed. - - * - **RMR_LOG_VLEVEL** - - - This is a numeric value which corresponds to the verbosity - level used to limit messages written to standard error. The - lower the number the less chatty RMR functions are during - execution. The following is the current relationship between - the value set on this variable and the messages written: - - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **0** - - - Off; no messages of any sort are written. - - * - **1** - - - Only critical messages are written (default if this variable - does not exist) - - * - **2** - - - Errors and all messages written with a lower value. - - * - **3** - - - Warnings and all messages written with a lower value. - - * - **4** - - - Informational and all messages written with a lower value. - - * - **5** - - - Debugging mode -- all messages written, however this requires - RMR to have been compiled with debugging support enabled. - - - - * - **RMR_RTG_ISRAW** - - - **Deprecated.** Should be set to 1 if the route table - generator is sending "plain" messages (not using RMR to send - messages), 0 if the RTG is using RMR to send. The default is - 1 as we don't expect the RTG to use RMR. - - This variable is only recognised when using the NNG transport - library as it is not possible to support NNG "raw" - communications with other transport libraries. It is also - necessary to match the value of this variable with the - capabilities of the Route Manager; at some point in the - future RMR will assume that all Route Manager messages will - arrive via an RMR connection and will ignore this variable. - - * - **RMR_SEED_RT** - - - This is used to supply a static route table which can be used - for debugging, testing, or if no route table generator - process is being used to supply the route table. If not - defined, no static table is used and RMR will not report - *ready* until a table is received. The static route table may - contain both the route table (between newrt start and end - records), and the MEID map (between meid_map start and end - records). - - * - **RMR_SRC_ID** - - - This is either the name or IP address which is placed into - outbound messages as the message source. This will used when - an RMR based application uses the rmr_rts_msg() function to - return a response to the sender. If not supplied RMR will use - the hostname which in some container environments might not - be routable. - - The value of this variable is also used for Route Manager - messages which are sent via an RMR connection. - - * - **RMR_VCTL_FILE** - - - This supplies the name of a verbosity control file. The core - RMR functions do not produce messages unless there is a - critical failure. However, the route table collection thread, - not a part of the main message processing component, can - write additional messages to standard error. If this variable - is set, RMR will extract the verbosity level for these - messages (0 is silent) from the first line of the file. - Changes to the file are detected and thus the level can be - changed dynamically, however RMR will only suss out this - variable during initialisation, so it is impossible to enable - verbosity after startup. - - * - **RMR_WARNINGS** - - - If set to 1, RMR will write some warnings which are - non-performance impacting. If the variable is not defined, or - set to 0, RMR will not write these additional warnings. - - +To enable configuration of the library behaviour outside of +direct user application control, RMR supports a number of +environment variables which provide information to the +library. The following is a list of the various environment +variables, what they control and the defaults which RMR uses +if undefined. + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **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 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. + + * - **RMR_CTL_PORT** + - + This variable defines the port that RMR should open for + communications with Route Manager, and other RMR control + applications. If not defined, the port 4561 is assumed. + + Previously, the ``RMR_RTG_SVC`` (route table generator + service port) was used to define this port. However, a future + version of Route Manager will require RMR to connect and + request tables, thus that variable is now used to supply the + Route Manager's well-known address and port. + + 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 manager is + used (routemgr:4561). + + When ``RMR_CTL_PORT`` is **undefined:** RMR assumes that + Route Manager will connect and push table updates, thus the + default listen port (4561) is used. + + To avoid any possible misinterpretation and/or incorrect + assumptions on the part of RMR, it is recommended that both + the ``RMR_CTL_PORT`` and ``RMR_RTG_SVC`` be defined. In the + case where both variables are defined, RMR will behave + exactly as is communicated with the variable's values. + + * - **RMR_RTG_SVC** + - + The value of this variable depends on the Route Manager in + use. + + When the Route Manager is expecting to connect to an xAPP and + push route tables, this variable must indicate the + ``port`` which RMR should use to listen for these + connections. + + When the Route Manager is expecting RMR to connect and + request a table update during initialisation, the variable + should be the ``host`` of the Route Manager process. + + The ``RMR_CTL_PORT`` variable (added with the support of + sending table update requests to Route manager), controls the + behaviour if this variable is not set. See the description of + that variable for details. + + * - **RMR_HR_LOG** + - + By default RMR writes messages to standard error (incorrectly + referred to as log messages) in human readable format. If + this environment variable is set to 0, the format of standard + error messages might be written in some format not easily + read by humans. If missing, a value of 1 is assumed. + + * - **RMR_LOG_VLEVEL** + - + This is a numeric value which corresponds to the verbosity + level used to limit messages written to standard error. The + lower the number the less chatty RMR functions are during + execution. The following is the current relationship between + the value set on this variable and the messages written: + + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **0** + - + Off; no messages of any sort are written. + + * - **1** + - + Only critical messages are written (default if this variable + does not exist) + + * - **2** + - + Errors and all messages written with a lower value. + + * - **3** + - + Warnings and all messages written with a lower value. + + * - **4** + - + Informational and all messages written with a lower value. + + * - **5** + - + Debugging mode -- all messages written, however this requires + RMR to have been compiled with debugging support enabled. + + + + * - **RMR_RTG_ISRAW** + - + **Deprecated.** Should be set to 1 if the route table + generator is sending "plain" messages (not using RMR to send + messages), 0 if the RTG is using RMR to send. The default is + 1 as we don't expect the RTG to use RMR. + + This variable is only recognised when using the NNG transport + library as it is not possible to support NNG "raw" + communications with other transport libraries. It is also + necessary to match the value of this variable with the + capabilities of the Route Manager; at some point in the + future RMR will assume that all Route Manager messages will + arrive via an RMR connection and will ignore this variable. + + * - **RMR_SEED_RT** + - + This is used to supply a static route table which can be used + for debugging, testing, or if no route table generator + process is being used to supply the route table. If not + defined, no static table is used and RMR will not report + *ready* until a table is received. The static route table may + contain both the route table (between newrt start and end + records), and the MEID map (between meid_map start and end + records). + + * - **RMR_SRC_ID** + - + This is either the name or IP address which is placed into + outbound messages as the message source. This will used when + an RMR based application uses the rmr_rts_msg() function to + return a response to the sender. If not supplied RMR will use + the hostname which in some container environments might not + be routable. + + The value of this variable is also used for Route Manager + messages which are sent via an RMR connection. + + * - **RMR_VCTL_FILE** + - + This supplies the name of a verbosity control file. The core + RMR functions do not produce messages unless there is a + critical failure. However, the route table collection thread, + not a part of the main message processing component, can + write additional messages to standard error. If this variable + is set, RMR will extract the verbosity level for these + messages (0 is silent) from the first line of the file. + Changes to the file are detected and thus the level can be + changed dynamically, however RMR will only suss out this + variable during initialisation, so it is impossible to enable + verbosity after startup. + + * - **RMR_WARNINGS** + - + If set to 1, RMR will write some warnings which are + non-performance impacting. If the variable is not defined, or + set to 0, RMR will not write these additional warnings. + + SEE ALSO -------- -rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_call(3), -rmr_free_msg(3), rmr_init(3), rmr_init_trace(3), -rmr_get_meid(3), rmr_get_src(3), rmr_get_srcip(3), -rmr_get_trace(3), rmr_get_trlen(3), rmr_get_xact(3), -rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3), -rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3), -rmr_tokenise(3), rmr_mk_ring(3), rmr_realloc_payload(3), -rmr_ring_free(3), rmr_set_trace(3), rmr_torcv_msg(3), -rmr_wh_open(3), rmr_wh_send_msg(3) +rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_call(3), +rmr_free_msg(3), rmr_init(3), rmr_init_trace(3), +rmr_get_meid(3), rmr_get_src(3), rmr_get_srcip(3), +rmr_get_trace(3), rmr_get_trlen(3), rmr_get_xact(3), +rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3), +rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3), +rmr_tokenise(3), rmr_mk_ring(3), rmr_realloc_payload(3), +rmr_ring_free(3), rmr_set_trace(3), rmr_torcv_msg(3), +rmr_wh_open(3), rmr_wh_send_msg(3) diff --git a/docs/rmr_alloc_msg.3.rst b/docs/rmr_alloc_msg.3.rst index cc15fbb..9c79c34 100644 --- a/docs/rmr_alloc_msg.3.rst +++ b/docs/rmr_alloc_msg.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_alloc_msg -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_alloc_msg +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,172 +19,172 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_alloc_msg +rmr_alloc_msg SYNOPSIS -------- - -:: - - #include - - rmr_mbuf_t* rmr_alloc_msg( void* ctx, int size ); - + +:: + + #include + + rmr_mbuf_t* rmr_alloc_msg( void* ctx, int size ); + DESCRIPTION ----------- -The ``rmr_alloc_msg`` function is used to allocate a buffer -which the user programme can write into and then send through -the RMR library. The buffer is allocated such that sending it -requires no additional copying out of the buffer. If the -value passed in ``size`` is less than or equal to 0, then the -*normal maximum size* supplied on the *rmr_init* call will be -used. When *size* is greater than zero, the message allocated -will have at least the indicated number of bytes in the -payload. There is no maximum size imposed by RMR, however the -underlying system memory management (e.g. malloc) functions -may impose a limit. - -The *ctx* parameter is the void context pointer that was -returned by the *rmr_init* function. - -The pointer to the message buffer returned is a structure -which has some user application visible fields; the structure -is described in ``rmr.h,`` and is illustrated below. - - -:: - - typedef struct { - int state; - int mtype; - int len; - unsigned char* payload; - unsigned char* xaction; - int sub_id; - int tp_state; - } rmr_mbuf_t; - - -Where: - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **state** - - - Is the current buffer state. Following a call to - ``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). When the state is - ``RMR_OK`` the buffer represents an empty buffer that the - application may fill in in preparation to send. - - * - **mtype** - - - When sending a message, the application is expected to set - this field to the appropriate message type value (as - determined by the user programme). Upon send this value - determines how the RMR 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. - - * - **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 indicate the number of bytes - in the payload which are valid. - - * - **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 ``rmr_send, rmr_call`` or - ``rmr_reply`` function call. Once the buffer has been passed - back to a RMR library function the user programme should - **NOT** make use of the payload pointer. - - * - **xaction** - - - The *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 ``rmr_call`` function to send a message - and wait for the reply; the underlying RMR processing expects - that the matching reply message will also contain the same - data in the *xaction* field. - - * - **sub_id** - - - This value is the subscription ID. It, in combination with - the message type is used by rmr to determine the target - endpoint when sending a message. If the application to - application protocol does not warrant the use of a - subscription ID, the RMR constant RMR_VOID_SUBID should be - placed in this field. When an application is forwarding or - returning a buffer to the sender, it is the application's - responsibility to set/reset this value. - - * - **tp_state** - - - For C applications making use of RMR, the state of a - transport based failure will often be available via - ``errno.`` However, some wrapper environments may not have - direct access to the C-lib ``errno`` value. RMR send and - receive operations will place the current value of - ``errno`` into this field which should make it available to - wrapper functions. User applications are strongly cautioned - against relying on the value of errno as some transport - mechanisms may not set this value on all calls. This value - should also be ignored any time the message status is - ``RMR_OK.`` - - +The ``rmr_alloc_msg`` function is used to allocate a buffer +which the user programme can write into and then send through +the RMR library. The buffer is allocated such that sending it +requires no additional copying out of the buffer. If the +value passed in ``size`` is less than or equal to 0, then the +*normal maximum size* supplied on the *rmr_init* call will be +used. When *size* is greater than zero, the message allocated +will have at least the indicated number of bytes in the +payload. There is no maximum size imposed by RMR, however the +underlying system memory management (e.g. malloc) functions +may impose a limit. + +The *ctx* parameter is the void context pointer that was +returned by the *rmr_init* function. + +The pointer to the message buffer returned is a structure +which has some user application visible fields; the structure +is described in ``rmr.h,`` and is illustrated below. + + +:: + + typedef struct { + int state; + int mtype; + int len; + unsigned char* payload; + unsigned char* xaction; + int sub_id; + int tp_state; + } rmr_mbuf_t; + + +Where: + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **state** + - + Is the current buffer state. Following a call to + ``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). When the state is + ``RMR_OK`` the buffer represents an empty buffer that the + application may fill in in preparation to send. + + * - **mtype** + - + When sending a message, the application is expected to set + this field to the appropriate message type value (as + determined by the user programme). Upon send this value + determines how the RMR 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. + + * - **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 indicate the number of bytes + in the payload which are valid. + + * - **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 ``rmr_send, rmr_call`` or + ``rmr_reply`` function call. Once the buffer has been passed + back to a RMR library function the user programme should + **NOT** make use of the payload pointer. + + * - **xaction** + - + The *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 ``rmr_call`` function to send a message + and wait for the reply; the underlying RMR processing expects + that the matching reply message will also contain the same + data in the *xaction* field. + + * - **sub_id** + - + This value is the subscription ID. It, in combination with + the message type is used by rmr to determine the target + endpoint when sending a message. If the application to + application protocol does not warrant the use of a + subscription ID, the RMR constant RMR_VOID_SUBID should be + placed in this field. When an application is forwarding or + returning a buffer to the sender, it is the application's + responsibility to set/reset this value. + + * - **tp_state** + - + For C applications making use of RMR, the state of a + transport based failure will often be available via + ``errno.`` However, some wrapper environments may not have + direct access to the C-lib ``errno`` value. RMR send and + receive operations will place the current value of + ``errno`` into this field which should make it available to + wrapper functions. User applications are strongly cautioned + against relying on the value of errno as some transport + mechanisms may not set this value on all calls. This value + should also be ignored any time the message status is + ``RMR_OK.`` + + RETURN VALUE ------------ -The function returns a pointer to a ``rmr_mbuf`` structure, -or NULL on error. +The function returns a pointer to a ``rmr_mbuf`` structure, +or NULL on error. ERRORS ------ - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **ENOMEM** - - - Unable to allocate memory. - - + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **ENOMEM** + - + Unable to allocate memory. + + SEE ALSO -------- -rmr_tralloc_msg(3), rmr_call(3), rmr_free_msg(3), -rmr_init(3), rmr_init_trace(3), rmr_get_trace(3), -rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3), -rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), -rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), -rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3) +rmr_tralloc_msg(3), rmr_call(3), rmr_free_msg(3), +rmr_init(3), rmr_init_trace(3), rmr_get_trace(3), +rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3), +rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), +rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), +rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3) diff --git a/docs/rmr_bytes2meid.3.rst b/docs/rmr_bytes2meid.3.rst index 3afe3dc..f9e1df6 100644 --- a/docs/rmr_bytes2meid.3.rst +++ b/docs/rmr_bytes2meid.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_bytes2meid -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_bytes2meid +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,65 +19,65 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_bytes2meid +rmr_bytes2meid SYNOPSIS -------- - -:: - - #include - - int rmr_bytes2meid( rmr_mbuf_t* mbuf, unsigned char* src, int len ) - + +:: + + #include + + int rmr_bytes2meid( rmr_mbuf_t* mbuf, unsigned char* src, int len ) + DESCRIPTION ----------- -The ``rmr_bytes2meid`` function will copy up to *len* bytes -from *src* to the managed entity ID (meid) field in the -message. The field is a fixed length, gated by the constant -``RMR_MAX_MEID`` and if len is larger than this value, only -RMR_MAX_MEID bytes will actually be copied. +The ``rmr_bytes2meid`` function will copy up to *len* bytes +from *src* to the managed entity ID (meid) field in the +message. The field is a fixed length, gated by the constant +``RMR_MAX_MEID`` and if len is larger than this value, only +RMR_MAX_MEID bytes will actually be copied. RETURN VALUE ------------ -On success, the actual number of bytes copied is returned, or --1 to indicate a hard error. If the length is less than 0, or -not the same as length passed in, ``errno`` is set to one of -the errors described in the *Errors* section. +On success, the actual number of bytes copied is returned, or +-1 to indicate a hard error. If the length is less than 0, or +not the same as length passed in, ``errno`` is set to one of +the errors described in the *Errors* section. ERRORS ------ -If the returned length does not match the length passed in, -``errno`` will be set to one of the following constants with -the meaning listed below. - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - - * - **EINVAL** - - - The message, or an internal portion of the message, was - corrupted or the pointer was invalid. - - - * - **EOVERFLOW** - - - The length passed in was larger than the maximum length of - the field; only a portion of the source bytes were copied. - - +If the returned length does not match the length passed in, +``errno`` will be set to one of the following constants with +the meaning listed below. + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + + * - **EINVAL** + - + The message, or an internal portion of the message, was + corrupted or the pointer was invalid. + + + * - **EOVERFLOW** + - + The length passed in was larger than the maximum length of + the field; only a portion of the source bytes were copied. + + EXAMPLE @@ -88,10 +88,10 @@ EXAMPLE SEE ALSO -------- -rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_call(3), -rmr_free_msg(3), rmr_get_rcvfd(3), rmr_get_meid(3), -rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), -rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3), -rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3), -rmr_ring_free(3), rmr_str2meid(3), rmr_str2xact(3), -rmr_wh_open(3), rmr_wh_send_msg(3) +rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_call(3), +rmr_free_msg(3), rmr_get_rcvfd(3), rmr_get_meid(3), +rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), +rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3), +rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3), +rmr_ring_free(3), rmr_str2meid(3), rmr_str2xact(3), +rmr_wh_open(3), rmr_wh_send_msg(3) diff --git a/docs/rmr_bytes2payload.3.rst b/docs/rmr_bytes2payload.3.rst index f9dc183..43de0b5 100644 --- a/docs/rmr_bytes2payload.3.rst +++ b/docs/rmr_bytes2payload.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_bytes2payload -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_bytes2payload +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,39 +19,39 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_bytes2payload +rmr_bytes2payload SYNOPSIS -------- - -:: - - #include - - void rmr_bytes2payload( rmr_mbuf_t* mbuf, unsigned char* src, int len ) - + +:: + + #include + + void rmr_bytes2payload( rmr_mbuf_t* mbuf, unsigned char* src, int len ) + DESCRIPTION ----------- -This is a convenience function as some wrapper languages -might not have the ability to directly copy into the payload -buffer. The bytes from *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 -``len`` field in the message buffer is updated to reflect the -number of bytes copied. - -There is little error checking, and no error reporting. +This is a convenience function as some wrapper languages +might not have the ability to directly copy into the payload +buffer. The bytes from *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 +``len`` field in the message buffer is updated to reflect the +number of bytes copied. + +There is little error checking, and no error reporting. RETURN VALUE ------------ -None. +None. EXAMPLE @@ -62,10 +62,10 @@ EXAMPLE SEE ALSO -------- -rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2payload(3), -rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3), -rmr_get_meid(3), rmr_payload_size(3), rmr_send_msg(3), -rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), -rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), -rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3), -rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3) +rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2payload(3), +rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3), +rmr_get_meid(3), rmr_payload_size(3), rmr_send_msg(3), +rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), +rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), +rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3), +rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3) diff --git a/docs/rmr_bytes2xact.3.rst b/docs/rmr_bytes2xact.3.rst index dd99f13..12f29f2 100644 --- a/docs/rmr_bytes2xact.3.rst +++ b/docs/rmr_bytes2xact.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_bytes2xact -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_bytes2xact +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,63 +19,63 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_bytes2xact +rmr_bytes2xact SYNOPSIS -------- - -:: - - #include - - int rmr_bytes2xact( rmr_mbuf_t* mbuf, unsigned char* src, int len ) - + +:: + + #include + + int rmr_bytes2xact( rmr_mbuf_t* mbuf, unsigned char* src, int len ) + DESCRIPTION ----------- -The ``rmr_bytes2xact`` function will copy up to *len* bytes -from *src* to the transaction ID (xaction) field in the -message. The field is a fixed length, gated by the constant -``RMR_MAX_XID`` and if len is larger than this value, only -``RMR_MAX_XID`` bytes will actually be copied. +The ``rmr_bytes2xact`` function will copy up to *len* bytes +from *src* to the transaction ID (xaction) field in the +message. The field is a fixed length, gated by the constant +``RMR_MAX_XID`` and if len is larger than this value, only +``RMR_MAX_XID`` bytes will actually be copied. RETURN VALUE ------------ -On success, the actual number of bytes copied is returned, or --1 to indicate a hard error. If the length is less than 0, or -not the same as length passed in, ``errno`` is set to one of -the errors described in the *Errors* section. +On success, the actual number of bytes copied is returned, or +-1 to indicate a hard error. If the length is less than 0, or +not the same as length passed in, ``errno`` is set to one of +the errors described in the *Errors* section. ERRORS ------ -If the returned length does not match the length passed in, -``errno`` will be set to one of the following constants with -the meaning listed below. - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **EINVAL** - - - The message, or an internal portion of the message, was - corrupted or the pointer was invalid. - - * - **EOVERFLOW** - - - The length passed in was larger than the maximum length of - the field; only a portion of the source bytes were copied. - - +If the returned length does not match the length passed in, +``errno`` will be set to one of the following constants with +the meaning listed below. + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **EINVAL** + - + The message, or an internal portion of the message, was + corrupted or the pointer was invalid. + + * - **EOVERFLOW** + - + The length passed in was larger than the maximum length of + the field; only a portion of the source bytes were copied. + + EXAMPLE @@ -86,10 +86,10 @@ EXAMPLE SEE ALSO -------- -rmr_alloc_msg(3), rmr_bytes2meid(3), rmr_call(3), -rmr_free_msg(3), rmr_get_meid(3), rmr_get_rcvfd(3), -rmr_get_xact(3), rmr_payload_size(3), rmr_send_msg(3), -rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), -rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), -rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3), -rmr_wh_open(3), rmr_wh_send_msg(3) +rmr_alloc_msg(3), rmr_bytes2meid(3), rmr_call(3), +rmr_free_msg(3), rmr_get_meid(3), rmr_get_rcvfd(3), +rmr_get_xact(3), rmr_payload_size(3), rmr_send_msg(3), +rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), +rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), +rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3), +rmr_wh_open(3), rmr_wh_send_msg(3) diff --git a/docs/rmr_call.3.rst b/docs/rmr_call.3.rst index bb02415..a8e02e5 100644 --- a/docs/rmr_call.3.rst +++ b/docs/rmr_call.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_call -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_call +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,227 +19,227 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_call +rmr_call SYNOPSIS -------- - -:: - - #include - - extern rmr_mbuf_t* rmr_call( void* vctx, rmr_mbuf_t* msg ); - + +:: + + #include + + extern rmr_mbuf_t* rmr_call( void* vctx, rmr_mbuf_t* msg ); + DESCRIPTION ----------- -The ``rmr_call`` function sends the user application message -to a remote endpoint, and waits for a corresponding response -message before returning control to the user application. The -user application supplies a completed message buffer, as it -would for a ``rmr_send`` call, but unlike with the send, the -buffer returned will have the response from the application -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 the order received, one per call to -``rmr_rcv_msg.`` +The ``rmr_call`` function sends the user application message +to a remote endpoint, and waits for a corresponding response +message before returning control to the user application. The +user application supplies a completed message buffer, as it +would for a ``rmr_send`` call, but unlike with the send, the +buffer returned will have the response from the application +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 the order received, one per call to +``rmr_rcv_msg.`` Call Timeout ------------ -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 -received messages which are not the response. Using a -mechanism which is not time based for *timeout* prevents the -async queue from filling (which would lead to message drops) -in an environment where there is heavy message traffic. - -When the threshold number of messages have been queued -without receiving a response message, 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. +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 +received messages which are not the response. Using a +mechanism which is not time based for *timeout* prevents the +async queue from filling (which would lead to message drops) +in an environment where there is heavy message traffic. + +When the threshold number of messages have been queued +without receiving a response message, 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. Retries ------- -The send operations in RMR will retry *soft* send failures -until one of three conditions occurs: - - -* The message is sent without error - -* The underlying transport reports a *hard* failure - -* The maximum number of retry loops has been attempted - - -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 -allowing the user application to completely disable retires -(set to 0), or to increase the number of retry loops. +The send operations in RMR will retry *soft* send failures +until one of three conditions occurs: + + +* The message is sent without error + +* The underlying transport reports a *hard* failure + +* The maximum number of retry loops has been attempted + + +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 +allowing the user application to completely disable retires +(set to 0), or to increase the number of retry loops. Transport Level Blocking ------------------------ -The underlying transport mechanism used to send messages is -configured in *non-blocking* mode. This means that if a -message cannot be sent immediately the transport mechanism -will **not** pause with the assumption that the inability to -send will clear quickly (within a few milliseconds). This -means that when the retry loop is completely disabled (set to -0), that the failure to accept a message for sending by the -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 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. +The underlying transport mechanism used to send messages is +configured in *non-blocking* mode. This means that if a +message cannot be sent immediately the transport mechanism +will **not** pause with the assumption that the inability to +send will clear quickly (within a few milliseconds). This +means that when the retry loop is completely disabled (set to +0), that the failure to accept a message for sending by the +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 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 ------------ -The ``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 nil -pointer will be returned; when this is the case only *errno* -will be available to describe the reason for failure. +The ``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 nil +pointer will be returned; when this is the case only *errno* +will be available to describe the reason for failure. ERRORS ------ -These values are reflected in the state field of the returned -message. - - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **RMR_OK** - - - The call was successful and the message buffer references the - response message. - - * - **RMR_ERR_CALLFAILED** - - - The call failed and the value of *errno,* as described below, - should be checked for the specific reason. - - - -The global "variable" *errno* will be set to one of the -following values if the overall call processing was not -successful. - - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **ETIMEDOUT** - - - Too many messages were queued before receiving the expected - response - - * - **ENOBUFS** - - - The queued message ring is full, messages were dropped - - * - **EINVAL** - - - A parameter was not valid - - * - **EAGAIN** - - - 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. - - +These values are reflected in the state field of the returned +message. + + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **RMR_OK** + - + The call was successful and the message buffer references the + response message. + + * - **RMR_ERR_CALLFAILED** + - + The call failed and the value of *errno,* as described below, + should be checked for the specific reason. + + + +The global "variable" *errno* will be set to one of the +following values if the overall call processing was not +successful. + + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **ETIMEDOUT** + - + Too many messages were queued before receiving the expected + response + + * - **ENOBUFS** + - + The queued message ring is full, messages were dropped + + * - **EINVAL** + - + A parameter was not valid + + * - **EAGAIN** + - + 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 snippet shows one way of using the -``rmr_call`` function, and illustrates how the transaction ID -must be set. - - -:: - - int retries_left = 5; // max retries on dev not available - int retry_delay = 50000; // retry delay (usec) - static rmr_mbuf_t* mbuf = NULL; // response msg - msg_t* pm; // application struct for payload - - // get a send buffer and reference the payload - mbuf = rmr_alloc_msg( mr, sizeof( pm->req ) ); - pm = (msg_t*) mbuf->payload; - - // 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 && - mbuf->state != RMR_OK ) { - - usleep( retry_delay ); - } - - if( mbuf == NULL || mbuf->state != RMR_OK ) { - rmr_free_msg( mbuf ); // safe if nil - return NULL; - } - } - - // do something with mbuf - +The following code snippet shows one way of using the +``rmr_call`` function, and illustrates how the transaction ID +must be set. + + +:: + + int retries_left = 5; // max retries on dev not available + int retry_delay = 50000; // retry delay (usec) + static rmr_mbuf_t* mbuf = NULL; // response msg + msg_t* pm; // application struct for payload + + // get a send buffer and reference the payload + mbuf = rmr_alloc_msg( mr, sizeof( pm->req ) ); + pm = (msg_t*) mbuf->payload; + + // 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 && + mbuf->state != RMR_OK ) { + + usleep( retry_delay ); + } + + if( mbuf == NULL || mbuf->state != RMR_OK ) { + rmr_free_msg( mbuf ); // safe if nil + return NULL; + } + } + + // do something with mbuf + SEE ALSO -------- -rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3), -rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), -rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3), -rmr_fib(3), rmr_has_str(3), rmr_set_stimeout(3), -rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3) +rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3), +rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), +rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3), +rmr_fib(3), rmr_has_str(3), rmr_set_stimeout(3), +rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3) diff --git a/docs/rmr_close.3.rst b/docs/rmr_close.3.rst index ae0af1d..2ddc025 100644 --- a/docs/rmr_close.3.rst +++ b/docs/rmr_close.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_close -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_close +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,38 +19,38 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_close +rmr_close SYNOPSIS -------- - -:: - - #include - - void rmr_close( void* vctx ) - + +:: + + #include + + void rmr_close( void* vctx ) + DESCRIPTION ----------- -The ``rmr_close`` function closes the listen socket -effectively cutting the application off. 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. - +The ``rmr_close`` function closes the listen socket +effectively cutting the application off. 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. + SEE ALSO -------- -rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), -rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3), -rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), -rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), -rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_open(3), -rmr_wh_send_msg(3) +rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), +rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3), +rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), +rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), +rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_open(3), +rmr_wh_send_msg(3) diff --git a/docs/rmr_free_msg.3.rst b/docs/rmr_free_msg.3.rst index b35905c..833dc28 100644 --- a/docs/rmr_free_msg.3.rst +++ b/docs/rmr_free_msg.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_free_msg -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_free_msg +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,41 +19,41 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_free_msg +rmr_free_msg SYNOPSIS -------- - -:: - - #include - - void rmr_free_msg( rmr_mbuf_t* mbuf ); - + +:: + + #include + + void rmr_free_msg( rmr_mbuf_t* mbuf ); + 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 to be used. It is safe to pass a -nil pointer to this function, and doing so does not result in -a change to the value of ``errrno.`` - -After calling, the user application should **not** use any of -the pointers (transaction ID, or payload) which were -available. +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 to be used. It is safe to pass a +nil pointer to this function, and doing so does not result in +a change to the value of ``errrno.`` + +After calling, the user application should **not** use any of +the pointers (transaction ID, or payload) which were +available. SEE ALSO -------- -rmr_alloc_msg(3), rmr_call(3), rmr_init(3), -rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), -rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3), -rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3), -rmr_ring_free(3) +rmr_alloc_msg(3), rmr_call(3), rmr_init(3), +rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), +rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3), +rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3), +rmr_ring_free(3) diff --git a/docs/rmr_get_const.3.rst b/docs/rmr_get_const.3.rst index 83f91df..f39465c 100644 --- a/docs/rmr_get_const.3.rst +++ b/docs/rmr_get_const.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_get_const -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_get_const +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,55 +19,55 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_get_const +rmr_get_const SYNOPSIS -------- - -:: - - #include - - unsigned char* rmr_get_const(); - + +:: + + #include + + unsigned char* rmr_get_const(); + DESCRIPTION ----------- -The ``rmr_get_const`` function is a convenience function for -wrappers which do not have the ability to "compile in" RMR -constants. The function will build a nil terminated string -containing JSON which defines the RMR constants that C and Go -applications have at compile time via the ``rmr.h`` header -file. - -All values are represented as strings and the JSON format is -illustrated in the following (partial) example: - - -:: - - { - "RMR_MAX_XID": "32", - "RMR_OK": "0", - "RMR_ERR_BADARG", "1", - "RMR_ERR_NOENDPT" "2" - } - +The ``rmr_get_const`` function is a convenience function for +wrappers which do not have the ability to "compile in" RMR +constants. The function will build a nil terminated string +containing JSON which defines the RMR constants that C and Go +applications have at compile time via the ``rmr.h`` header +file. + +All values are represented as strings and the JSON format is +illustrated in the following (partial) example: + + +:: + + { + "RMR_MAX_XID": "32", + "RMR_OK": "0", + "RMR_ERR_BADARG", "1", + "RMR_ERR_NOENDPT" "2" + } + RETURN VALUE ------------ -On success, a pointer to a string containing the JSON -defining constant and value pairs. On failure a nil pointer -is returned. +On success, a pointer to a string containing the JSON +defining constant and value pairs. On failure a nil pointer +is returned. SEE ALSO -------- -rmr(7) +rmr(7) diff --git a/docs/rmr_get_meid.3.rst b/docs/rmr_get_meid.3.rst index d97cfd9..0f03d6e 100644 --- a/docs/rmr_get_meid.3.rst +++ b/docs/rmr_get_meid.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_get_meid -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_get_meid +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,74 +19,74 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_get_meid +rmr_get_meid SYNOPSIS -------- - -:: - - #include - - char* rmr_get_meid( rmr_mbuf_t* mbuf, unsigned char* dest ) - + +:: + + #include + + char* rmr_get_meid( rmr_mbuf_t* mbuf, unsigned char* dest ) + DESCRIPTION ----------- -The ``rmr_get_meid`` function will copy the managed entity ID -(meid) field from the message into the *dest* buffer provided -by the user. The buffer referenced by *dest* is assumed to be -at least ``RMR_MAX_MEID`` bytes in length. If *dest* is NULL, -then a buffer is allocated (the calling application is -expected to free when the buffer is no longer needed). +The ``rmr_get_meid`` function will copy the managed entity ID +(meid) field from the message into the *dest* buffer provided +by the user. The buffer referenced by *dest* is assumed to be +at least ``RMR_MAX_MEID`` bytes in length. If *dest* is NULL, +then a buffer is allocated (the calling application is +expected to free when the buffer is no longer needed). RETURN VALUE ------------ -On success, a pointer to the extracted string is returned. If -*dest* was supplied, then this is just a pointer to the -caller's buffer. If *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. +On success, a pointer to the extracted string is returned. If +*dest* was supplied, then this is just a pointer to the +caller's buffer. If *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. ERRORS ------ -If an error occurs, the value of the global variable -``errno`` will be set to one of the following with the -indicated meaning. - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **EINVAL** - - - The message, or an internal portion of the message, was - corrupted or the pointer was invalid. - - * - **ENOMEM** - - - A nil pointer was passed for *dest,* however it was not - possible to allocate a buffer using malloc(). - - +If an error occurs, the value of the global variable +``errno`` will be set to one of the following with the +indicated meaning. + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **EINVAL** + - + The message, or an internal portion of the message, was + corrupted or the pointer was invalid. + + * - **ENOMEM** + - + A nil pointer was passed for *dest,* however it was not + possible to allocate a buffer using malloc(). + + SEE ALSO -------- -rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3), -rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3), -rmr_get_xact(3), rmr_payload_size(3), rmr_send_msg(3), -rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), -rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), -rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3), -rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3) +rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3), +rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3), +rmr_get_xact(3), rmr_payload_size(3), rmr_send_msg(3), +rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), +rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), +rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3), +rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3) diff --git a/docs/rmr_get_rcvfd.3.rst b/docs/rmr_get_rcvfd.3.rst index 8a6bcd2..3a3e270 100644 --- a/docs/rmr_get_rcvfd.3.rst +++ b/docs/rmr_get_rcvfd.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_get_rcvfd -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_get_rcvfd +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,117 +19,117 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_get_rcvfd +rmr_get_rcvfd SYNOPSIS -------- - -:: - - #include - - void* rmr_get_rcvfd( void* ctx ) - + +:: + + #include + + void* rmr_get_rcvfd( void* ctx ) + DESCRIPTION ----------- -The ``rmr_get_rcvfd`` function returns a file descriptor -which may be given to epoll_wait() 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. - -The context (ctx) pointer passed in is the pointer returned -by the call to rmr_init(). +The ``rmr_get_rcvfd`` function returns a file descriptor +which may be given to epoll_wait() 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. + +The context (ctx) pointer passed in is the pointer returned +by the call to rmr_init(). RETURN VALUE ------------ -The ``rmr_get_rcvfd`` function returns a file descriptor -greater or equal to 0 on success and -1 on error. +The ``rmr_get_rcvfd`` function returns a file descriptor +greater or equal to 0 on success and -1 on error. ERRORS ------ -The following error values are specifically set by this RMR -function. In some cases the error message of a system call is -propagated up, and thus this list might be incomplete. - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **EINVAL** - - - The use of this function is invalid in this environment. - - +The following error values are specifically set by this RMR +function. In some cases the error message of a system call is +propagated up, and thus this list might be incomplete. + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **EINVAL** + - + The use of this function is invalid in this environment. + + EXAMPLE ------- -The following short code bit illustrates the use of this -function. Error checking has been omitted for clarity. - - -:: - - #include - #include - #include - #include - - int main() { - int rcv_fd; // pollable fd - void* mrc; //msg router context - struct epoll_event events[10]; // support 10 events to poll - struct epoll_event epe; // event definition for event to listen to - int ep_fd = -1; - rmr_mbuf_t* msg = NULL; - int nready; - int i; - int norm_msg_size = 1500; // 95% messages are less than this - - mrc = rmr_init( "43086", norm_msg_size, RMRFL_NONE ); - rcv_fd = rmr_get_rcvfd( mrc ); - - 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 - msg = rmr_rcv_msg( mrc, msg ); - if( msg ) { - // do something with msg - } - } - - // check for other ready fds.... - } - } - } - +The following short code bit illustrates the use of this +function. Error checking has been omitted for clarity. + + +:: + + #include + #include + #include + #include + + int main() { + int rcv_fd; // pollable fd + void* mrc; //msg router context + struct epoll_event events[10]; // support 10 events to poll + struct epoll_event epe; // event definition for event to listen to + int ep_fd = -1; + rmr_mbuf_t* msg = NULL; + int nready; + int i; + int norm_msg_size = 1500; // 95% messages are less than this + + mrc = rmr_init( "43086", norm_msg_size, RMRFL_NONE ); + rcv_fd = rmr_get_rcvfd( mrc ); + + 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 + msg = rmr_rcv_msg( mrc, msg ); + if( msg ) { + // do something with msg + } + } + + // check for other ready fds.... + } + } + } + SEE ALSO -------- -rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), -rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), -rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3), -rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3), -rmr_ring_free(3) +rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), +rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), +rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3), +rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3), +rmr_ring_free(3) diff --git a/docs/rmr_get_src.3.rst b/docs/rmr_get_src.3.rst index 37f9f74..936e570 100644 --- a/docs/rmr_get_src.3.rst +++ b/docs/rmr_get_src.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_get_src -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_get_src +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,74 +19,74 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_get_src +rmr_get_src SYNOPSIS -------- - -:: - - #include - - unsigned char* rmr_get_src( rmr_mbuf_t* mbuf, unsigned char* dest ) - + +:: + + #include + + unsigned char* rmr_get_src( rmr_mbuf_t* mbuf, unsigned char* dest ) + DESCRIPTION ----------- -The ``rmr_get_src`` function will copy the *source* -information from the message to a buffer (dest) supplied by -the user. In an RMR message, the source is the sender's -information that is used for return to sender function calls, -and is generally the hostname and port in the form *name*. -The source might be an IP address port combination; the data -is populated by the sending process and the only requirement -is that it be capable of being used to start a TCP session -with the sender. - -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 ``rmr_get_src`` function will copy the *source* +information from the message to a buffer (dest) supplied by +the user. In an RMR message, the source is the sender's +information that is used for return to sender function calls, +and is generally the hostname and port in the form *name*. +The source might be an IP address port combination; the data +is populated by the sending process and the only requirement +is that it be capable of being used to start a TCP session +with the sender. + +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. RETURN VALUE ------------ -On success, a pointer to the destination buffer is given as a -convenience to the user programme. On failure, a nil pointer -is returned and the value of errno is set. +On success, a pointer to the destination buffer is given as a +convenience to the user programme. On failure, a nil pointer +is returned and the value of errno is set. ERRORS ------ -If an error occurs, the value of the global variable -``errno`` will be set to one of the following with the -indicated meaning. - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **EINVAL** - - - The message, or an internal portion of the message, was - corrupted or the pointer was invalid. - - +If an error occurs, the value of the global variable +``errno`` will be set to one of the following with the +indicated meaning. + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **EINVAL** + - + The message, or an internal portion of the message, was + corrupted or the pointer was invalid. + + SEE ALSO -------- -rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3), -rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3), -rmr_get_srcip(3), rmr_payload_size(3), rmr_send_msg(3), -rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), -rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), -rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3), -rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3) +rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3), +rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3), +rmr_get_srcip(3), rmr_payload_size(3), rmr_send_msg(3), +rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), +rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), +rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3), +rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3) diff --git a/docs/rmr_get_srcip.3.rst b/docs/rmr_get_srcip.3.rst index 88785ed..b47ac8b 100644 --- a/docs/rmr_get_srcip.3.rst +++ b/docs/rmr_get_srcip.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_get_srcip -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_get_srcip +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,77 +19,77 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_get_srcip +rmr_get_srcip SYNOPSIS -------- - -:: - - #include - - unsigned char* rmr_get_srcip( rmr_mbuf_t* mbuf, unsigned char* dest ) - + +:: + + #include + + unsigned char* rmr_get_srcip( rmr_mbuf_t* mbuf, unsigned char* dest ) + DESCRIPTION ----------- -The ``rmr_get_srcip`` function will copy the *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. The address is maintained as IP:port where *IP* -could be either an IPv6 or IPv4 address depending on what was -provided by the sending application. - -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 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. +The ``rmr_get_srcip`` function will copy the *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. The address is maintained as IP:port where *IP* +could be either an IPv6 or IPv4 address depending on what was +provided by the sending application. + +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 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. RETURN VALUE ------------ -On success, a pointer to the destination buffer is given as a -convenience to the user programme. On failure, a nil pointer -is returned and the value of errno is set. +On success, a pointer to the destination buffer is given as a +convenience to the user programme. On failure, a nil pointer +is returned and the value of errno is set. ERRORS ------ -If an error occurs, the value of the global variable -``errno`` will be set to one of the following with the -indicated meaning. - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **EINVAL** - - - The message, or an internal portion of the message, was - corrupted or the pointer was invalid. - - +If an error occurs, the value of the global variable +``errno`` will be set to one of the following with the +indicated meaning. + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **EINVAL** + - + The message, or an internal portion of the message, was + corrupted or the pointer was invalid. + + SEE ALSO -------- -rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3), -rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3), -rmr_get_src(3), rmr_payload_size(3), rmr_send_msg(3), -rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), -rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), -rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3), -rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3) +rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3), +rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3), +rmr_get_src(3), rmr_payload_size(3), rmr_send_msg(3), +rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), +rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), +rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3), +rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3) diff --git a/docs/rmr_get_trace.3.rst b/docs/rmr_get_trace.3.rst index 2c27b8d..0f1fc8b 100644 --- a/docs/rmr_get_trace.3.rst +++ b/docs/rmr_get_trace.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_get_trace -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_get_trace +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,49 +19,49 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_get_trace +rmr_get_trace SYNOPSIS -------- - -:: - - #include - - int rmr_get_trace( rmr_mbuf_t* mbuf, unsigned char* dest, int size ) - + +:: + + #include + + int rmr_get_trace( rmr_mbuf_t* mbuf, unsigned char* dest, int size ) + DESCRIPTION ----------- -The ``rmr_get_trace`` function will copy the trace -information from the message into the user's allocated memory -referenced by ``dest.`` The ``size`` parameter is assumed to -be the maximum number of bytes which can be copied (size of -the destination buffer). +The ``rmr_get_trace`` function will copy the trace +information from the message into the user's allocated memory +referenced by ``dest.`` The ``size`` parameter is assumed to +be the maximum number of bytes which can be copied (size of +the destination buffer). RETURN VALUE ------------ -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. +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. SEE ALSO -------- -rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3), -rmr_bytes2meid(3), rmr_call(3), rmr_free_msg(3), -rmr_get_rcvfd(3), rmr_get_trlen(3), rmr_init(3), -rmr_init_trace(3), rmr_payload_size(3), rmr_send_msg(3), -rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), -rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), -rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3), -rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3), -rmr_set_trace(3), rmr_trace_ref(3) +rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3), +rmr_bytes2meid(3), rmr_call(3), rmr_free_msg(3), +rmr_get_rcvfd(3), rmr_get_trlen(3), rmr_init(3), +rmr_init_trace(3), rmr_payload_size(3), rmr_send_msg(3), +rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), +rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), +rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3), +rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3), +rmr_set_trace(3), rmr_trace_ref(3) diff --git a/docs/rmr_get_trlen.3.rst b/docs/rmr_get_trlen.3.rst index c438157..81430ae 100644 --- a/docs/rmr_get_trlen.3.rst +++ b/docs/rmr_get_trlen.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_get_trlen -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_get_trlen +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,58 +19,58 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_get_trlen +rmr_get_trlen SYNOPSIS -------- - -:: - - #include - - int rmr_get_trlen( rmr_mbuf_t* msg ); - + +:: + + #include + + int rmr_get_trlen( rmr_mbuf_t* msg ); + DESCRIPTION ----------- -Given a message buffer, this function returns the amount of -space (bytes) that have been allocated for trace data. If no -trace data has been allocated, then 0 is returned. +Given a message buffer, this function returns the amount of +space (bytes) that have been allocated for trace data. If no +trace data has been allocated, then 0 is returned. RETURN VALUE ------------ -The number of bytes allocated for trace information in the -given message. +The number of bytes allocated for trace information in the +given message. ERRORS ------ - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **INVAL** - - - Parameter(s) passed to the function were not valid. - - + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **INVAL** + - + Parameter(s) passed to the function were not valid. + + SEE ALSO -------- -rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), -rmr_get_trace(3), rmr_init(3), rmr_init_trace(3), -rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3), -rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3), -rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3), -rmr_set_trace(3), rmr_tralloc_msg(3) +rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), +rmr_get_trace(3), rmr_init(3), rmr_init_trace(3), +rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3), +rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3), +rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3), +rmr_set_trace(3), rmr_tralloc_msg(3) diff --git a/docs/rmr_get_xact.3.rst b/docs/rmr_get_xact.3.rst index 887d654..409b158 100644 --- a/docs/rmr_get_xact.3.rst +++ b/docs/rmr_get_xact.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_get_xact -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_get_xact +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,74 +19,74 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_get_xact +rmr_get_xact SYNOPSIS -------- - -:: - - #include - - char* rmr_get_xact( rmr_mbuf_t* mbuf, unsigned char* dest ) - + +:: + + #include + + char* rmr_get_xact( rmr_mbuf_t* mbuf, unsigned char* dest ) + DESCRIPTION ----------- -The ``rmr_get_xact`` function will copy the transaction field -from the message into the *dest* buffer provided by the user. -The buffer referenced by *dest* is assumed to be at least -``RMR_MAX_XID`` bytes in length. If *dest* is NULL, then a -buffer is allocated (the calling application is expected to -free when the buffer is no longer needed). +The ``rmr_get_xact`` function will copy the transaction field +from the message into the *dest* buffer provided by the user. +The buffer referenced by *dest* is assumed to be at least +``RMR_MAX_XID`` bytes in length. If *dest* is NULL, then a +buffer is allocated (the calling application is expected to +free when the buffer is no longer needed). RETURN VALUE ------------ -On success, a pointer to the extracted string is returned. If -*dest* was supplied, then this is just a pointer to the -caller's buffer. If *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. +On success, a pointer to the extracted string is returned. If +*dest* was supplied, then this is just a pointer to the +caller's buffer. If *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. ERRORS ------ -If an error occurs, the value of the global variable -``errno`` will be set to one of the following with the -indicated meaning. - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **EINVAL** - - - The message, or an internal portion of the message, was - corrupted or the pointer was invalid. - - * - **ENOMEM** - - - A nil pointer was passed for *dest,* however it was not - possible to allocate a buffer using malloc(). - - +If an error occurs, the value of the global variable +``errno`` will be set to one of the following with the +indicated meaning. + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **EINVAL** + - + The message, or an internal portion of the message, was + corrupted or the pointer was invalid. + + * - **ENOMEM** + - + A nil pointer was passed for *dest,* however it was not + possible to allocate a buffer using malloc(). + + SEE ALSO -------- -rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3), -rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3), -rmr_get_meid(3), rmr_payload_size(3), rmr_send_msg(3), -rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), -rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), -rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3), -rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3) +rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3), +rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3), +rmr_get_meid(3), rmr_payload_size(3), rmr_send_msg(3), +rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), +rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), +rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3), +rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3) diff --git a/docs/rmr_init.3.rst b/docs/rmr_init.3.rst index ef830f2..d229a2a 100644 --- a/docs/rmr_init.3.rst +++ b/docs/rmr_init.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_init -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_init +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,364 +19,364 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_init +rmr_init SYNOPSIS -------- - -:: - - #include - - void* rmr_init( char* proto_port, int norm_msg_size, int flags ); - + +:: + + #include + + void* rmr_init( char* proto_port, int norm_msg_size, int flags ); + DESCRIPTION ----------- -The ``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 send messages. - -*Port* is used to listen for connection requests from other -RMR based applications. The *norm_msg_size* parameter is used -to allocate receive buffers and should be set to what the -user application expects to be a size which will hold the -vast majority of expected messages. When computing the size, -the application should consider the usual payload size -**and** the maximum trace data size that will be used. This -value is also used as the default message size when -allocating message buffers (when a zero size is given to -rmr_alloc_msg(); see the rmr_alloc_msg() manual page). -Messages arriving which are longer than the given normal size -will cause RMR to allocate a new buffer which is large enough -for the arriving message. - -Starting with version 3.8.0 RMR no longer places a maximum -buffer size for received messages. The underlying system -memory manager might impose such a limit and the attempt to -allocate a buffer larger than that limit will likely result -in an application abort. Other than the potential performance -impact from extra memory allocation and release, there is no -penality to the user programme for specifyning a normal -buffer size which is usually smaller than received buffers. -Similarly, the only penality to the application for over -specifying the normal buffer size might be a larger memory -footprint. - -*Flags* allows for selection of some RMR options at the time -of initialisation. These are set by ORing ``RMRFL`` constants -from the RMR header file. Currently the following flags are -supported: - - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **RMRFL_NONE** - - - No flags are set. - - - * - **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. - - - * - **RMRFL_MTCALL** - - - Enable multi-threaded call support. - - - * - **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. - - +The ``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 send messages. + +*Port* is used to listen for connection requests from other +RMR based applications. The *norm_msg_size* parameter is used +to allocate receive buffers and should be set to what the +user application expects to be a size which will hold the +vast majority of expected messages. When computing the size, +the application should consider the usual payload size +**and** the maximum trace data size that will be used. This +value is also used as the default message size when +allocating message buffers (when a zero size is given to +rmr_alloc_msg(); see the rmr_alloc_msg() manual page). +Messages arriving which are longer than the given normal size +will cause RMR to allocate a new buffer which is large enough +for the arriving message. + +Starting with version 3.8.0 RMR no longer places a maximum +buffer size for received messages. The underlying system +memory manager might impose such a limit and the attempt to +allocate a buffer larger than that limit will likely result +in an application abort. Other than the potential performance +impact from extra memory allocation and release, there is no +penality to the user programme for specifyning a normal +buffer size which is usually smaller than received buffers. +Similarly, the only penality to the application for over +specifying the normal buffer size might be a larger memory +footprint. + +*Flags* allows for selection of some RMR options at the time +of initialisation. These are set by ORing ``RMRFL`` constants +from the RMR header file. Currently the following flags are +supported: + + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **RMRFL_NONE** + - + No flags are set. + + + * - **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. + + + * - **RMRFL_MTCALL** + - + Enable multi-threaded call support. + + + * - **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. + + Multi-threaded Calling ---------------------- -The support for an application to issue a *blocking call* by -the ``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. 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. The -additional support is implemented with the *rmr_mt_call()* -and *rmr_mt_rcv()* function calls. - -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 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" to this approach. - +The support for an application to issue a *blocking call* by +the ``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. 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. The +additional support is implemented with the *rmr_mt_call()* +and *rmr_mt_rcv()* function calls. + +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 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" to this approach. + ENVIRONMENT ----------- -As a part of the initialisation process ``rmr_init`` reads -environment variables to configure itself. The following -variables are used if found. - - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **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 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. - - * - **RMR_CTL_PORT** - - - This variable defines the port that RMR should open for - communications with Route Manager, and other RMR control - applications. If not defined, the port 4561 is assumed. - - Previously, the ``RMR_RTG_SVC`` (route table generator - service port) was used to define this port. However, a future - version of Route Manager will require RMR to connect and - request tables, thus that variable is now used to supply the - Route Manager's well-known address and port. - - 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 manager is - used (routemgr:4561). - - When ``RMR_CTL_PORT`` is **undefined:** RMR assumes that - Route Manager will connect and push table updates, thus the - default listen port (4561) is used. - - To avoid any possible misinterpretation and/or incorrect - assumptions on the part of RMR, it is recommended that both - the ``RMR_CTL_PORT`` and ``RMR_RTG_SVC`` be defined. In the - case where both variables are defined, RMR will behave - exactly as is communicated with the variable's values. - - * - **RMR_RTG_SVC** - - - The value of this variable depends on the Route Manager in - use. - - When the Route Manager is expecting to connect to an xAPP and - push route tables, this variable must indicate the - ``port`` which RMR should use to listen for these - connections. - - When the Route Manager is expecting RMR to connect and - request a table update during initialisation, the variable - should be the ``host`` of the Route Manager process. - - The ``RMR_CTL_PORT`` variable (added with the support of - sending table update requests to Route manager), controls the - behaviour if this variable is not set. See the description of - that variable for details. - - * - **RMR_HR_LOG** - - - By default RMR writes messages to standard error (incorrectly - referred to as log messages) in human readable format. If - this environment variable is set to 0, the format of standard - error messages might be written in some format not easily - read by humans. If missing, a value of 1 is assumed. - - * - **RMR_LOG_VLEVEL** - - - This is a numeric value which corresponds to the verbosity - level used to limit messages written to standard error. The - lower the number the less chatty RMR functions are during - execution. The following is the current relationship between - the value set on this variable and the messages written: - - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **0** - - - Off; no messages of any sort are written. - - * - **1** - - - Only critical messages are written (default if this variable - does not exist) - - * - **2** - - - Errors and all messages written with a lower value. - - * - **3** - - - Warnings and all messages written with a lower value. - - * - **4** - - - Informational and all messages written with a lower value. - - * - **5** - - - Debugging mode -- all messages written, however this requires - RMR to have been compiled with debugging support enabled. - - - - * - **RMR_RTG_ISRAW** - - - **Deprecated.** Should be set to 1 if the route table - generator is sending "plain" messages (not using RMR to send - messages), 0 if the RTG is using RMR to send. The default is - 1 as we don't expect the RTG to use RMR. - - This variable is only recognised when using the NNG transport - library as it is not possible to support NNG "raw" - communications with other transport libraries. It is also - necessary to match the value of this variable with the - capabilities of the Route Manager; at some point in the - future RMR will assume that all Route Manager messages will - arrive via an RMR connection and will ignore this variable. - - * - **RMR_SEED_RT** - - - This is used to supply a static route table which can be used - for debugging, testing, or if no route table generator - process is being used to supply the route table. If not - defined, no static table is used and RMR will not report - *ready* until a table is received. The static route table may - contain both the route table (between newrt start and end - records), and the MEID map (between meid_map start and end - records). - - * - **RMR_SRC_ID** - - - This is either the name or IP address which is placed into - outbound messages as the message source. This will used when - an RMR based application uses the rmr_rts_msg() function to - return a response to the sender. If not supplied RMR will use - the hostname which in some container environments might not - be routable. - - The value of this variable is also used for Route Manager - messages which are sent via an RMR connection. - - * - **RMR_VCTL_FILE** - - - This supplies the name of a verbosity control file. The core - RMR functions do not produce messages unless there is a - critical failure. However, the route table collection thread, - not a part of the main message processing component, can - write additional messages to standard error. If this variable - is set, RMR will extract the verbosity level for these - messages (0 is silent) from the first line of the file. - Changes to the file are detected and thus the level can be - changed dynamically, however RMR will only suss out this - variable during initialisation, so it is impossible to enable - verbosity after startup. - - * - **RMR_WARNINGS** - - - If set to 1, RMR will write some warnings which are - non-performance impacting. If the variable is not defined, or - set to 0, RMR will not write these additional warnings. - - +As a part of the initialisation process ``rmr_init`` reads +environment variables to configure itself. The following +variables are used if found. + + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **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 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. + + * - **RMR_CTL_PORT** + - + This variable defines the port that RMR should open for + communications with Route Manager, and other RMR control + applications. If not defined, the port 4561 is assumed. + + Previously, the ``RMR_RTG_SVC`` (route table generator + service port) was used to define this port. However, a future + version of Route Manager will require RMR to connect and + request tables, thus that variable is now used to supply the + Route Manager's well-known address and port. + + 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 manager is + used (routemgr:4561). + + When ``RMR_CTL_PORT`` is **undefined:** RMR assumes that + Route Manager will connect and push table updates, thus the + default listen port (4561) is used. + + To avoid any possible misinterpretation and/or incorrect + assumptions on the part of RMR, it is recommended that both + the ``RMR_CTL_PORT`` and ``RMR_RTG_SVC`` be defined. In the + case where both variables are defined, RMR will behave + exactly as is communicated with the variable's values. + + * - **RMR_RTG_SVC** + - + The value of this variable depends on the Route Manager in + use. + + When the Route Manager is expecting to connect to an xAPP and + push route tables, this variable must indicate the + ``port`` which RMR should use to listen for these + connections. + + When the Route Manager is expecting RMR to connect and + request a table update during initialisation, the variable + should be the ``host`` of the Route Manager process. + + The ``RMR_CTL_PORT`` variable (added with the support of + sending table update requests to Route manager), controls the + behaviour if this variable is not set. See the description of + that variable for details. + + * - **RMR_HR_LOG** + - + By default RMR writes messages to standard error (incorrectly + referred to as log messages) in human readable format. If + this environment variable is set to 0, the format of standard + error messages might be written in some format not easily + read by humans. If missing, a value of 1 is assumed. + + * - **RMR_LOG_VLEVEL** + - + This is a numeric value which corresponds to the verbosity + level used to limit messages written to standard error. The + lower the number the less chatty RMR functions are during + execution. The following is the current relationship between + the value set on this variable and the messages written: + + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **0** + - + Off; no messages of any sort are written. + + * - **1** + - + Only critical messages are written (default if this variable + does not exist) + + * - **2** + - + Errors and all messages written with a lower value. + + * - **3** + - + Warnings and all messages written with a lower value. + + * - **4** + - + Informational and all messages written with a lower value. + + * - **5** + - + Debugging mode -- all messages written, however this requires + RMR to have been compiled with debugging support enabled. + + + + * - **RMR_RTG_ISRAW** + - + **Deprecated.** Should be set to 1 if the route table + generator is sending "plain" messages (not using RMR to send + messages), 0 if the RTG is using RMR to send. The default is + 1 as we don't expect the RTG to use RMR. + + This variable is only recognised when using the NNG transport + library as it is not possible to support NNG "raw" + communications with other transport libraries. It is also + necessary to match the value of this variable with the + capabilities of the Route Manager; at some point in the + future RMR will assume that all Route Manager messages will + arrive via an RMR connection and will ignore this variable. + + * - **RMR_SEED_RT** + - + This is used to supply a static route table which can be used + for debugging, testing, or if no route table generator + process is being used to supply the route table. If not + defined, no static table is used and RMR will not report + *ready* until a table is received. The static route table may + contain both the route table (between newrt start and end + records), and the MEID map (between meid_map start and end + records). + + * - **RMR_SRC_ID** + - + This is either the name or IP address which is placed into + outbound messages as the message source. This will used when + an RMR based application uses the rmr_rts_msg() function to + return a response to the sender. If not supplied RMR will use + the hostname which in some container environments might not + be routable. + + The value of this variable is also used for Route Manager + messages which are sent via an RMR connection. + + * - **RMR_VCTL_FILE** + - + This supplies the name of a verbosity control file. The core + RMR functions do not produce messages unless there is a + critical failure. However, the route table collection thread, + not a part of the main message processing component, can + write additional messages to standard error. If this variable + is set, RMR will extract the verbosity level for these + messages (0 is silent) from the first line of the file. + Changes to the file are detected and thus the level can be + changed dynamically, however RMR will only suss out this + variable during initialisation, so it is impossible to enable + verbosity after startup. + + * - **RMR_WARNINGS** + - + If set to 1, RMR will write some warnings which are + non-performance impacting. If the variable is not defined, or + set to 0, RMR will not write these additional warnings. + + RETURN VALUE ------------ -The ``rmr_init`` function returns a void pointer (a context -if you will) that is passed as the first parameter to nearly -all other RMR functions. If ``rmr_init`` is unable to -properly initialise the environment, NULL is returned and -errno is set to an appropriate value. +The ``rmr_init`` function returns a void pointer (a context +if you will) that is passed as the first parameter to nearly +all other RMR functions. If ``rmr_init`` is unable to +properly initialise the environment, NULL is returned and +errno is set to an appropriate value. ERRORS ------ -The following error values are specifically set by this RMR -function. In some cases the error message of a system call is -propagated up, and thus this list might be incomplete. - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **ENOMEM** - - - Unable to allocate memory. - - +The following error values are specifically set by this RMR +function. In some cases the error message of a system call is +propagated up, and thus this list might be incomplete. + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **ENOMEM** + - + Unable to allocate memory. + + EXAMPLE ------- - -:: - - void* uh; - rmr_mbuf* buf = NULL; - - uh = rmr_init( "43086", 4096, 0 ); - buf = rmr_rcv_msg( uh, buf ); - + +:: + + void* uh; + rmr_mbuf* buf = NULL; + + uh = rmr_init( "43086", 4096, 0 ); + buf = rmr_rcv_msg( uh, buf ); + SEE ALSO -------- -rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), -rmr_get_rcvfd(3), rmr_mt_call(3), rmr_mt_rcv(3), -rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), -rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3), -rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3), -rmr_ring_free(3) +rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), +rmr_get_rcvfd(3), rmr_mt_call(3), rmr_mt_rcv(3), +rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), +rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3), +rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3), +rmr_ring_free(3) diff --git a/docs/rmr_init_trace.3.rst b/docs/rmr_init_trace.3.rst index 52875a9..2f9774d 100644 --- a/docs/rmr_init_trace.3.rst +++ b/docs/rmr_init_trace.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_init_trace -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_init_trace +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,61 +19,61 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_init_trace +rmr_init_trace SYNOPSIS -------- - -:: - - #include - - void* rmr_init_trace( void* ctx ) - + +:: + + #include + + void* rmr_init_trace( void* ctx ) + DESCRIPTION ----------- -The ``rmr_init_trace`` function establishes the default trace -space placed in each message buffer allocated with -``rmr_alloc_msg().`` If this function is never called, then -no trace space is allocated by default into any message -buffer. - -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 -``rmr_set_trace(),`` and may be extracted from a message with -``rmr_get_trace().`` The number of bytes that a message -contains for/with trace data can be determined by invoking -``rmr_get_trlen().`` - -This function may be safely called at any time during the -life of the user programme 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 a -message later, the ``rmr_tralloc_msg()`` function can be -used. +The ``rmr_init_trace`` function establishes the default trace +space placed in each message buffer allocated with +``rmr_alloc_msg().`` If this function is never called, then +no trace space is allocated by default into any message +buffer. + +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 +``rmr_set_trace(),`` and may be extracted from a message with +``rmr_get_trace().`` The number of bytes that a message +contains for/with trace data can be determined by invoking +``rmr_get_trlen().`` + +This function may be safely called at any time during the +life of the user programme 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 a +message later, the ``rmr_tralloc_msg()`` function can be +used. RETURN VALUE ------------ -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. +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. SEE ALSO -------- -rmr_alloc_msg(3), rmr_tr_alloc_msg(3), rmr_call(3), -rmr_free_msg(3), rmr_get_rcvfd(3), rmr_get_trace(3), -rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3), -rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), -rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), -rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3) +rmr_alloc_msg(3), rmr_tr_alloc_msg(3), rmr_call(3), +rmr_free_msg(3), rmr_get_rcvfd(3), rmr_get_trace(3), +rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3), +rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), +rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), +rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3) diff --git a/docs/rmr_mt_call.3.rst b/docs/rmr_mt_call.3.rst index f8b295b..985e9d7 100644 --- a/docs/rmr_mt_call.3.rst +++ b/docs/rmr_mt_call.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_mt_call -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_mt_call +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,252 +19,252 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_mt_call +rmr_mt_call SYNOPSIS -------- - -:: - - #include - - extern rmr_mbuf_t* rmr_mt_call( void* vctx, rmr_mbuf_t* msg, int id, int timeout ); - + +:: + + #include + + extern rmr_mbuf_t* rmr_mt_call( void* vctx, rmr_mbuf_t* msg, int id, int timeout ); + DESCRIPTION ----------- -The ``rmr_mt_call`` function sends the user application -message to a remote endpoint, and waits for a corresponding -response message before returning control to the user -application. The user application supplies a completed -message buffer, as it would for a ``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 *rmr_mt_call()* will block until a -message arrives or until *timeout* milliseconds has passed; -which ever comes first. Using a timeout value of zero (0) -will cause the thread to block without a timeout. - -The *id* supplied as the third parameter is an integer in the -range of 2 through 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. - -Messages which are received while waiting for the response -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 the order received, one per -call to ``rmr_rcv_msg.`` +The ``rmr_mt_call`` function sends the user application +message to a remote endpoint, and waits for a corresponding +response message before returning control to the user +application. The user application supplies a completed +message buffer, as it would for a ``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 *rmr_mt_call()* will block until a +message arrives or until *timeout* milliseconds has passed; +which ever comes first. Using a timeout value of zero (0) +will cause the thread to block without a timeout. + +The *id* supplied as the third parameter is an integer in the +range of 2 through 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. + +Messages which are received while waiting for the response +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 the order received, one per +call to ``rmr_rcv_msg.`` 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 **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 *rmr_rts_msg()* function and does -not adjust 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 **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 *rmr_rts_msg()* function and does +not adjust the transaction ID. Retries ------- -The send operations in RMR will retry *soft* send failures -until one of three conditions occurs: - - -* The message is sent without error - -* The underlying transport reports a *hard* failure - -* The maximum number of retry loops has been attempted - - -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 -allowing the user application to completely disable retires -(set to 0), or to increase the number of retry loops. +The send operations in RMR will retry *soft* send failures +until one of three conditions occurs: + + +* The message is sent without error + +* The underlying transport reports a *hard* failure + +* The maximum number of retry loops has been attempted + + +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 +allowing the user application to completely disable retires +(set to 0), or to increase the number of retry loops. Transport Level Blocking ------------------------ -The underlying transport mechanism used to send messages is -configured in *non-blocking* mode. This means that if a -message cannot be sent immediately the transport mechanism -will **not** pause with the assumption that the inability to -send will clear quickly (within a few milliseconds). This -means that when the retry loop is completely disabled (set to -0), that the failure to accept a message for sending by the -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 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. +The underlying transport mechanism used to send messages is +configured in *non-blocking* mode. This means that if a +message cannot be sent immediately the transport mechanism +will **not** pause with the assumption that the inability to +send will clear quickly (within a few milliseconds). This +means that when the retry loop is completely disabled (set to +0), that the failure to accept a message for sending by the +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 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 ------------ -The ``rmr_mt_call`` function returns a pointer to a message -buffer with the state set to reflect the overall state of -call processing. If the state is ``RMR_OK`` then the buffer -contains the response message; otherwise the state indicates -the error encountered while attempting to send the message. - -If no response message is received when the timeout period -has expired, a nil pointer will be returned (NULL). +The ``rmr_mt_call`` function returns a pointer to a message +buffer with the state set to reflect the overall state of +call processing. If the state is ``RMR_OK`` then the buffer +contains the response message; otherwise the state indicates +the error encountered while attempting to send the message. + +If no response message is received when the timeout period +has expired, a nil pointer will be returned (NULL). ERRORS ------ -These values are reflected in the state field of the returned -message. - - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **RMR_OK** - - - The call was successful and the message buffer references the - response message. - - * - **RMR_ERR_BADARG** - - - An argument passed to the function was invalid. - - * - **RMR_ERR_CALLFAILED** - - - The call failed and the value of *errno,* as described below, - should be checked for the specific reason. - - * - **RMR_ERR_NOENDPT** - - - An endpoint associated with the message type could not be - found in the route table. - - * - **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. - - - -The global "variable" *errno* will be set to one of the -following values if the overall call processing was not -successful. - - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **ETIMEDOUT** - - - Too many messages were queued before receiving the expected - response - - * - **ENOBUFS** - - - The queued message ring is full, messages were dropped - - * - **EINVAL** - - - A parameter was not valid - - * - **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. - - +These values are reflected in the state field of the returned +message. + + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **RMR_OK** + - + The call was successful and the message buffer references the + response message. + + * - **RMR_ERR_BADARG** + - + An argument passed to the function was invalid. + + * - **RMR_ERR_CALLFAILED** + - + The call failed and the value of *errno,* as described below, + should be checked for the specific reason. + + * - **RMR_ERR_NOENDPT** + - + An endpoint associated with the message type could not be + found in the route table. + + * - **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. + + + +The global "variable" *errno* will be set to one of the +following values if the overall call processing was not +successful. + + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **ETIMEDOUT** + - + Too many messages were queued before receiving the expected + response + + * - **ENOBUFS** + - + The queued message ring is full, messages were dropped + + * - **EINVAL** + - + A parameter was not valid + + * - **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. + + EXAMPLE ------- -The following code bit shows one way of using the -``rmr_mt_call`` 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; // appl message struct (payload) - - // get a send buffer and reference the payload - mbuf = rmr_alloc_msg( mr, sizeof( pm->req ) ); - pm = (msg_t*) mbuf->payload; - - // 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 - 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_OK ) { - - usleep( retry_delay ); - } - - if( mbuf == NULL || mbuf->state != RMR_OK ) { - rmr_free_msg( mbuf ); // safe if nil - return NULL; - } - } - - // do something with mbuf - +The following code bit shows one way of using the +``rmr_mt_call`` 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; // appl message struct (payload) + + // get a send buffer and reference the payload + mbuf = rmr_alloc_msg( mr, sizeof( pm->req ) ); + pm = (msg_t*) mbuf->payload; + + // 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 + 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_OK ) { + + usleep( retry_delay ); + } + + if( mbuf == NULL || mbuf->state != RMR_OK ) { + rmr_free_msg( mbuf ); // safe if nil + return NULL; + } + } + + // do something with mbuf + SEE ALSO -------- -rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3), -rmr_mt_rcv(3), rmr_payload_size(3), rmr_send_msg(3), -rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), -rmr_ready(3), rmr_fib(3), rmr_has_str(3), -rmr_set_stimeout(3), rmr_tokenise(3), rmr_mk_ring(3), -rmr_ring_free(3) +rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3), +rmr_mt_rcv(3), rmr_payload_size(3), rmr_send_msg(3), +rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), +rmr_ready(3), rmr_fib(3), rmr_has_str(3), +rmr_set_stimeout(3), rmr_tokenise(3), rmr_mk_ring(3), +rmr_ring_free(3) diff --git a/docs/rmr_mt_rcv.3.rst b/docs/rmr_mt_rcv.3.rst index d772774..087d417 100644 --- a/docs/rmr_mt_rcv.3.rst +++ b/docs/rmr_mt_rcv.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_mt_rcv -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_mt_rcv +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,201 +19,201 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_mt_rcv +rmr_mt_rcv SYNOPSIS -------- - -:: - - #include - - rmr_mbuf_t* rmr_mt_rcv( void* vctx, rmr_mbuf_t* old_msg, int timeout ); - + +:: + + #include + + rmr_mbuf_t* rmr_mt_rcv( void* vctx, rmr_mbuf_t* old_msg, int timeout ); + DESCRIPTION ----------- -The ``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. 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 the -next message received. - -The *vctx* pointer is the pointer returned by the -``rmr_init`` function. *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. When no 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 -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 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 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 -function without a timeout value, thus there is the small -cost of a second call that results). Similarly, the -*rmr_torcv_msg()* call can be used when in multi-threaded -mode with the same "pass through" overhead to using this -function directly. +The ``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. 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 the +next message received. + +The *vctx* pointer is the pointer returned by the +``rmr_init`` function. *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. When no 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 +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 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 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 +function without a timeout value, thus there is the small +cost of a second call that results). Similarly, the +*rmr_torcv_msg()* call can be used when in multi-threaded +mode with the same "pass through" overhead to using this +function directly. 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. This will, with a high probability, be a -different message buffer than *old_msg;* the user application -should not continue to use *old_msg* after it is passed to -this function. - -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. +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 *old_msg;* the user application +should not continue to use *old_msg* after it is passed to +this function. + +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. ERRORS ------ -The *state* field in the message buffer will be set to one of -the following values: - - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **RMR_OK** - - - The message was received without error. - - * - **RMR_ERR_BADARG** - - - A parameter passed to the function was not valid (e.g. a nil - pointer). indicate either ``RMR_OK`` or ``RMR_ERR_EMPTY`` if - an empty message was received. - - * - **RMR_ERR_EMPTY** - - - The message received had no associated data. The length of - the message will be 0. - - * - **RMR_ERR_NOTSUPP** - - - The multi-threaded option was not enabled when RMR was - initialised. See the man page for *rmr_init()* for details. - - * - **RMR_ERR_RCVFAILED** - - - A hard error occurred preventing the receive from completing. - - -When a nil pointer is returned, or any other state value was -set in the message buffer, ``errno`` will be set to one of -the following: - - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **INVAL** - - - Parameter(s) passed to the function were not valid. - - * - **EBADF** - - - The underlying message transport is unable to process the - request. - - * - **ENOTSUP** - - - The underlying message transport is unable to process the - request. - - * - **EFSM** - - - The underlying message transport is unable to process the - request. - - * - **EAGAIN** - - - The underlying message transport is unable to process the - request. - - * - **EINTR** - - - The underlying message transport is unable to process the - request. - - * - **ETIMEDOUT** - - - The underlying message transport is unable to process the - request. - - * - **ETERM** - - - The underlying message transport is unable to process the - request. - - +The *state* field in the message buffer will be set to one of +the following values: + + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **RMR_OK** + - + The message was received without error. + + * - **RMR_ERR_BADARG** + - + A parameter passed to the function was not valid (e.g. a nil + pointer). indicate either ``RMR_OK`` or ``RMR_ERR_EMPTY`` if + an empty message was received. + + * - **RMR_ERR_EMPTY** + - + The message received had no associated data. The length of + the message will be 0. + + * - **RMR_ERR_NOTSUPP** + - + The multi-threaded option was not enabled when RMR was + initialised. See the man page for *rmr_init()* for details. + + * - **RMR_ERR_RCVFAILED** + - + A hard error occurred preventing the receive from completing. + + +When a nil pointer is returned, or any other state value was +set in the message buffer, ``errno`` will be set to one of +the following: + + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **INVAL** + - + Parameter(s) passed to the function were not valid. + + * - **EBADF** + - + The underlying message transport is unable to process the + request. + + * - **ENOTSUP** + - + The underlying message transport is unable to process the + request. + + * - **EFSM** + - + The underlying message transport is unable to process the + request. + + * - **EAGAIN** + - + The underlying message transport is unable to process the + request. + + * - **EINTR** + - + The underlying message transport is unable to process the + request. + + * - **ETIMEDOUT** + - + The underlying message transport is unable to process the + request. + + * - **ETERM** + - + The underlying message transport is unable to process the + request. + + EXAMPLE ------- - - -:: - - rmr_mbuf_t* mbuf = NULL; // received msg - - msg = rmr_mt_recv( mr, mbuf, 100 ); // wait up to 100ms - if( msg != NULL ) { - switch( msg->state ) { - case RMR_OK: - printf( "got a good message\\n" ); - break; - - case RMR_ERR_EMPTY: - printf( "received timed out\\n" ); - break; - - default: - printf( "receive error: %d\\n", mbuf->state ); - break; - } - } else { - printf( "receive timeout (nil)\\n" ); - } - + + +:: + + rmr_mbuf_t* mbuf = NULL; // received msg + + msg = rmr_mt_recv( mr, mbuf, 100 ); // wait up to 100ms + if( msg != NULL ) { + switch( msg->state ) { + case RMR_OK: + printf( "got a good message\\n" ); + break; + + case RMR_ERR_EMPTY: + printf( "received timed out\\n" ); + break; + + default: + printf( "receive error: %d\\n", mbuf->state ); + break; + } + } else { + printf( "receive timeout (nil)\\n" ); + } + SEE ALSO -------- -rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), -rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3), -rmr_mt_call(3), rmr_payload_size(3), rmr_send_msg(3), -rmr_torcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), -rmr_ready(3), rmr_ring_free(3), rmr_torcv_msg(3) +rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), +rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3), +rmr_mt_call(3), rmr_payload_size(3), rmr_send_msg(3), +rmr_torcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), +rmr_ready(3), rmr_ring_free(3), rmr_torcv_msg(3) diff --git a/docs/rmr_payload_size.3.rst b/docs/rmr_payload_size.3.rst index 58b674f..a0c4bd3 100644 --- a/docs/rmr_payload_size.3.rst +++ b/docs/rmr_payload_size.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_payload_size -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_payload_size +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,56 +19,56 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_payload_size +rmr_payload_size SYNOPSIS -------- - -:: - - #include - - int rmr_payload_size( rmr_mbuf_t* msg ); - + +:: + + #include + + int rmr_payload_size( rmr_mbuf_t* msg ); + 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 message buffer. +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 message buffer. RETURN VALUE ------------ -The number of bytes available in the payload. +The number of bytes available in the payload. ERRORS ------ - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **INVAL** - - - Parameter(s) passed to the function were not valid. - - + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **INVAL** + - + Parameter(s) passed to the function were not valid. + + SEE ALSO -------- -rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), -rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3), -rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3), -rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3) +rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), +rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3), +rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3), +rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3) diff --git a/docs/rmr_rcv_msg.3.rst b/docs/rmr_rcv_msg.3.rst index aa7f2fd..9faa3a3 100644 --- a/docs/rmr_rcv_msg.3.rst +++ b/docs/rmr_rcv_msg.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_rcv_msg -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_rcv_msg +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,135 +19,135 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_rcv_msg +rmr_rcv_msg SYNOPSIS -------- - -:: - - #include - - rmr_mbuf_t* rmr_rcv_msg( void* vctx, rmr_mbuf_t* old_msg ); - + +:: + + #include + + rmr_mbuf_t* rmr_rcv_msg( void* vctx, rmr_mbuf_t* old_msg ); + DESCRIPTION ----------- -The ``rmr_rcv_msg`` function blocks until a message is -received, returning the message to the caller via a pointer -to a ``rmr_mbuf_t`` structure type. If messages were queued -while waiting for the response to a previous invocation of -``rmr_call,`` the oldest message is removed from the queue -and returned without delay. - -The *vctx* pointer is the pointer returned by the -``rmr_init`` function. *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. When no buffer is available to supply, the -receive function will allocate one. +The ``rmr_rcv_msg`` function blocks until a message is +received, returning the message to the caller via a pointer +to a ``rmr_mbuf_t`` structure type. If messages were queued +while waiting for the response to a previous invocation of +``rmr_call,`` the oldest message is removed from the queue +and returned without delay. + +The *vctx* pointer is the pointer returned by the +``rmr_init`` function. *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. When no buffer is available to supply, the +receive function will allocate one. RETURN VALUE ------------ -The function returns a pointer to the ``rmr_mbuf_t`` -structure which references the message information (state, -length, payload), or a nil pointer in the case of an extreme -error. +The function returns a pointer to the ``rmr_mbuf_t`` +structure which references the message information (state, +length, payload), or a nil pointer in the case of an extreme +error. ERRORS ------ -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: - - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **RMR_ERR_EMPTY** - - - The message received had no payload, or was completely empty. - - - * - **RMR_ERR_TIMEOUT** - - - For some transport mechanisms, or if reading the receive - queue from multiple threads, it is possible for one thread to - find no data waiting when it queries the queue. When this - state is reported, the message buffer does not contain - message data and the user application should reinvoke the - receive function. - - - -When an RMR error state is reported, the underlying -``errno`` value might provide more information. The following -is a list of possible values that might accompany the states -listed above: - -``RMR_ERR_EMPTY`` if an empty message was received. If a nil -pointer is returned, or any other state value was set in the -message buffer, ``errno`` will be set to one of the -following: - - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **INVAL** - - - Parameter(s) passed to the function were not valid. - - * - **EBADF** - - - The underlying message transport is unable to process the - request. - - * - **ENOTSUP** - - - The underlying message transport is unable to process the - request. - - * - **EFSM** - - - The underlying message transport is unable to process the - request. - - * - **EAGAIN** - - - The underlying message transport is unable to process the - request. - - * - **EINTR** - - - The underlying message transport is unable to process the - request. - - * - **ETIMEDOUT** - - - The underlying message transport is unable to process the - request. - - * - **ETERM** - - - The underlying message transport is unable to process the - request. - - +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: + + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **RMR_ERR_EMPTY** + - + The message received had no payload, or was completely empty. + + + * - **RMR_ERR_TIMEOUT** + - + For some transport mechanisms, or if reading the receive + queue from multiple threads, it is possible for one thread to + find no data waiting when it queries the queue. When this + state is reported, the message buffer does not contain + message data and the user application should reinvoke the + receive function. + + + +When an RMR error state is reported, the underlying +``errno`` value might provide more information. The following +is a list of possible values that might accompany the states +listed above: + +``RMR_ERR_EMPTY`` if an empty message was received. If a nil +pointer is returned, or any other state value was set in the +message buffer, ``errno`` will be set to one of the +following: + + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **INVAL** + - + Parameter(s) passed to the function were not valid. + + * - **EBADF** + - + The underlying message transport is unable to process the + request. + + * - **ENOTSUP** + - + The underlying message transport is unable to process the + request. + + * - **EFSM** + - + The underlying message transport is unable to process the + request. + + * - **EAGAIN** + - + The underlying message transport is unable to process the + request. + + * - **EINTR** + - + The underlying message transport is unable to process the + request. + + * - **ETIMEDOUT** + - + The underlying message transport is unable to process the + request. + + * - **ETERM** + - + The underlying message transport is unable to process the + request. + + EXAMPLE @@ -158,8 +158,8 @@ EXAMPLE SEE ALSO -------- -rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), -rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3), -rmr_payload_size(3), rmr_send_msg(3), rmr_torcv_msg(3), -rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3), -rmr_ring_free(3), rmr_torcv_msg(3) +rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), +rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3), +rmr_payload_size(3), rmr_send_msg(3), rmr_torcv_msg(3), +rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3), +rmr_ring_free(3), rmr_torcv_msg(3) diff --git a/docs/rmr_ready.3.rst b/docs/rmr_ready.3.rst index e7843b4..b6b8b0f 100644 --- a/docs/rmr_ready.3.rst +++ b/docs/rmr_ready.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_ready -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_ready +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,44 +19,44 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_ready +rmr_ready SYNOPSIS -------- - -:: - - #include - - int rmr_ready( void* vctx ); - + +:: + + #include + + int rmr_ready( void* vctx ); + DESCRIPTION ----------- -The ``rmr_ready`` function checks to see if a routing table -has been successfully received and installed. The return -value indicates the state of readiness. +The ``rmr_ready`` function checks to see if a routing table +has been successfully received and installed. The return +value indicates the state of readiness. RETURN VALUE ------------ -A return value of 1 (true) indicates that the routing table -is in place and 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 *no -endpoint* errors. +A return value of 1 (true) indicates that the routing table +is in place and 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 *no +endpoint* errors. SEE ALSO -------- -rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), -rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), -rmr_rcv_specific(3), rmr_rts_msg(3), rmr_fib(3), -rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3), -rmr_ring_free(3) +rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), +rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), +rmr_rcv_specific(3), rmr_rts_msg(3), rmr_fib(3), +rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3), +rmr_ring_free(3) diff --git a/docs/rmr_realloc_payload.3.rst b/docs/rmr_realloc_payload.3.rst index 3d5f013..9397017 100644 --- a/docs/rmr_realloc_payload.3.rst +++ b/docs/rmr_realloc_payload.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_realloc_payload -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_realloc_payload +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,126 +19,126 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_realloc_payload +rmr_realloc_payload SYNOPSIS -------- - -:: - - #include - - extern rmr_mbuf_t* rmr_realloc_payload( rmr_mbuf_t* msg, int new_len, int copy, int clone ); - + +:: + + #include + + extern rmr_mbuf_t* rmr_realloc_payload( rmr_mbuf_t* msg, int new_len, int copy, int clone ); + DESCRIPTION ----------- -The ``rmr_realloc_payload`` function will return a pointer to -an RMR message buffer struct (rmr_mbuf_t) which has a payload -large enough to accomodate *new_len* bytes. If necessary, the -underlying payload is reallocated, and the bytes from the -original payload are copied if the *copy* parameter is true -(1). If the message passed in has a payload large enough, -there is no additional memory allocation and copying. +The ``rmr_realloc_payload`` function will return a pointer to +an RMR message buffer struct (rmr_mbuf_t) which has a payload +large enough to accomodate *new_len* bytes. If necessary, the +underlying payload is reallocated, and the bytes from the +original payload are copied if the *copy* parameter is true +(1). If the message passed in has a payload large enough, +there is no additional memory allocation and copying. Cloning The Message Buffer -------------------------- -This function can also be used to generate a separate copy of -the original message, with the desired payload size, without -destroying the original message buffer or the original -payload. A standalone copy is made only when the *clone* -parameter is true (1). When cloning, the payload is copied to -the cloned message **only** if the *copy* parameter is true. +This function can also be used to generate a separate copy of +the original message, with the desired payload size, without +destroying the original message buffer or the original +payload. A standalone copy is made only when the *clone* +parameter is true (1). When cloning, the payload is copied to +the cloned message **only** if the *copy* parameter is true. Message Buffer Metadata ----------------------- -The metadata in the original message buffer (message type, -subscription ID, and payload length) will be preserved if the -*copy* parameter is true. When this parameter is not true -(0), then these values are set to the uninitialised value -(-1) for type and ID, and the length is set to 0. +The metadata in the original message buffer (message type, +subscription ID, and payload length) will be preserved if the +*copy* parameter is true. When this parameter is not true +(0), then these values are set to the uninitialised value +(-1) for type and ID, and the length is set to 0. RETURN VALUE ------------ -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 reference that -message. It is the calling application's responsibility to -free the memory associateed with both messages using the -rmr_free_msg() function. - -When the *clone* option is not used, it is still good -practice by the calling application to capture and use this -reference as it is possible that the message buffer, and not -just the payload buffer, was reallocated. In the event of an -error, a nil pointer will be returned and the value of -*errno* will be set to reflect the problem. +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 reference that +message. It is the calling application's responsibility to +free the memory associateed with both messages using the +rmr_free_msg() function. + +When the *clone* option is not used, it is still good +practice by the calling application to capture and use this +reference as it is possible that the message buffer, and not +just the payload buffer, was reallocated. In the event of an +error, a nil pointer will be returned and the value of +*errno* will be set to reflect the problem. ERRORS ------ -These value of *errno* will reflect the error condition if a -nil pointer is returned: - - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **ENOMEM** - - - Memory allocation of the new payload failed. - - * - **EINVAL** - - - The pointer passed in was nil, or referenced an invalid - message, or the required length was not valid. - - +These value of *errno* will reflect the error condition if a +nil pointer is returned: + + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **ENOMEM** + - + Memory allocation of the new payload failed. + + * - **EINVAL** + - + The pointer passed in was nil, or referenced an invalid + message, or the required length was not valid. + + EXAMPLE ------- -The following code bit illustrates how this function can be -used to reallocate a buffer for a return to sender -acknowledgement message which is larger than the message -received. - - -:: - - if( rmr_payload_size( msg ) < ack_sz ) { // received message too small for ack - msg = rmr_realloc_payload( msg, ack_sz, 0, 0 ); // reallocate the message with a payload big enough - if( msg == NULL ) { - fprintf( stderr, "[ERR] realloc returned a nil pointer: %s\\n", strerror( errno ) ); - } else { - // populate and send ack message - } - } - - +The following code bit illustrates how this function can be +used to reallocate a buffer for a return to sender +acknowledgement message which is larger than the message +received. + + +:: + + if( rmr_payload_size( msg ) < ack_sz ) { // received message too small for ack + msg = rmr_realloc_payload( msg, ack_sz, 0, 0 ); // reallocate the message with a payload big enough + if( msg == NULL ) { + fprintf( stderr, "[ERR] realloc returned a nil pointer: %s\\n", strerror( errno ) ); + } else { + // populate and send ack message + } + } + + SEE ALSO -------- -rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3), -rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), -rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3), -rmr_fib(3), rmr_has_str(3), rmr_set_stimeout(3), -rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3) +rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3), +rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), +rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3), +rmr_fib(3), rmr_has_str(3), rmr_set_stimeout(3), +rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3) diff --git a/docs/rmr_rts_msg.3.rst b/docs/rmr_rts_msg.3.rst index b0637cc..1ebbd84 100644 --- a/docs/rmr_rts_msg.3.rst +++ b/docs/rmr_rts_msg.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_rts_msg -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_rts_msg +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,213 +19,213 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_rts_msg +rmr_rts_msg SYNOPSIS -------- - -:: - - #include - - rmr_mbuf_t* rmr_rts_msg( void* vctx, rmr_mbuf_t* msg ); - + +:: + + #include + + rmr_mbuf_t* rmr_rts_msg( void* vctx, rmr_mbuf_t* msg ); + DESCRIPTION ----------- -The ``rmr_rts_msg`` function sends a message returning it to -the endpoint which sent the message rather than selecting an -endpoint based on the message type and routing table. Other -than this small difference, the behaviour is exactly the same -as ``rmr_send_msg.`` +The ``rmr_rts_msg`` function sends a message returning it to +the endpoint which sent the message rather than selecting an +endpoint based on the message type and routing table. Other +than this small difference, the behaviour is exactly the same +as ``rmr_send_msg.`` Retries ------- -The send operations in RMR will retry *soft* send failures -until one of three conditions occurs: - - -* The message is sent without error - -* The underlying transport reports a *hard* failure - -* The maximum number of retry loops has been attempted - - -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 -allowing the user application to completely disable retires -(set to 0), or to increase the number of retry loops. +The send operations in RMR will retry *soft* send failures +until one of three conditions occurs: + + +* The message is sent without error + +* The underlying transport reports a *hard* failure + +* The maximum number of retry loops has been attempted + + +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 +allowing the user application to completely disable retires +(set to 0), or to increase the number of retry loops. Transport Level Blocking ------------------------ -The underlying transport mechanism used to send messages is -configured in *non-blocking* mode. This means that if a -message cannot be sent immediately the transport mechanism -will **not** pause with the assumption that the inability to -send will clear quickly (within a few milliseconds). This -means that when the retry loop is completely disabled (set to -0), that the failure to accept a message for sending by the -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 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. +The underlying transport mechanism used to send messages is +configured in *non-blocking* mode. This means that if a +message cannot be sent immediately the transport mechanism +will **not** pause with the assumption that the inability to +send will clear quickly (within a few milliseconds). This +means that when the retry loop is completely disabled (set to +0), that the failure to accept a message for sending by the +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 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 ------------ -When crafting a response based on a received message, the -user application must take care not to write more bytes to -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 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 data needed -by this function, the *rmr_realloc_payload()* function must -be used to extend the payload to a size suitable for the -response. +When crafting a response based on a received message, the +user application must take care not to write more bytes to +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 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 data needed +by this function, the *rmr_realloc_payload()* function must +be used to extend the payload to a size suitable for the +response. RETURN VALUE ------------ -On success, a new message buffer, with an empty payload, is -returned for the application to use for the next send. The -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 -``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. - -In the event of extreme failure, a nil pointer is returned. -In this case the value of ``errno`` might be of some use, for -documentation, but there will be little that the user -application can do other than to move on. +On success, a new message buffer, with an empty payload, is +returned for the application to use for the next send. The +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 +``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. + +In the event of extreme failure, a nil pointer is returned. +In this case the value of ``errno`` might be of some use, for +documentation, but there will be little that the user +application can do other than to move on. ERRORS ------ -The following values may be passed back in the *state* field -of the returned message buffer. - - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **RMR_ERR_BADARG** - - - The message buffer pointer did not refer to a valid message. - - * - **RMR_ERR_NOHDR** - - - The header in the message buffer was not valid or corrupted. - - * - **RMR_ERR_NOENDPT** - - - The message type in the message buffer did not map to a known - endpoint. - - * - **RMR_ERR_SENDFAILED** - - - The send failed; ``errno`` has the possible reason. - - - -The following values may be assigned to ``errno`` on failure. - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **INVAL** - - - Parameter(s) passed to the function were not valid, or the - underlying message processing environment was unable to - interpret the message. - - * - **ENOKEY** - - - The header information in the message buffer was invalid. - - * - **ENXIO** - - - No known endpoint for the message could be found. - - * - **EMSGSIZE** - - - The underlying transport refused to accept the message - because of a size value issue (message was not attempted to - be sent). - - * - **EFAULT** - - - The message referenced by the message buffer is corrupt (nil - pointer or bad internal length). - - * - **EBADF** - - - Internal RMR error; information provided to the message - transport environment was not valid. - - * - **ENOTSUP** - - - Sending was not supported by the underlying message - transport. - - * - **EFSM** - - - The device is not in a state that can accept the message. - - * - **EAGAIN** - - - The device is not able to accept a message for sending. The - user application should attempt to resend. - - * - **EINTR** - - - The operation was interrupted by delivery of a signal before - the message was sent. - - * - **ETIMEDOUT** - - - The underlying message environment timed out during the send - process. - - * - **ETERM** - - - The underlying message environment is in a shutdown state. - - +The following values may be passed back in the *state* field +of the returned message buffer. + + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **RMR_ERR_BADARG** + - + The message buffer pointer did not refer to a valid message. + + * - **RMR_ERR_NOHDR** + - + The header in the message buffer was not valid or corrupted. + + * - **RMR_ERR_NOENDPT** + - + The message type in the message buffer did not map to a known + endpoint. + + * - **RMR_ERR_SENDFAILED** + - + The send failed; ``errno`` has the possible reason. + + + +The following values may be assigned to ``errno`` on failure. + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **INVAL** + - + Parameter(s) passed to the function were not valid, or the + underlying message processing environment was unable to + interpret the message. + + * - **ENOKEY** + - + The header information in the message buffer was invalid. + + * - **ENXIO** + - + No known endpoint for the message could be found. + + * - **EMSGSIZE** + - + The underlying transport refused to accept the message + because of a size value issue (message was not attempted to + be sent). + + * - **EFAULT** + - + The message referenced by the message buffer is corrupt (nil + pointer or bad internal length). + + * - **EBADF** + - + Internal RMR error; information provided to the message + transport environment was not valid. + + * - **ENOTSUP** + - + Sending was not supported by the underlying message + transport. + + * - **EFSM** + - + The device is not in a state that can accept the message. + + * - **EAGAIN** + - + The device is not able to accept a message for sending. The + user application should attempt to resend. + + * - **EINTR** + - + The operation was interrupted by delivery of a signal before + the message was sent. + + * - **ETIMEDOUT** + - + The underlying message environment timed out during the send + process. + + * - **ETERM** + - + The underlying message environment is in a shutdown state. + + EXAMPLE @@ -236,8 +236,8 @@ EXAMPLE SEE ALSO -------- -rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), -rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), -rmr_rcv_specific(3), rmr_ready(3), rmr_fib(3), -rmr_has_str(3), rmr_set_stimeout(3), rmr_tokenise(3), -rmr_mk_ring(3), rmr_ring_free(3) +rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), +rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), +rmr_rcv_specific(3), rmr_ready(3), rmr_fib(3), +rmr_has_str(3), rmr_set_stimeout(3), rmr_tokenise(3), +rmr_mk_ring(3), rmr_ring_free(3) diff --git a/docs/rmr_send_msg.3.rst b/docs/rmr_send_msg.3.rst index 33fd9cf..9d214fe 100644 --- a/docs/rmr_send_msg.3.rst +++ b/docs/rmr_send_msg.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_send_msg -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_send_msg +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,263 +19,263 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_send_msg +rmr_send_msg SYNOPSIS -------- - -:: - - #include - - rmr_mbuf_t* rmr_send_msg( void* vctx, rmr_mbuf_t* msg ); - + +:: + + #include + + rmr_mbuf_t* rmr_send_msg( void* vctx, rmr_mbuf_t* msg ); + DESCRIPTION ----------- -The ``rmr_send_msg`` function accepts a message buffer from -the user application and attempts to send it. The destination -of the message is selected based on the message type -specified in the message buffer, and the matching information -in the routing tables which are currently in use by the RMR -library. This may actually result in the sending of the -message to multiple destinations which could degrade expected -overall performance of the user application. (Limiting -excessive sending of messages is the responsibility of the -application(s) responsible for building the routing table -used by the RMR library, and not the responsibility of the -library.) +The ``rmr_send_msg`` function accepts a message buffer from +the user application and attempts to send it. The destination +of the message is selected based on the message type +specified in the message buffer, and the matching information +in the routing tables which are currently in use by the RMR +library. This may actually result in the sending of the +message to multiple destinations which could degrade expected +overall performance of the user application. (Limiting +excessive sending of messages is the responsibility of the +application(s) responsible for building the routing table +used by the RMR library, and not the responsibility of the +library.) Retries ------- -The send operations in RMR will retry *soft* send failures -until one of three conditions occurs: - - -* The message is sent without error - -* The underlying transport reports a *hard* failure - -* The maximum number of retry loops has been attempted - - -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 -allowing the user application to completely disable retires -(set to 0), or to increase the number of retry loops. +The send operations in RMR will retry *soft* send failures +until one of three conditions occurs: + + +* The message is sent without error + +* The underlying transport reports a *hard* failure + +* The maximum number of retry loops has been attempted + + +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 +allowing the user application to completely disable retires +(set to 0), or to increase the number of retry loops. Transport Level Blocking ------------------------ -The underlying transport mechanism used to send messages is -configured in *non-blocking* mode. This means that if a -message cannot be sent immediately the transport mechanism -will **not** pause with the assumption that the inability to -send will clear quickly (within a few milliseconds). This -means that when the retry loop is completely disabled (set to -0), that the failure to accept a message for sending by the -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 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. +The underlying transport mechanism used to send messages is +configured in *non-blocking* mode. This means that if a +message cannot be sent immediately the transport mechanism +will **not** pause with the assumption that the inability to +send will clear quickly (within a few milliseconds). This +means that when the retry loop is completely disabled (set to +0), that the failure to accept a message for sending by the +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 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 ------------ -On success, a new message buffer, with an empty payload, is -returned for the application to use for the next send. The -state in this buffer will reflect the overall send operation -state and will be ``RMR_OK`` when the send was successful. - -When the message cannot be successfully sent this function -will return the unsent (original) message buffer with the -state set to indicate the reason for failure. The value of -*errno* may also be set to reflect a more detailed failure -reason if it is known. - -In the event of extreme failure, a nil pointer is returned. -In this case the value of ``errno`` might be of some use, for -documentation, but there will be little that the user -application can do other than to move on. - -**CAUTION:** In some cases it is extremely likely that the -message returned by the send function does **not** reference -the same memory structure. Thus is important for the user -programme to capture the new pointer for future use or to be -passed to ``rmr_free().`` If you are experiencing either -double free errors or segment faults in either -``rmr_free()`` or ``rmr_send_msg(),`` ensure that the return -value from this function is being captured and used. +On success, a new message buffer, with an empty payload, is +returned for the application to use for the next send. The +state in this buffer will reflect the overall send operation +state and will be ``RMR_OK`` when the send was successful. + +When the message cannot be successfully sent this function +will return the unsent (original) message buffer with the +state set to indicate the reason for failure. The value of +*errno* may also be set to reflect a more detailed failure +reason if it is known. + +In the event of extreme failure, a nil pointer is returned. +In this case the value of ``errno`` might be of some use, for +documentation, but there will be little that the user +application can do other than to move on. + +**CAUTION:** In some cases it is extremely likely that the +message returned by the send function does **not** reference +the same memory structure. Thus is important for the user +programme to capture the new pointer for future use or to be +passed to ``rmr_free().`` If you are experiencing either +double free errors or segment faults in either +``rmr_free()`` or ``rmr_send_msg(),`` ensure that the return +value from this function is being captured and used. ERRORS ------ -The following values may be passed back in the *state* field -of the returned message buffer. - - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **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. - - * - **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. - - * - **RMR_ERR_BADARG** - - - The message buffer pointer did not refer to a valid message. - - * - **RMR_ERR_NOHDR** - - - The header in the message buffer was not valid or corrupted. - - * - **RMR_ERR_NOENDPT** - - - The message type in the message buffer did not map to a known - endpoint. - - - -The following values may be assigned to ``errno`` on failure. - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **INVAL** - - - Parameter(s) passed to the function were not valid, or the - underlying message processing environment was unable to - interpret the message. - - * - **ENOKEY** - - - The header information in the message buffer was invalid. - - * - **ENXIO** - - - No known endpoint for the message could be found. - - * - **EMSGSIZE** - - - The underlying transport refused to accept the message - because of a size value issue (message was not attempted to - be sent). - - * - **EFAULT** - - - The message referenced by the message buffer is corrupt (nil - pointer or bad internal length). - - * - **EBADF** - - - Internal RMR error; information provided to the message - transport environment was not valid. - - * - **ENOTSUP** - - - Sending was not supported by the underlying message - transport. - - * - **EFSM** - - - The device is not in a state that can accept the message. - - * - **EAGAIN** - - - The device is not able to accept a message for sending. The - user application should attempt to resend. - - * - **EINTR** - - - The operation was interrupted by delivery of a signal before - the message was sent. - - * - **ETIMEDOUT** - - - The underlying message environment timed out during the send - process. - - * - **ETERM** - - - The underlying message environment is in a shutdown state. - - +The following values may be passed back in the *state* field +of the returned message buffer. + + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **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. + + * - **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. + + * - **RMR_ERR_BADARG** + - + The message buffer pointer did not refer to a valid message. + + * - **RMR_ERR_NOHDR** + - + The header in the message buffer was not valid or corrupted. + + * - **RMR_ERR_NOENDPT** + - + The message type in the message buffer did not map to a known + endpoint. + + + +The following values may be assigned to ``errno`` on failure. + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **INVAL** + - + Parameter(s) passed to the function were not valid, or the + underlying message processing environment was unable to + interpret the message. + + * - **ENOKEY** + - + The header information in the message buffer was invalid. + + * - **ENXIO** + - + No known endpoint for the message could be found. + + * - **EMSGSIZE** + - + The underlying transport refused to accept the message + because of a size value issue (message was not attempted to + be sent). + + * - **EFAULT** + - + The message referenced by the message buffer is corrupt (nil + pointer or bad internal length). + + * - **EBADF** + - + Internal RMR error; information provided to the message + transport environment was not valid. + + * - **ENOTSUP** + - + Sending was not supported by the underlying message + transport. + + * - **EFSM** + - + The device is not in a state that can accept the message. + + * - **EAGAIN** + - + The device is not able to accept a message for sending. The + user application should attempt to resend. + + * - **EINTR** + - + The operation was interrupted by delivery of a signal before + the message was sent. + + * - **ETIMEDOUT** + - + The underlying message environment timed out during the send + process. + + * - **ETERM** + - + The underlying message environment is in a shutdown state. + + EXAMPLE ------- -The following is a simple example of how the -``rmr_send_msg`` function is called. In this example, the -send message buffer is saved between calls and reused -eliminating alloc/free 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 - - 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 - if( ! msg ) { - return ERROR; - } else { - if( msg->state != RMR_OK ) { - // check for RMR_ERR_RETRY, and resend if needed - // else return error - } - } - return OK; - - +The following is a simple example of how the +``rmr_send_msg`` function is called. In this example, the +send message buffer is saved between calls and reused +eliminating alloc/free 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 + + 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 + if( ! msg ) { + return ERROR; + } else { + if( msg->state != RMR_OK ) { + // check for RMR_ERR_RETRY, and resend if needed + // else return error + } + } + return OK; + + SEE ALSO -------- -rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), -rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3), -rmr_rts_msg(3), rmr_ready(3), rmr_mk_ring(3), -rmr_ring_free(3), rmr_torcv_rcv(3), rmr_wh_send_msg(3) +rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), +rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3), +rmr_rts_msg(3), rmr_ready(3), rmr_mk_ring(3), +rmr_ring_free(3), rmr_torcv_rcv(3), rmr_wh_send_msg(3) diff --git a/docs/rmr_set_fack.3.rst b/docs/rmr_set_fack.3.rst index 84f09fc..10cdf59 100644 --- a/docs/rmr_set_fack.3.rst +++ b/docs/rmr_set_fack.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_set_fack -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_set_fack +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,44 +19,44 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_set_fack +rmr_set_fack SYNOPSIS -------- - -:: - - #include - - void rmr_set_fack( void* vctx ); - - + +:: + + #include + + void rmr_set_fack( void* vctx ); + + DESCRIPTION ----------- -The ``rmr_set_fack`` function enables *fast TCP -acknowledgements* if the underlying transport library -supports it. This might be useful for applications which must -send messages at a maximum rate. +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 at a maximum rate. RETURN VALUE ------------ -There is no return value. +There is no return value. ERRORS ------ -This function does not generate any errors. +This function does not generate any errors. SEE ALSO -------- -rmr_init(3), +rmr_init(3), diff --git a/docs/rmr_set_stimeout.3.rst b/docs/rmr_set_stimeout.3.rst index fbd1071..22f4423 100644 --- a/docs/rmr_set_stimeout.3.rst +++ b/docs/rmr_set_stimeout.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_set_stimeout -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_set_stimeout +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,98 +19,98 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_set_stimeout +rmr_set_stimeout SYNOPSIS -------- - -:: - - #include - - int rmr_set_stimeout( void* vctx, int rloops ); - - + +:: + + #include + + int rmr_set_stimeout( void* vctx, int rloops ); + + DESCRIPTION ----------- -The ``rmr_set_stimeout`` function sets the configuration for -how RMR will retry message send operations which complete -with either a *timeout* or *again* completion value. (Send -operations include all of the possible message send -functions: *rmr_send_msg(), rmr_call(), rmr_rts_msg()* and -*rmr_wh_send_msg().* The *rloops* parameter sets the maximum -number of retry loops that will be attempted before giving up -and returning the unsuccessful state to the user application. -Each retry loop is approximately 1000 attempts, and RMR does -**not** invoke any sleep function between retries in the -loop; a small, 1 mu-sec, sleep is executed between loop sets -if the *rloops* value is greater than 1. - +The ``rmr_set_stimeout`` function sets the configuration for +how RMR will retry message send operations which complete +with either a *timeout* or *again* completion value. (Send +operations include all of the possible message send +functions: *rmr_send_msg(), rmr_call(), rmr_rts_msg()* and +*rmr_wh_send_msg().* The *rloops* parameter sets the maximum +number of retry loops that will be attempted before giving up +and returning the unsuccessful state to the user application. +Each retry loop is approximately 1000 attempts, and RMR does +**not** invoke any sleep function between retries in the +loop; a small, 1 mu-sec, sleep is executed between loop sets +if the *rloops* value is greater than 1. + Disabling Retries ----------------- -By default, the send operations will execute with an *rloop* -setting of 1; each send operation will attempt to resend the -message approximately 1000 times before giving up. If the -user application does not want to have send operations retry -when the underlying transport mechanism indicates *timeout* -or *again,* the application should invoke this function and -pass a value of 0 (zero) for *rloops.* With this setting, all -RMR send operations will attempt a send operation only -**once,** returning immediately to the caller with the state -of that single attempt. +By default, the send operations will execute with an *rloop* +setting of 1; each send operation will attempt to resend the +message approximately 1000 times before giving up. If the +user application does not want to have send operations retry +when the underlying transport mechanism indicates *timeout* +or *again,* the application should invoke this function and +pass a value of 0 (zero) for *rloops.* With this setting, all +RMR send operations will attempt a send operation only +**once,** returning immediately to the caller with the state +of that single attempt. RETURN VALUE ------------ -This function returns a -1 to indicate that the *rloops* -value could not be set, and the value *RMR_OK* to indicate -success. +This function returns a -1 to indicate that the *rloops* +value could not be set, and the value *RMR_OK* to indicate +success. ERRORS ------ -Currently errno is **not** set by this function; the only -cause of a failure is an invalid context (*vctx*) pointer. +Currently errno is **not** set by this function; the only +cause of a failure is an invalid context (*vctx*) pointer. EXAMPLE ------- -The following is a simple example of how the -``rmr_set_stimeout`` function is called. - - -:: - - #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 - - mr_context = rmr_init( port, max_size, NO_FLAGS ); - if( mr_context != NULL ) { - rmr_set_stimeout( mr_context, 0 ); // turn off retries - } - - +The following is a simple example of how the +``rmr_set_stimeout`` function is called. + + +:: + + #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 + + mr_context = rmr_init( port, max_size, NO_FLAGS ); + if( mr_context != NULL ) { + rmr_set_stimeout( mr_context, 0 ); // turn off retries + } + + SEE ALSO -------- -rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), -rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3), -rmr_rts_msg(3), rmr_ready(3), rmr_mk_ring(3), -rmr_ring_free(3), rmr_send_msg(3), rmr_torcv_rcv(3), -rmr_wh_send_msg(3) +rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), +rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3), +rmr_rts_msg(3), rmr_ready(3), rmr_mk_ring(3), +rmr_ring_free(3), rmr_send_msg(3), rmr_torcv_rcv(3), +rmr_wh_send_msg(3) diff --git a/docs/rmr_set_trace.3.rst b/docs/rmr_set_trace.3.rst index 89c114e..25a0e69 100644 --- a/docs/rmr_set_trace.3.rst +++ b/docs/rmr_set_trace.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_set_trace -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_set_trace +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,49 +19,49 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_set_trace +rmr_set_trace SYNOPSIS -------- - -:: - - #include - - int rmr_set_trace( rmr_mbuf_t* mbuf, unsigned char* data, int len ) - + +:: + + #include + + int rmr_set_trace( rmr_mbuf_t* mbuf, unsigned char* data, int len ) + DESCRIPTION ----------- -The ``rmr_set_trace`` function will copy ``len`` bytes from -``data`` into the trace portion of ``mbuf.`` If the trace -area of ``mbuf`` is not the correct size, the message buffer -will be reallocated to ensure that enough space is available -for the trace data. +The ``rmr_set_trace`` function will copy ``len`` bytes from +``data`` into the trace portion of ``mbuf.`` If the trace +area of ``mbuf`` is not the correct size, the message buffer +will be reallocated to ensure that enough space is available +for the trace data. RETURN VALUE ------------ -The ``rmr_set_trace`` function returns the number of bytes -successfully copied to the message. If 0 is returned either -the message pointer was nil, or the size in the parameters -was <= 0. +The ``rmr_set_trace`` function returns the number of bytes +successfully copied to the message. If 0 is returned either +the message pointer was nil, or the size in the parameters +was <= 0. SEE ALSO -------- -rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3), -rmr_bytes2payload(3), rmr_call(3), rmr_free_msg(3), -rmr_get_rcvfd(3), rmr_get_meid(3), rmr_get_trace(3), -rmr_get_trlen(3), rmr_init(3), rmr_init_trace(3), -rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), -rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3), -rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3), -rmr_ring_free(3), rmr_str2meid(3), rmr_str2xact(3), -rmr_wh_open(3), rmr_wh_send_msg(3) +rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3), +rmr_bytes2payload(3), rmr_call(3), rmr_free_msg(3), +rmr_get_rcvfd(3), rmr_get_meid(3), rmr_get_trace(3), +rmr_get_trlen(3), rmr_init(3), rmr_init_trace(3), +rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), +rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3), +rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3), +rmr_ring_free(3), rmr_str2meid(3), rmr_str2xact(3), +rmr_wh_open(3), rmr_wh_send_msg(3) diff --git a/docs/rmr_set_vlevel.3.rst b/docs/rmr_set_vlevel.3.rst index 01bf715..37bd8fd 100644 --- a/docs/rmr_set_vlevel.3.rst +++ b/docs/rmr_set_vlevel.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_set_vlevel -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_set_vlevel +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,99 +19,99 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_set_vlevel +rmr_set_vlevel SYNOPSIS -------- - -:: - - #include - #include - - void rmr_set_vlevel( int new_level ) - + +:: + + #include + #include + + void rmr_set_vlevel( int new_level ) + DESCRIPTION ----------- -The ``rmr_set_vlevel`` allows the user programme to set the -verbosity level which is used to determine the messages RMR -writes to standard error. The ``new_vlevel`` value must be -one of the following constants which have the indicated -meanings: - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **RMR_VL_OFF** - - - Turns off all message writing. This includes the stats and - debugging messages generated by the route collector thread - which are normally affected only by the externally managed - verbose level file (and related environment variable). - - * - **RMR_VL_CRIT** - - - Write only messages of critical importance. From the point of - view of RMR, when a critical proper behaviour of the library - cannot be expected or guaranteed. - - * - **RMR_VL_ERR** - - - Include error messages in the output. An error is an event - from which RMR has no means to recover. Continued proper - execution is likely except where the affected connection - and/or component mentioned in the error is concerned. - - * - **RMR_VL_WARN** - - - Include warning messages in the output. A warning indicates - an event which is not considered to be normal, but is - expected and continued acceptable behaviour of the system is - assured. - - * - **RMR_VL_INFO** - - - Include informational messagees in the output. Informational - messages include some diagnostic information which explain - the activities of RMR. - - * - **RMR_VL_DEBUG** - - - Include all debugging messages in the output. Debugging must - have also been enabled during the build as a precaution to - accidentally enabling this level of output as it can grossly - affect performance. - - - -Generally RMR does not write messages to the standard error -device from *critical path* functions, therefore it is -usually not harmful to enable a verbosity level of either -RMR_VL_CRIT or RMR_VL_ERR. - -Messages written from the route table collection thread are -still governed by the value placed into the verbose level -control file (see the man page for rmr_init()); those -messages are affected only when logging is completely -disabled by passing RMR_VL_OFF to this function. - -The verbosity level can also be set via an environment -variable prior to the start of the RMR based application. The -environment variable is read only during initialisation; if -the programme must change the value during execution, this -function must be used. The default value, if this function is -never called, and the environment variable is not present, is -RMR_VL_ERR. +The ``rmr_set_vlevel`` allows the user programme to set the +verbosity level which is used to determine the messages RMR +writes to standard error. The ``new_vlevel`` value must be +one of the following constants which have the indicated +meanings: + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **RMR_VL_OFF** + - + Turns off all message writing. This includes the stats and + debugging messages generated by the route collector thread + which are normally affected only by the externally managed + verbose level file (and related environment variable). + + * - **RMR_VL_CRIT** + - + Write only messages of critical importance. From the point of + view of RMR, when a critical proper behaviour of the library + cannot be expected or guaranteed. + + * - **RMR_VL_ERR** + - + Include error messages in the output. An error is an event + from which RMR has no means to recover. Continued proper + execution is likely except where the affected connection + and/or component mentioned in the error is concerned. + + * - **RMR_VL_WARN** + - + Include warning messages in the output. A warning indicates + an event which is not considered to be normal, but is + expected and continued acceptable behaviour of the system is + assured. + + * - **RMR_VL_INFO** + - + Include informational messagees in the output. Informational + messages include some diagnostic information which explain + the activities of RMR. + + * - **RMR_VL_DEBUG** + - + Include all debugging messages in the output. Debugging must + have also been enabled during the build as a precaution to + accidentally enabling this level of output as it can grossly + affect performance. + + + +Generally RMR does not write messages to the standard error +device from *critical path* functions, therefore it is +usually not harmful to enable a verbosity level of either +RMR_VL_CRIT or RMR_VL_ERR. + +Messages written from the route table collection thread are +still governed by the value placed into the verbose level +control file (see the man page for rmr_init()); those +messages are affected only when logging is completely +disabled by passing RMR_VL_OFF to this function. + +The verbosity level can also be set via an environment +variable prior to the start of the RMR based application. The +environment variable is read only during initialisation; if +the programme must change the value during execution, this +function must be used. The default value, if this function is +never called, and the environment variable is not present, is +RMR_VL_ERR. SEE ALSO -------- -rmr_init(3) +rmr_init(3) diff --git a/docs/rmr_str2meid.3.rst b/docs/rmr_str2meid.3.rst index ae8b57b..b501acf 100644 --- a/docs/rmr_str2meid.3.rst +++ b/docs/rmr_str2meid.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_str2meid -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_str2meid +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,63 +19,63 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_str2meid +rmr_str2meid SYNOPSIS -------- - -:: - - #include - - int rmr_str2meid( rmr_mbuf_t* mbuf, unsigned char* src, int len ) - + +:: + + #include + + int rmr_str2meid( rmr_mbuf_t* mbuf, unsigned char* src, int len ) + DESCRIPTION ----------- -The ``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 -``RMR_MAX_MEID`` and if string length is larger than this -value, then **nothing** will be copied. (Note, this differs -slightly from the behaviour of the ``lrmr_bytes2meid()`` -function.) +The ``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 +``RMR_MAX_MEID`` and if string length is larger than this +value, then **nothing** will be copied. (Note, this differs +slightly from the behaviour of the ``lrmr_bytes2meid()`` +function.) 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 errors listed below. +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. ERRORS ------ -If the return value is not RMR_OK, then it will be set to one -of the values below. - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **RMR_ERR_BADARG** - - - The message, or an internal portion of the message, was - corrupted or the pointer was invalid. - - * - **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. - - +If the return value is not RMR_OK, then it will be set to one +of the values below. + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **RMR_ERR_BADARG** + - + The message, or an internal portion of the message, was + corrupted or the pointer was invalid. + + * - **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. + + EXAMPLE @@ -86,9 +86,9 @@ EXAMPLE SEE ALSO -------- -rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), -rmr_get_meid(3), rmr_get_rcvfd(3), rmr_payload_size(3), -rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3), -rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3), -rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3), -rmr_bytes2meid(3), rmr_wh_open(3), rmr_wh_send_msg(3) +rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), +rmr_get_meid(3), rmr_get_rcvfd(3), rmr_payload_size(3), +rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3), +rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3), +rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3), +rmr_bytes2meid(3), rmr_wh_open(3), rmr_wh_send_msg(3) diff --git a/docs/rmr_str2xact.3.rst b/docs/rmr_str2xact.3.rst index 968f0c6..3db1e8e 100644 --- a/docs/rmr_str2xact.3.rst +++ b/docs/rmr_str2xact.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_str2xact -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_str2xact +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,63 +19,63 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_str2xact +rmr_str2xact SYNOPSIS -------- - -:: - - #include - - int rmr_str2xact( rmr_mbuf_t* mbuf, unsigned char* src, int len ) - + +:: + + #include + + int rmr_str2xact( rmr_mbuf_t* mbuf, unsigned char* src, int len ) + DESCRIPTION ----------- -The ``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 -``RMR_MAX_XID`` and if string length is larger than this -value, then **nothing** will be copied. (Note, this differs -slightly from the behaviour of the ``lrmr_bytes2xact()`` -function.) +The ``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 +``RMR_MAX_XID`` and if string length is larger than this +value, then **nothing** will be copied. (Note, this differs +slightly from the behaviour of the ``lrmr_bytes2xact()`` +function.) 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 errors listed below. +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. ERRORS ------ -If the return value is not RMR_OK, then it will be set to one -of the values below. - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **RMR_ERR_BADARG** - - - The message, or an internal portion of the message, was - corrupted or the pointer was invalid. - - * - **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. - - +If the return value is not RMR_OK, then it will be set to one +of the values below. + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **RMR_ERR_BADARG** + - + The message, or an internal portion of the message, was + corrupted or the pointer was invalid. + + * - **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. + + EXAMPLE @@ -86,10 +86,10 @@ EXAMPLE SEE ALSO -------- -rmr_alloc_msg(3), rmr_bytes2meid(3), rmr_bytes2xact(3), -rmr_call(3), rmr_free_msg(3), rmr_get_meid(3), -rmr_get_rcvfd(3), rmr_get_xact(3), rmr_payload_size(3), -rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3), -rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3), -rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3), -rmr_str2meid(3), rmr_wh_open(3), rmr_wh_send_msg(3) +rmr_alloc_msg(3), rmr_bytes2meid(3), rmr_bytes2xact(3), +rmr_call(3), rmr_free_msg(3), rmr_get_meid(3), +rmr_get_rcvfd(3), rmr_get_xact(3), rmr_payload_size(3), +rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3), +rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3), +rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3), +rmr_str2meid(3), rmr_wh_open(3), rmr_wh_send_msg(3) diff --git a/docs/rmr_support.3.rst b/docs/rmr_support.3.rst index 648bedf..cc63e43 100644 --- a/docs/rmr_support.3.rst +++ b/docs/rmr_support.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_support -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_support +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,118 +19,118 @@ RMR LIBRARY FUNCTIONS NAME ---- -RMR support functions +RMR support functions SYNOPSIS -------- - -:: - - #include - #include - - char* rmr_fib( char* fname ); - int rmr_has_str( char const* buf, char const* str, char sep, int max ); - int rmr_tokenise( char* buf, char** tokens, int max, char sep ); - void* rmr_mk_ring( int size ); - void rmr_ring_free( void* vr ); - - static inline void* rmr_ring_extract( void* vr ) - static inline int rmr_ring_insert( void* vr, void* new_data ) - + +:: + + #include + #include + + char* rmr_fib( char* fname ); + int rmr_has_str( char const* buf, char const* str, char sep, int max ); + int rmr_tokenise( char* buf, char** tokens, int max, char sep ); + void* rmr_mk_ring( int size ); + void rmr_ring_free( void* vr ); + + static inline void* rmr_ring_extract( void* vr ) + static inline int rmr_ring_insert( void* vr, void* new_data ) + DESCRIPTION ----------- -These functions support the RMR library, and are made -available to user applications as some (e.g. route table -generators) might need and/or want to make use of them. The -``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 buffered -I/O hoops. - -The ``rmr_has_str`` function accepts a *buffer* containing a -set of delimited tokens (e.g. foo,bar,goo) and returns true -if the target string, *str,* matches one of the tokens. The -*sep* parameter provides the separation character in the -buffer (e.g a comma) and *max* indicates the maximum number -of tokens to split the buffer into before checking. - -The ``rmr_tokenise`` function is a simple tokeniser which -splits *buf* into tokens at each occurrence of *sep*. -Multiple occurrences of the separator character (e.g. a,,b) -result in a nil token. Pointers to the tokens are placed into -the *tokens* array provided by the caller which is assumed to -have at least enough space for *max* entries. - -The ``rmr_mk_ring`` function creates a buffer ring with -*size* entries. - -The ``rmr_ring_free`` function accepts a pointer to a ring -context and frees the associated memory. - -The ``rmr_ring_insert`` and ``rmr_ring_extract`` functions -are provided as static inline functions via the -*rmr/ring_inline.h* header file. These functions both accept -the ring *context* returned by ``mk_ring,`` and either insert -a pointer at the next available slot (tail) or extract the -data at the head. +These functions support the RMR library, and are made +available to user applications as some (e.g. route table +generators) might need and/or want to make use of them. The +``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 buffered +I/O hoops. + +The ``rmr_has_str`` function accepts a *buffer* containing a +set of delimited tokens (e.g. foo,bar,goo) and returns true +if the target string, *str,* matches one of the tokens. The +*sep* parameter provides the separation character in the +buffer (e.g a comma) and *max* indicates the maximum number +of tokens to split the buffer into before checking. + +The ``rmr_tokenise`` function is a simple tokeniser which +splits *buf* into tokens at each occurrence of *sep*. +Multiple occurrences of the separator character (e.g. a,,b) +result in a nil token. Pointers to the tokens are placed into +the *tokens* array provided by the caller which is assumed to +have at least enough space for *max* entries. + +The ``rmr_mk_ring`` function creates a buffer ring with +*size* entries. + +The ``rmr_ring_free`` function accepts a pointer to a ring +context and frees the associated memory. + +The ``rmr_ring_insert`` and ``rmr_ring_extract`` functions +are provided as static inline functions via the +*rmr/ring_inline.h* header file. These functions both accept +the ring *context* returned by ``mk_ring,`` and either insert +a pointer at the next available slot (tail) or extract the +data at the head. RETURN VALUES ------------- -The following are the return values for each of these -functions. - -The ``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, the -caller should use the system stat function call to make that -determination. - -The ``rmr_has_str`` function returns 1 if *buf* contains the -token referenced by &ita and false (0) if it does not. On -error, a -1 value is returned and ``errno`` is set -accordingly. - -The ``rmr_tokenise`` function returns the actual number of -token pointers placed into *tokens* - -The ``rmr_mk_ring`` function returns a void pointer which is -the *context* for the ring. - -The ``rmr_ring_insert`` function returns 1 if the data was -successfully inserted into the ring, and 0 if the ring is -full and the pointer could not be deposited. - -The ``rmr_ring_extract`` will return the data which is at the -head of the ring, or NULL if the ring is empty. +The following are the return values for each of these +functions. + +The ``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, the +caller should use the system stat function call to make that +determination. + +The ``rmr_has_str`` function returns 1 if *buf* contains the +token referenced by &ita and false (0) if it does not. On +error, a -1 value is returned and ``errno`` is set +accordingly. + +The ``rmr_tokenise`` function returns the actual number of +token pointers placed into *tokens* + +The ``rmr_mk_ring`` function returns a void pointer which is +the *context* for the ring. + +The ``rmr_ring_insert`` function returns 1 if the data was +successfully inserted into the ring, and 0 if the ring is +full and the pointer could not be deposited. + +The ``rmr_ring_extract`` will return the data which is at the +head of the ring, or NULL if the ring is empty. ERRORS ------ -Not many of these functions set the value in ``errno,`` -however the value may be one of the following: - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **INVAL** - - - Parameter(s) passed to the function were not valid. - - +Not many of these functions set the value in ``errno,`` +however the value may be one of the following: + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **INVAL** + - + Parameter(s) passed to the function were not valid. + + EXAMPLE @@ -141,6 +141,6 @@ EXAMPLE SEE ALSO -------- -rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), -rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), -rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3), +rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), +rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), +rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3), diff --git a/docs/rmr_torcv_msg.3.rst b/docs/rmr_torcv_msg.3.rst index 21ad8ba..66f98e3 100644 --- a/docs/rmr_torcv_msg.3.rst +++ b/docs/rmr_torcv_msg.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_torcv_msg -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_torcv_msg +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,138 +19,138 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_torcv_msg +rmr_torcv_msg SYNOPSIS -------- - -:: - - #include - - rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to ); - + +:: + + #include + + rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to ); + DESCRIPTION ----------- -The ``rmr_torcv_msg`` function will pause for *ms_to* -milliseconds waiting 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 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 ``rmr_call,`` the -oldest message is removed from the queue and returned without -delay. - -The *vctx* pointer is the pointer returned by the -``rmr_init`` function. *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. When no buffer is available to supply, the -receive function will allocate one. +The ``rmr_torcv_msg`` function will pause for *ms_to* +milliseconds waiting 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 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 ``rmr_call,`` the +oldest message is removed from the queue and returned without +delay. + +The *vctx* pointer is the pointer returned by the +``rmr_init`` function. *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. When no buffer is available to supply, the +receive function will allocate one. RETURN VALUE ------------ -The function returns a pointer to the ``rmr_mbuf_t`` -structure which references the message information (state, -length, payload), or a nil pointer in the case of an extreme -error. +The function returns a pointer to the ``rmr_mbuf_t`` +structure which references the message information (state, +length, payload), or a nil pointer in the case of an extreme +error. ERRORS ------ -The *state* field in the message buffer will be one of the -following: - - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **RMR_OK** - - - The message buffer (payload) references the received data. - - * - **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 initialise, the poll mechanism, it is - likely that message receives will never be successful. - - * - **RMR_ERR_TIMEOUT** - - - The timeout expired before a complete message was received. - All other fields in the message buffer are not valid. - - * - **RMR_ERR_EMPTY** - - - A message was received, but it had no payload. All other - fields in the message buffer are not valid. - - -Upon return the system error number, *errno* might be set -with a value that can help to explain the meaning of the -state indicated in the message. The following are possible: - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **INVAL** - - - Parameter(s) passed to the function were not valid. - - * - **EBADF** - - - The underlying message transport is unable to process the - request. - - * - **ENOTSUP** - - - The underlying message transport is unable to process the - request. - - * - **EFSM** - - - The underlying message transport is unable to process the - request. - - * - **EAGAIN** - - - The underlying message transport is unable to process the - request. - - * - **EINTR** - - - The underlying message transport is unable to process the - request. - - * - **ETIMEDOUT** - - - The underlying message transport is unable to process the - request. - - * - **ETERM** - - - The underlying message transport is unable to process the - request. - - +The *state* field in the message buffer will be one of the +following: + + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **RMR_OK** + - + The message buffer (payload) references the received data. + + * - **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 initialise, the poll mechanism, it is + likely that message receives will never be successful. + + * - **RMR_ERR_TIMEOUT** + - + The timeout expired before a complete message was received. + All other fields in the message buffer are not valid. + + * - **RMR_ERR_EMPTY** + - + A message was received, but it had no payload. All other + fields in the message buffer are not valid. + + +Upon return the system error number, *errno* might be set +with a value that can help to explain the meaning of the +state indicated in the message. The following are possible: + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **INVAL** + - + Parameter(s) passed to the function were not valid. + + * - **EBADF** + - + The underlying message transport is unable to process the + request. + + * - **ENOTSUP** + - + The underlying message transport is unable to process the + request. + + * - **EFSM** + - + The underlying message transport is unable to process the + request. + + * - **EAGAIN** + - + The underlying message transport is unable to process the + request. + + * - **EINTR** + - + The underlying message transport is unable to process the + request. + + * - **ETIMEDOUT** + - + The underlying message transport is unable to process the + request. + + * - **ETERM** + - + The underlying message transport is unable to process the + request. + + EXAMPLE @@ -161,8 +161,8 @@ EXAMPLE SEE ALSO -------- -rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), -rmr_get_rcvfd(3), rmr_init(3), rmr_payload_size(3), -rmr_rcv_msg(3), rmr_send_msg(3), rmr_rcv_specific(3), -rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3), -rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3) +rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), +rmr_get_rcvfd(3), rmr_init(3), rmr_payload_size(3), +rmr_rcv_msg(3), rmr_send_msg(3), rmr_rcv_specific(3), +rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3), +rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3) diff --git a/docs/rmr_trace_ref.3.rst b/docs/rmr_trace_ref.3.rst index b5a7320..b9f4c8a 100644 --- a/docs/rmr_trace_ref.3.rst +++ b/docs/rmr_trace_ref.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_trace_ref -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_trace_ref +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,48 +19,48 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_trace_ref +rmr_trace_ref SYNOPSIS -------- - -:: - - #include - - int rmr_trace_ref( rmr_mbuf_t* mbuf, int* sizeptr ) - + +:: + + #include + + int rmr_trace_ref( rmr_mbuf_t* mbuf, int* sizeptr ) + DESCRIPTION ----------- -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. +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 ------------ -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. +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. SEE ALSO -------- -rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3), -rmr_bytes2meid(3), rmr_call(3), rmr_free_msg(3), -rmr_get_rcvfd(3), rmr_get_trlen(3), rmr_init(3), -rmr_init_trace(3), rmr_payload_size(3), rmr_send_msg(3), -rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), -rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), -rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3), -rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3), -rmr_set_trace(3) +rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3), +rmr_bytes2meid(3), rmr_call(3), rmr_free_msg(3), +rmr_get_rcvfd(3), rmr_get_trlen(3), rmr_init(3), +rmr_init_trace(3), rmr_payload_size(3), rmr_send_msg(3), +rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), +rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), +rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3), +rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3), +rmr_set_trace(3) diff --git a/docs/rmr_tralloc_msg.3.rst b/docs/rmr_tralloc_msg.3.rst index 02a8a7c..59ee5b3 100644 --- a/docs/rmr_tralloc_msg.3.rst +++ b/docs/rmr_tralloc_msg.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_tralloc_msg -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_tralloc_msg +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,147 +19,147 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_tralloc_msg +rmr_tralloc_msg SYNOPSIS -------- - -:: - - #include - - rmr_mbuf_t* rmr_tralloc_msg( void* vctx, int size, - int trace_size, unsigned const char *tr_data ); - + +:: + + #include + + rmr_mbuf_t* rmr_tralloc_msg( void* vctx, int size, + int trace_size, unsigned const char *tr_data ); + DESCRIPTION ----------- -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. 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 -copied into that portion of the message. The *vctx* parameter -is the void context pointer that was returned by the -*rmr_init* function. - -The pointer to the message buffer returned is a structure -which has some user application visible fields; the structure -is described in ``rmr.h,`` and is illustrated below. - - -:: - - typedef struct { - int state; - int mtype; - int len; - unsigned char* payload; - unsigned char* xaction; - } rmr_mbuf_t; - - -Where: - - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **state** - - - Is the current buffer state. Following a call to - ``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). When the state is - ``a_OK`` the buffer represents an empty buffer that the - application may fill in in preparation to send. - - * - **mtype** - - - When sending a message, the application is expected to set - this field 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. - - * - **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 indicate the number of bytes - in the payload which are valid. - - * - **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 ``rmr_send, rmr_call`` or - ``rmr_reply`` function call. Once the buffer has been passed - back to a a library function the user programme should - **NOT** make use of the payload pointer. - - * - **xaction** - - - The *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 ``rmr_call`` 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 *xaction* field. - - +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. 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 +copied into that portion of the message. The *vctx* parameter +is the void context pointer that was returned by the +*rmr_init* function. + +The pointer to the message buffer returned is a structure +which has some user application visible fields; the structure +is described in ``rmr.h,`` and is illustrated below. + + +:: + + typedef struct { + int state; + int mtype; + int len; + unsigned char* payload; + unsigned char* xaction; + } rmr_mbuf_t; + + +Where: + + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **state** + - + Is the current buffer state. Following a call to + ``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). When the state is + ``a_OK`` the buffer represents an empty buffer that the + application may fill in in preparation to send. + + * - **mtype** + - + When sending a message, the application is expected to set + this field 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. + + * - **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 indicate the number of bytes + in the payload which are valid. + + * - **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 ``rmr_send, rmr_call`` or + ``rmr_reply`` function call. Once the buffer has been passed + back to a a library function the user programme should + **NOT** make use of the payload pointer. + + * - **xaction** + - + The *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 ``rmr_call`` 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 *xaction* field. + + RETURN VALUE ------------ -The function returns a pointer to a ``rmr_mbuf`` structure, -or NULL on error. +The function returns a pointer to a ``rmr_mbuf`` structure, +or NULL on error. ERRORS ------ - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **ENOMEM** - - - Unable to allocate memory. - - + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **ENOMEM** + - + Unable to allocate memory. + + SEE ALSO -------- -rmr_alloc_msg(3), rmr_mbuf(3) rmr_call(3), rmr_free_msg(3), -rmr_init(3), rmr_init_trace(3), rmr_get_trace(3), -rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3), -rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), -rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), -rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3) +rmr_alloc_msg(3), rmr_mbuf(3) rmr_call(3), rmr_free_msg(3), +rmr_init(3), rmr_init_trace(3), rmr_get_trace(3), +rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3), +rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), +rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), +rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3) diff --git a/docs/rmr_wh_call.3.rst b/docs/rmr_wh_call.3.rst index 9e6da4e..1024ca3 100644 --- a/docs/rmr_wh_call.3.rst +++ b/docs/rmr_wh_call.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_wh_call -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_wh_call +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,208 +19,208 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_wh_call +rmr_wh_call SYNOPSIS -------- - -:: - - #include - - rmr_mbuf_t* rmr_wh_call( void* vctx, rmr_whid_t whid, rmr_mbuf_t* msg, int call_id, int max_wait ) - - + +:: + + #include + + rmr_mbuf_t* rmr_wh_call( void* vctx, rmr_whid_t whid, rmr_mbuf_t* msg, int call_id, int max_wait ) + + DESCRIPTION ----------- -The ``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 ``max_wait`` number of milliseconds has passed. In -order for the response to be recognised as a response, the -remote 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 -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 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 -``rmr_wh_call()`` function from potentially non-threaded -concurrent applications (such as Go's goroutines) is -possible. +The ``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 ``max_wait`` number of milliseconds has passed. In +order for the response to be recognised as a response, the +remote 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 +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 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 +``rmr_wh_call()`` function from potentially non-threaded +concurrent applications (such as Go's goroutines) is +possible. Retries ------- -The send operations in RMR will retry *soft* send failures -until one of three conditions occurs: - - -* The message is sent without error - -* The underlying transport reports a *hard* failure - -* The maximum number of retry loops has been attempted - - -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 -allowing the user application to completely disable retires -(set to 0), or to increase the number of retry loops. +The send operations in RMR will retry *soft* send failures +until one of three conditions occurs: + + +* The message is sent without error + +* The underlying transport reports a *hard* failure + +* The maximum number of retry loops has been attempted + + +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 +allowing the user application to completely disable retires +(set to 0), or to increase the number of retry loops. Transport Level Blocking ------------------------ -The underlying transport mechanism used to send messages is -configured in *non-blocking* mode. This means that if a -message cannot be sent immediately the transport mechanism -will **not** pause with the assumption that the inability to -send will clear quickly (within a few milliseconds). This -means that when the retry loop is completely disabled (set to -0), that the failure to accept a message for sending by the -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 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. +The underlying transport mechanism used to send messages is +configured in *non-blocking* mode. This means that if a +message cannot be sent immediately the transport mechanism +will **not** pause with the assumption that the inability to +send will clear quickly (within a few milliseconds). This +means that when the retry loop is completely disabled (set to +0), that the failure to accept a message for sending by the +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 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 ------------ -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 ``RMR_OK.`` - -If a message is returned with a state which is anything other -than ``RMR_OK,`` the indication is that the send was not -successful. The user application must check the state and -determine the course of action. If the return value is NULL, -no message, the indication is that there was no response -received within the timeout (max_wait) period of time. +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 ``RMR_OK.`` + +If a message is returned with a state which is anything other +than ``RMR_OK,`` the indication is that the send was not +successful. The user application must check the state and +determine the course of action. If the return value is NULL, +no message, the indication is that there was no response +received within the timeout (max_wait) period of time. ERRORS ------ -The following values may be passed back in the *state* field -of the returned message buffer. - - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **RMR_ERR_WHID** - - - The wormhole ID passed in was not associated with an open - wormhole, or was out of range for a valid ID. - - * - **RMR_ERR_NOWHOPEN** - - - No wormholes exist, further attempt to validate the ID are - skipped. - - * - **RMR_ERR_BADARG** - - - The message buffer pointer did not refer to a valid message. - - * - **RMR_ERR_NOHDR** - - - The header in the message buffer was not valid or corrupted. - - +The following values may be passed back in the *state* field +of the returned message buffer. + + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **RMR_ERR_WHID** + - + The wormhole ID passed in was not associated with an open + wormhole, or was out of range for a valid ID. + + * - **RMR_ERR_NOWHOPEN** + - + No wormholes exist, further attempt to validate the ID are + skipped. + + * - **RMR_ERR_BADARG** + - + The message buffer pointer did not refer to a valid message. + + * - **RMR_ERR_NOHDR** + - + The header in the message buffer was not valid or corrupted. + + EXAMPLE ------- -The following is a simple example of how the a wormhole is -created (rmr_wh_open) and then how ``rmr_wh_send_msg`` -function is used to send messages. Some error checking is -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 - int i; - rmr_mbuf_t* sbuf; // send buffer - int count = 0; - int norm_msg_size = 1500; // most messages fit in this size - - mrc = rmr_init( "43086", norm_msg_size, RMRFL_NONE ); - if( mrc == NULL ) { - fprintf( stderr, "[FAIL] unable to initialise RMR environment\\n" ); - exit( 1 ); - } - - 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 - 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 - if( sbuf != NULL && sbuf->state = RMR_OK ) { - sprintf( stderr, "response: %s\\n", sbuf->payload ); // assume they sent a string - } else { - sprintf( stderr, "response not received, or send error\\n" ); - } - } - } - - sleep( 5 ); - } - } - +The following is a simple example of how the a wormhole is +created (rmr_wh_open) and then how ``rmr_wh_send_msg`` +function is used to send messages. Some error checking is +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 + int i; + rmr_mbuf_t* sbuf; // send buffer + int count = 0; + int norm_msg_size = 1500; // most messages fit in this size + + mrc = rmr_init( "43086", norm_msg_size, RMRFL_NONE ); + if( mrc == NULL ) { + fprintf( stderr, "[FAIL] unable to initialise RMR environment\\n" ); + exit( 1 ); + } + + 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 + 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 + if( sbuf != NULL && sbuf->state = RMR_OK ) { + sprintf( stderr, "response: %s\\n", sbuf->payload ); // assume they sent a string + } else { + sprintf( stderr, "response not received, or send error\\n" ); + } + } + } + + sleep( 5 ); + } + } + SEE ALSO -------- -rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), -rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3), -rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3), -rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3), -rmr_set_stimeout(3), rmr_wh_open(3), rmr_wh_close(3), -rmr_wh_state(3) +rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), +rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3), +rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3), +rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3), +rmr_set_stimeout(3), rmr_wh_open(3), rmr_wh_close(3), +rmr_wh_state(3) diff --git a/docs/rmr_wh_close.3.rst b/docs/rmr_wh_close.3.rst index 3741bab..64faa69 100644 --- a/docs/rmr_wh_close.3.rst +++ b/docs/rmr_wh_close.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_wh_close -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_wh_close +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,41 +19,41 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_wh_close +rmr_wh_close SYNOPSIS -------- - -:: - - #include - - void rmr_wh_close( void* vctx, rmr_whid_t whid ) - + +:: + + #include + + void rmr_wh_close( void* vctx, rmr_whid_t whid ) + DESCRIPTION ----------- -The ``rmr_wh_close`` function closes the wormhole associated -with 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 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. +The ``rmr_wh_close`` function closes the wormhole associated +with 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 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 -------- -rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), -rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3), -rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), -rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), -rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_open(3), -rmr_wh_send_msg(3) +rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), +rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3), +rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), +rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), +rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_open(3), +rmr_wh_send_msg(3) diff --git a/docs/rmr_wh_open.3.rst b/docs/rmr_wh_open.3.rst index d3a9134..ac7a3b8 100644 --- a/docs/rmr_wh_open.3.rst +++ b/docs/rmr_wh_open.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_wh_open -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_wh_open +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,112 +19,112 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_wh_open +rmr_wh_open SYNOPSIS -------- - -:: - - #include - - rmr_whid_t rmr_wh_open( void* vctx, char* target ) - + +:: + + #include + + rmr_whid_t rmr_wh_open( void* vctx, char* target ) + DESCRIPTION ----------- -The ``rmr_wh_open`` function creates a direct link for -sending, a wormhole, to another RMR based process. Sending -messages through a wormhole requires that the connection be -established overtly by the user application (via this -function), and that the ID returned by ``rmr_wh_open`` be -passed to the ``rmr_wh_send_msg`` function. - -*Vctx* is the RMR void context pointer that was returned by -the ``rmr_init`` function. *Target* is the *name and port,* -or *IP-address and port,* combination for the process that -the wormhole should be connected to. For example, -"localhost:6123". - -When invoked, this function immediately 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 buffering and retries differently. +The ``rmr_wh_open`` function creates a direct link for +sending, a wormhole, to another RMR based process. Sending +messages through a wormhole requires that the connection be +established overtly by the user application (via this +function), and that the ID returned by ``rmr_wh_open`` be +passed to the ``rmr_wh_send_msg`` function. + +*Vctx* is the RMR void context pointer that was returned by +the ``rmr_init`` function. *Target* is the *name and port,* +or *IP-address and port,* combination for the process that +the wormhole should be connected to. For example, +"localhost:6123". + +When invoked, this function immediately 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 buffering and retries differently. RETURN VALUE ------------ -The ``rmr_wh_open`` function returns a type -``rmr_whid_t`` which must be passed to the -``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 1 indicates that the -connection was established and that the ID is valid. +The ``rmr_wh_open`` function returns a type +``rmr_whid_t`` which must be passed to the +``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 1 indicates that the +connection was established and that the ID is valid. ERRORS ------ -The following error values are specifically set by this RMR -function. In some cases the error message of a system call is -propagated up, and thus this list might be incomplete. - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **EINVAL** - - - A parameter passed was not valid. - - * - **EACCESS** - - - The user application does not have the ability to establish a - wormhole to the indicated target (or maybe any target). - - * - **ECONNREFUSED** - - - The connection was refused. - - +The following error values are specifically set by this RMR +function. In some cases the error message of a system call is +propagated up, and thus this list might be incomplete. + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **EINVAL** + - + A parameter passed was not valid. + + * - **EACCESS** + - + The user application does not have the ability to establish a + wormhole to the indicated target (or maybe any target). + + * - **ECONNREFUSED** + - + The connection was refused. + + EXAMPLE ------- - -:: - - void* rmc; - rmr_whid_t wh; - - 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", - strerror( errno ) ); - } - + +:: + + void* rmc; + rmr_whid_t wh; + + 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", + strerror( errno ) ); + } + SEE ALSO -------- -rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), -rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3), -rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), -rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), -rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_close(3), -rmr_wh_send_msg(3), rmr_wh_state(3) +rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), +rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3), +rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), +rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), +rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_close(3), +rmr_wh_send_msg(3), rmr_wh_state(3) diff --git a/docs/rmr_wh_send_msg.3.rst b/docs/rmr_wh_send_msg.3.rst index 7de91a8..66af85b 100644 --- a/docs/rmr_wh_send_msg.3.rst +++ b/docs/rmr_wh_send_msg.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_wh_send_msg -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_wh_send_msg +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,264 +19,264 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_wh_send_msg +rmr_wh_send_msg SYNOPSIS -------- - -:: - - #include - - rmr_mbuf_t* rmr_wh_send_msg( void* vctx, rmr_whid_t id, rmr_mbuf_t* msg ) - + +:: + + #include + + rmr_mbuf_t* rmr_wh_send_msg( void* vctx, rmr_whid_t id, rmr_mbuf_t* msg ) + DESCRIPTION ----------- -The ``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 *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 -caller may leave the message type unspecified in the message -buffer (unless it is needed by the receiving process). - -*Vctx* is the RMR void context pointer that was returned by -the ``rmr_init`` function. 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 *rmr_rcv_msg()* can be passed to -this function. +The ``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 *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 +caller may leave the message type unspecified in the message +buffer (unless it is needed by the receiving process). + +*Vctx* is the RMR void context pointer that was returned by +the ``rmr_init`` function. 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 *rmr_rcv_msg()* can be passed to +this function. Retries ------- -The send operations in RMR will retry *soft* send failures -until one of three conditions occurs: - - -* The message is sent without error - -* The underlying transport reports a *hard* failure - -* The maximum number of retry loops has been attempted - - -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 -allowing the user application to completely disable retires -(set to 0), or to increase the number of retry loops. +The send operations in RMR will retry *soft* send failures +until one of three conditions occurs: + + +* The message is sent without error + +* The underlying transport reports a *hard* failure + +* The maximum number of retry loops has been attempted + + +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 +allowing the user application to completely disable retires +(set to 0), or to increase the number of retry loops. Transport Level Blocking ------------------------ -The underlying transport mechanism used to send messages is -configured in *non-blocking* mode. This means that if a -message cannot be sent immediately the transport mechanism -will **not** pause with the assumption that the inability to -send will clear quickly (within a few milliseconds). This -means that when the retry loop is completely disabled (set to -0), that the failure to accept a message for sending by the -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 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. +The underlying transport mechanism used to send messages is +configured in *non-blocking* mode. This means that if a +message cannot be sent immediately the transport mechanism +will **not** pause with the assumption that the inability to +send will clear quickly (within a few milliseconds). This +means that when the retry loop is completely disabled (set to +0), that the failure to accept a message for sending by the +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 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 ------------ -On success, a new message buffer, with an empty payload, is -returned for the application to use for the next send. The -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 -``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. - -In the event of extreme failure, a nil pointer is returned. -In this case the value of ``errno`` might be of some use, for -documentation, but there will be little that the user -application can do other than to move on. +On success, a new message buffer, with an empty payload, is +returned for the application to use for the next send. The +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 +``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. + +In the event of extreme failure, a nil pointer is returned. +In this case the value of ``errno`` might be of some use, for +documentation, but there will be little that the user +application can do other than to move on. ERRORS ------ -The following values may be passed back in the *state* field -of the returned message buffer. - - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **RMR_ERR_WHID** - - - The wormhole ID passed in was not associated with an open - wormhole, or was out of range for a valid ID. - - * - **RMR_ERR_NOWHOPEN** - - - No wormholes exist, further attempt to validate the ID are - skipped. - - * - **RMR_ERR_BADARG** - - - The message buffer pointer did not refer to a valid message. - - * - **RMR_ERR_NOHDR** - - - The header in the message buffer was not valid or corrupted. - - - -The following values may be assigned to ``errno`` on failure. - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **INVAL** - - - Parameter(s) passed to the function were not valid, or the - underlying message processing environment was unable to - interpret the message. - - * - **ENOKEY** - - - The header information in the message buffer was invalid. - - * - **ENXIO** - - - No known endpoint for the message could be found. - - * - **EMSGSIZE** - - - The underlying transport refused to accept the message - because of a size value issue (message was not attempted to - be sent). - - * - **EFAULT** - - - The message referenced by the message buffer is corrupt (nil - pointer or bad internal length). - - * - **EBADF** - - - Internal RMR error; information provided to the message - transport environment was not valid. - - * - **ENOTSUP** - - - Sending was not supported by the underlying message - transport. - - * - **EFSM** - - - The device is not in a state that can accept the message. - - * - **EAGAIN** - - - The device is not able to accept a message for sending. The - user application should attempt to resend. - - * - **EINTR** - - - The operation was interrupted by delivery of a signal before - the message was sent. - - * - **ETIMEDOUT** - - - The underlying message environment timed out during the send - process. - - * - **ETERM** - - - The underlying message environment is in a shutdown state. - - +The following values may be passed back in the *state* field +of the returned message buffer. + + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **RMR_ERR_WHID** + - + The wormhole ID passed in was not associated with an open + wormhole, or was out of range for a valid ID. + + * - **RMR_ERR_NOWHOPEN** + - + No wormholes exist, further attempt to validate the ID are + skipped. + + * - **RMR_ERR_BADARG** + - + The message buffer pointer did not refer to a valid message. + + * - **RMR_ERR_NOHDR** + - + The header in the message buffer was not valid or corrupted. + + + +The following values may be assigned to ``errno`` on failure. + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **INVAL** + - + Parameter(s) passed to the function were not valid, or the + underlying message processing environment was unable to + interpret the message. + + * - **ENOKEY** + - + The header information in the message buffer was invalid. + + * - **ENXIO** + - + No known endpoint for the message could be found. + + * - **EMSGSIZE** + - + The underlying transport refused to accept the message + because of a size value issue (message was not attempted to + be sent). + + * - **EFAULT** + - + The message referenced by the message buffer is corrupt (nil + pointer or bad internal length). + + * - **EBADF** + - + Internal RMR error; information provided to the message + transport environment was not valid. + + * - **ENOTSUP** + - + Sending was not supported by the underlying message + transport. + + * - **EFSM** + - + The device is not in a state that can accept the message. + + * - **EAGAIN** + - + The device is not able to accept a message for sending. The + user application should attempt to resend. + + * - **EINTR** + - + The operation was interrupted by delivery of a signal before + the message was sent. + + * - **ETIMEDOUT** + - + The underlying message environment timed out during the send + process. + + * - **ETERM** + - + The underlying message environment is in a shutdown state. + + EXAMPLE ------- -The following is a simple example of how the a wormhole is -created (rmr_wh_open) and then how ``rmr_wh_send_msg`` -function is used to send messages. Some error checking is -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 - int i; - rmr_mbuf_t* sbuf; // send buffer - int count = 0; - int norm_msg_size = 1500; // most msg fit in this size - - mrc = rmr_init( "43086", norm_msg_size, RMRFL_NONE ); - if( mrc == NULL ) { - fprintf( stderr, "[FAIL] unable to initialise RMR environment\\n" ); - exit( 1 ); - } - - 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 - 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 ); - } - } - +The following is a simple example of how the a wormhole is +created (rmr_wh_open) and then how ``rmr_wh_send_msg`` +function is used to send messages. Some error checking is +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 + int i; + rmr_mbuf_t* sbuf; // send buffer + int count = 0; + int norm_msg_size = 1500; // most msg fit in this size + + mrc = rmr_init( "43086", norm_msg_size, RMRFL_NONE ); + if( mrc == NULL ) { + fprintf( stderr, "[FAIL] unable to initialise RMR environment\\n" ); + exit( 1 ); + } + + 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 + 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 ); + } + } + SEE ALSO -------- -rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), -rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3), -rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3), -rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3), -rmr_set_stimeout(3), rmr_wh_open(3), rmr_wh_close(3), -rmr_wh_state(3) +rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), +rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3), +rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3), +rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3), +rmr_set_stimeout(3), rmr_wh_open(3), rmr_wh_close(3), +rmr_wh_state(3) diff --git a/docs/rmr_wh_state.3.rst b/docs/rmr_wh_state.3.rst index 6054932..805ae78 100644 --- a/docs/rmr_wh_state.3.rst +++ b/docs/rmr_wh_state.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_wh_state -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_wh_state +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,70 +19,70 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_wh_state +rmr_wh_state SYNOPSIS -------- - -:: - - #include - - int rmr_wh_state( void* vctx, rmr_whid_t whid ) - + +:: + + #include + + int rmr_wh_state( void* vctx, rmr_whid_t whid ) + DESCRIPTION ----------- -The ``rmr_wh_state`` function will return the current state -of the connection associated with the given wormhole (whid). -The return value indicates whether the connection is open -(RMR_OK), or closed (any other return value). - -When using some transport mechanisms (e.g. NNG), it may not -be possible for RMR to know the actual state and the -connection may always be reported as "open." +The ``rmr_wh_state`` function will return the current state +of the connection associated with the given wormhole (whid). +The return value indicates whether the connection is open +(RMR_OK), or closed (any other return value). + +When using some transport mechanisms (e.g. NNG), it may not +be possible for RMR to know the actual state and the +connection may always be reported as "open." RETURN ------ -The following values are potential return values. - - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **RMR_OK** - - - The wormhole ID is valid and the connection is "open." - - * - **RMR_ERR_WHID** - - - THe wormhole ID passed into the function was not valid. - - * - **RMR_ERR_NOENDPT** - - - The wormhole is not open (not connected). - - * - **RMR_ERR_BADARG** - - - The context passed to the function was nil or invalid. - - * - **RMR_ERR_NOWHOPEN** - - - Wormholes have not been initialised (no wormhole open call - has been made). - - +The following values are potential return values. + + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **RMR_OK** + - + The wormhole ID is valid and the connection is "open." + + * - **RMR_ERR_WHID** + - + THe wormhole ID passed into the function was not valid. + + * - **RMR_ERR_NOENDPT** + - + The wormhole is not open (not connected). + + * - **RMR_ERR_BADARG** + - + The context passed to the function was nil or invalid. + + * - **RMR_ERR_NOWHOPEN** + - + Wormholes have not been initialised (no wormhole open call + has been made). + + SEE ALSO -------- -rmr_wh_open(3), rmr_wh_send_msg(3), rmr_wh_close(3) +rmr_wh_open(3), rmr_wh_send_msg(3), rmr_wh_close(3) diff --git a/docs/rt_tables.rst b/docs/rt_tables.rst index 807c56e..c4f869e 100644 --- a/docs/rt_tables.rst +++ b/docs/rt_tables.rst @@ -1,646 +1,646 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Route Table Guide -============================================================================================ --------------------------------------------------------------------------------------------- -RIC Message Router -- RMR --------------------------------------------------------------------------------------------- +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Route Table Guide +============================================================================================ +-------------------------------------------------------------------------------------------- +RIC Message Router -- RMR +-------------------------------------------------------------------------------------------- Overview ======== -Messages sent via the RIC Message Router (RMR) are routed to -an endpoint (another application) based on a combination of -the *message type* (MT) and *subscription ID* (SID) supplied -in the message. RMR determines the endpoint by matching the -MT and SID combination to an entry in a route table which has -been supplied dynamically by a *Route Manager* service, or as -a static table loaded during RMR initialisation. It is also -possible to route messages directly to an endpoint which is -the *managed entity* "owner," using the *managed entity ID* -(MEID). - -For most xAPP developers the format of the RMR route table is -not important beyond understanding how to create a static -table for local testing. For developers of a *Route Manager* -service, the need is certainly a requirement. This document -describes the overall syntax of a route table and the -interface between the *Route Manager* service and RMR. +Messages sent via the RIC Message Router (RMR) are routed to +an endpoint (another application) based on a combination of +the *message type* (MT) and *subscription ID* (SID) supplied +in the message. RMR determines the endpoint by matching the +MT and SID combination to an entry in a route table which has +been supplied dynamically by a *Route Manager* service, or as +a static table loaded during RMR initialisation. It is also +possible to route messages directly to an endpoint which is +the *managed entity* "owner," using the *managed entity ID* +(MEID). + +For most xAPP developers the format of the RMR route table is +not important beyond understanding how to create a static +table for local testing. For developers of a *Route Manager* +service, the need is certainly a requirement. This document +describes the overall syntax of a route table and the +interface between the *Route Manager* service and RMR. Contents of a Route Table ========================= -The table consists of a start record, one or more entry -records, and an end record. Each entry record defines one -message type, with an optional sender application, and the -endpoint(s) which accept the indicated message type. All -table records contain fields separated with vertical bars -(|), and allow for trailing comments with the standard shell -comment symbol (hash, #) provided that the start of the -comment is separated from the last token on the record by one -or more spaces. Leading and trailing white space in each -field is ignored. Figure 1 illustrates a very basic route -table with two message types, 1000 and 2000, and two -subscription IDs for message type 1000. - - -:: - +The table consists of a start record, one or more entry +records, and an end record. Each entry record defines one +message type, with an optional sender application, and the +endpoint(s) which accept the indicated message type. All +table records contain fields separated with vertical bars +(|), and allow for trailing comments with the standard shell +comment symbol (hash, #) provided that the start of the +comment is separated from the last token on the record by one +or more spaces. Leading and trailing white space in each +field is ignored. Figure 1 illustrates a very basic route +table with two message types, 1000 and 2000, and two +subscription IDs for message type 1000. + + +:: + newrt | start | rt-0928 rte | 2000 | logger:30311 mse | 1000 | 10 | forwarder:43086 mse | 1000 | 21 | app0:43086,app1:43086 newrt | end | 3 - -Figure 1: A basic route table. + +Figure 1: A basic route table. Entry record syntax ------------------- -Two types of table entries are supported for compatibility -with the original RMR implementation, but only the *mse* -entry type is needed and that should be the entry used when -creating new tables. The following shows the syntax for both -entry types: - - -:: - +Two types of table entries are supported for compatibility +with the original RMR implementation, but only the *mse* +entry type is needed and that should be the entry used when +creating new tables. The following shows the syntax for both +entry types: + + +:: + rte | [,] | [;;...] mse | [,] | | [;;...] - - -Where: - - - .. list-table:: - :widths: 25,70 - :header-rows: 0 - :class: borderless - - * - **mse, rte** - - - is the table entry type - - * - **** - - - is the integer message type - - * - **** - - - is the endpoint description of the message sender; only that - sender will read the entry from the table, so a single table - may be used for all senders when a common message type is - delivered to varying endpoints based on senders. If the - sender endpoint is omitted from the entry, then the entry - will be used by all applications. - - * - **** - - - is the subscription id (integer) for subscription-based - messages, or -1 if the message type is not - subscription-based. An *mse* entry with a sub-id of -1 is the - **same** as an *rte* entry with the same message type. - - * - **** - - - is one or more, comma separated, endpoint descriptions. - - - -When an application sends a message with the indicated type, -the message will be sent to one endpoint in the group in a -round-robin ordering. If multiple endpoint groups are given, -then the message is sent to a member selected from each -group; 3 groups, then three messages will be sent. The first -group is required. + + +Where: + + + .. list-table:: + :widths: 25,70 + :header-rows: 0 + :class: borderless + + * - **mse, rte** + - + is the table entry type + + * - **** + - + is the integer message type + + * - **** + - + is the endpoint description of the message sender; only that + sender will read the entry from the table, so a single table + may be used for all senders when a common message type is + delivered to varying endpoints based on senders. If the + sender endpoint is omitted from the entry, then the entry + will be used by all applications. + + * - **** + - + is the subscription id (integer) for subscription-based + messages, or -1 if the message type is not + subscription-based. An *mse* entry with a sub-id of -1 is the + **same** as an *rte* entry with the same message type. + + * - **** + - + is one or more, comma separated, endpoint descriptions. + + + +When an application sends a message with the indicated type, +the message will be sent to one endpoint in the group in a +round-robin ordering. If multiple endpoint groups are given, +then the message is sent to a member selected from each +group; 3 groups, then three messages will be sent. The first +group is required. Line separation --------------- -Table entries **must** end with a record termination sequence -which may be one of the following three sequences: - - -* a single newline (\\n) -* a DOS style CRLF pair (\\r\\n) -* a single carriage return (\\r) - - -Care must be taken when manually editing a static table; some -editors do **not** add a final record termination sequence to -the last line of a file. RMR expects the final record to have -a termination sequence to ensure that the record was not -truncated (especially important when receiving dynamic -tables). +Table entries **must** end with a record termination sequence +which may be one of the following three sequences: + + +* a single newline (\\n) +* a DOS style CRLF pair (\\r\\n) +* a single carriage return (\\r) + + +Care must be taken when manually editing a static table; some +editors do **not** add a final record termination sequence to +the last line of a file. RMR expects the final record to have +a termination sequence to ensure that the record was not +truncated (especially important when receiving dynamic +tables). Table framing ------------- -The route table parser within RMR assumes that route table -entries are sent via RMR messages as a stream. To ensure -synchronisation and prevent malformed tables because of -broken sessions or lost packets, each table must begin and -end with an *newrt* record. Each *newrt* record has one of -two possible syntax layouts as described below. - - -:: - +The route table parser within RMR assumes that route table +entries are sent via RMR messages as a stream. To ensure +synchronisation and prevent malformed tables because of +broken sessions or lost packets, each table must begin and +end with an *newrt* record. Each *newrt* record has one of +two possible syntax layouts as described below. + + +:: + newrt | begin [| table-id-string] newrt | end [| record-count] - -Figure 2: Illustration of the newrt records in the table. - -The *table-id-string* is an optional string which is used by -RMR when sending an acknowledgement back to the *Route -Manager* service (see the *Route Manager Interface* section -for more details). If a *record-count* is given as the final -field on the *end* record, RMR will verify that the number of -*mse* and *rte* entries in the table matches the count; if -there is a mismatch in values the table is not used. + +Figure 2: Illustration of the newrt records in the table. + +The *table-id-string* is an optional string which is used by +RMR when sending an acknowledgement back to the *Route +Manager* service (see the *Route Manager Interface* section +for more details). If a *record-count* is given as the final +field on the *end* record, RMR will verify that the number of +*mse* and *rte* entries in the table matches the count; if +there is a mismatch in values the table is not used. Comments, spaces, and blank lines --------------------------------- -Comments may be placed to the right of any table entry line -using the standard shell comment symbol (#). The start of a -comment must be separated from any previous record content by -at least one space or tab. Complete lines are treated as -comments when the first non-whitespace character of a line is -a comment symbol. Blank lines are also ignored. - -Fields on table records are separated using the vertical bar -(|) character. Any white space (tabs or spaces) which appear -immediately before or after a separator are ignored. +Comments may be placed to the right of any table entry line +using the standard shell comment symbol (#). The start of a +comment must be separated from any previous record content by +at least one space or tab. Complete lines are treated as +comments when the first non-whitespace character of a line is +a comment symbol. Blank lines are also ignored. + +Fields on table records are separated using the vertical bar +(|) character. Any white space (tabs or spaces) which appear +immediately before or after a separator are ignored. Endpoint Description -------------------- -The endpoint description is either the hostname or IP address -followed by a port number; the two are separated by a single -colon. The illustration below assumes that host names (e.g. -forwarder and app1) are defined; they also make the tables -easier to read. The port number given is the port number that -the user application provides to RMR when the RMR -initialisation function is invoked (and thus is the port that -RMR is listening on). +The endpoint description is either the hostname or IP address +followed by a port number; the two are separated by a single +colon. The illustration below assumes that host names (e.g. +forwarder and app1) are defined; they also make the tables +easier to read. The port number given is the port number that +the user application provides to RMR when the RMR +initialisation function is invoked (and thus is the port that +RMR is listening on). Table Mechanics =============== -Creating a table from the two entry types is fairly simple, -however there are some subtleties which should be pointed out -to avoid unexpected behaviour. For this discussion the -following complete table will be used. - -.. list-table:: - :widths: 75,10 - :header-rows: 0 - :class: borderless - - - * - - - :: - - newrt | start | rt-0928 - rte | 2000 | logger:30311 - mse | 1000 | 10 | forwarder:43086 - mse | 1000,forwarder:43086 | 10 | app2:43086 - mse | 1000 | -1 | app0:43086,app1:43086; logger:20311 - newrt | end | 4 - - - - - :: - - (1) - (2) - (3) - (4) - (5) - (6) - - -Figure 3: A complete RMR routing table (line numbers to the -right for reference). +Creating a table from the two entry types is fairly simple, +however there are some subtleties which should be pointed out +to avoid unexpected behaviour. For this discussion the +following complete table will be used. + +.. list-table:: + :widths: 75,10 + :header-rows: 0 + :class: borderless + + + * - + + :: + + newrt | start | rt-0928 + rte | 2000 | logger:30311 + mse | 1000 | 10 | forwarder:43086 + mse | 1000,forwarder:43086 | 10 | app2:43086 + mse | 1000 | -1 | app0:43086,app1:43086; logger:20311 + newrt | end | 4 + + - + + :: + + (1) + (2) + (3) + (4) + (5) + (6) + + +Figure 3: A complete RMR routing table (line numbers to the +right for reference). Table Entry Ordering -------------------- -Whether a table is read from a file on disk, or is received -from a *Route Manager* service, RMR parses the records to -build an internal route table keeping only the relevant -information. Entries are read in the order they appear (from -the file or in messages received), and RMR will use only one -entry for each MT/SID pair. - -For most tables, the ordering of entries is not important, -but when there are entries which duplicate the MT/SID pair -ordering becomes significant. RMR will use the **last** valid -entry for a MT/SID pair that it encounters. An entry is -considered valid if there is no sender identified with the -message type (line 3), and when the sender (host and port) -match the the applications' location and the port provided to -RMR for listening. - -Using the table in figure 3 as an example, there are two -entries which match the MT/SID pair of 1000/10. When this -table is parsed on any host, RMR will recognise and add the -first entry (line 3) to the internal representation; this -entry is valid for all applications. The second 1000/10 entry -(line 4) is valid when the table is parsed on the *forwarder* -host, and only by the application which is listening on port -43086. For this application the entry will override the more -generic entry for the MT/SID combination. - -As a rule, the ordering of entries for a given MT/SID pair -should be from most generic to most specific. +Whether a table is read from a file on disk, or is received +from a *Route Manager* service, RMR parses the records to +build an internal route table keeping only the relevant +information. Entries are read in the order they appear (from +the file or in messages received), and RMR will use only one +entry for each MT/SID pair. + +For most tables, the ordering of entries is not important, +but when there are entries which duplicate the MT/SID pair +ordering becomes significant. RMR will use the **last** valid +entry for a MT/SID pair that it encounters. An entry is +considered valid if there is no sender identified with the +message type (line 3), and when the sender (host and port) +match the the applications' location and the port provided to +RMR for listening. + +Using the table in figure 3 as an example, there are two +entries which match the MT/SID pair of 1000/10. When this +table is parsed on any host, RMR will recognise and add the +first entry (line 3) to the internal representation; this +entry is valid for all applications. The second 1000/10 entry +(line 4) is valid when the table is parsed on the *forwarder* +host, and only by the application which is listening on port +43086. For this application the entry will override the more +generic entry for the MT/SID combination. + +As a rule, the ordering of entries for a given MT/SID pair +should be from most generic to most specific. Route Manager Communications ============================ -During initialisation RMR will use the value of the -``RMR_RTG_SVC`` environment variable to connect to the *Route -Manager* service in order to request a route table. The -connection between RMR and the *Route Manager* is also an RMR -session and thus RMR messages will be used to exchange -requests and responses. +During initialisation RMR will use the value of the +``RMR_RTG_SVC`` environment variable to connect to the *Route +Manager* service in order to request a route table. The +connection between RMR and the *Route Manager* is also an RMR +session and thus RMR messages will be used to exchange +requests and responses. Table Request ------------- -During initialisation, RMR establishes a wormhole connection -to the *Route Manager* and sends a message type of 21 to -request a new table. RMR will continue to send table requests -until a table is received and accepted; in other words it is -fine for the *Route Manager* to ignore the requests if it is -not ready to respond. +During initialisation, RMR establishes a wormhole connection +to the *Route Manager* and sends a message type of 21 to +request a new table. RMR will continue to send table requests +until a table is received and accepted; in other words it is +fine for the *Route Manager* to ignore the requests if it is +not ready to respond. Sending Tables To RMR --------------------- -Table entry data is expected to arrive via RMR message with a -message type of 20. The message may contain one or more -entries provided that the entries are newline separated. -Current versions of RMR support very large messages, however -to ensure compatibility with an xAPP built using an older -version of RMR (pre 3.8), messages should be limited to 4 -KiB. +Table entry data is expected to arrive via RMR message with a +message type of 20. The message may contain one or more +entries provided that the entries are newline separated. +Current versions of RMR support very large messages, however +to ensure compatibility with an xAPP built using an older +version of RMR (pre 3.8), messages should be limited to 4 +KiB. Table Acceptance and Acknowledgement ------------------------------------ -When RMR receives the table end entry (newrt|end), it will -send a state message back to the *Route Manager* to indicate -the state of the received table. The message type is 22 and -the payload will contain UTF-8 tokens which indicate the -state. The second token will be the *table ID* supplied on -the start record, or the string "." When the -state is an error state, RMR might add a final set of tokens -which contain the reason for the failure. - -Upon receipt of a status message which indicates an "OK" -response, the *Route Manager* can assume that the table has -been installed and is in use. Any other response indicates -that RMR did not use the table and has dropped it; the -previous table is still in use. +When RMR receives the table end entry (newrt|end), it will +send a state message back to the *Route Manager* to indicate +the state of the received table. The message type is 22 and +the payload will contain UTF-8 tokens which indicate the +state. The second token will be the *table ID* supplied on +the start record, or the string "." When the +state is an error state, RMR might add a final set of tokens +which contain the reason for the failure. + +Upon receipt of a status message which indicates an "OK" +response, the *Route Manager* can assume that the table has +been installed and is in use. Any other response indicates +that RMR did not use the table and has dropped it; the +previous table is still in use. Using A Static Route Table -------------------------- -A static route table can be provided to assist with testing, -or to provide a bootstrap set of route information until a -dynamic table is received from a routing manager. The -environment variable ``RMR_SEED_RT`` is checked during RMR -initialisation and if set is expected to reference a file -containing a route table. This table will be loaded and used -until overlaid by a table sent by the *Route Manager*. - -For testing, the static table will be reloaded periodically -if the ``RMR_RTG_SVC`` environment variable is set to -1. -When this testing feature is enabled RMR will not listen for -*Route Manager* connections, nor will it attempt to request a -dynamic table. +A static route table can be provided to assist with testing, +or to provide a bootstrap set of route information until a +dynamic table is received from a routing manager. The +environment variable ``RMR_SEED_RT`` is checked during RMR +initialisation and if set is expected to reference a file +containing a route table. This table will be loaded and used +until overlaid by a table sent by the *Route Manager*. + +For testing, the static table will be reloaded periodically +if the ``RMR_RTG_SVC`` environment variable is set to -1. +When this testing feature is enabled RMR will not listen for +*Route Manager* connections, nor will it attempt to request a +dynamic table. Routing Using MEID ================== -Starting with version 1.13.0, RMR provides the ability to -select the endpoint for a message based on the MEID (managed -entity ID) in the message, rather than selecting the endpoint -from the round-robin list for the matching route table entry. -When the MEID is used, the message is sent to the endpoint -which *owns,* or is responsible for the managed entity. -Should the *owner* change messages will be routed to the new -owner when the route table is updated. To make use of MEID -routing, there must be one or more route table entries which -list the special endpoint name ``%meid`` instead of providing -a round robin list. As an example, consider the following -route table entry: - - -:: - - mse| 1000,forwarder:43086 | 10 | %meid - -Figure 4: Sample route entry with the meid flag. - -The final field of the entry doesn't specify a round-robin -group which means that when an application attempts to send a -message with type 1000, and the subscription ID of 10, the -MEID in the message will be used to select the endpoint. +Starting with version 1.13.0, RMR provides the ability to +select the endpoint for a message based on the MEID (managed +entity ID) in the message, rather than selecting the endpoint +from the round-robin list for the matching route table entry. +When the MEID is used, the message is sent to the endpoint +which *owns,* or is responsible for the managed entity. +Should the *owner* change messages will be routed to the new +owner when the route table is updated. To make use of MEID +routing, there must be one or more route table entries which +list the special endpoint name ``%meid`` instead of providing +a round robin list. As an example, consider the following +route table entry: + + +:: + + mse| 1000,forwarder:43086 | 10 | %meid + +Figure 4: Sample route entry with the meid flag. + +The final field of the entry doesn't specify a round-robin +group which means that when an application attempts to send a +message with type 1000, and the subscription ID of 10, the +MEID in the message will be used to select the endpoint. MEID endpoint selection ----------------------- -To select an endpoint for the message based on the MEID in a -message, RMR must know which endpoint owns the MEID. This -information, known as an MEID map, is provided by the *Route -Manager* over the same communication path as the route table -is supplied. The following is the syntax for an MEID map. - - -:: - - meid_map | start | - mme_ar | | [...] - mme_del | [...] - meid_map | end | [| ] - -Figure 5: Meid map table. - -The mme_ar records are add/update records and allow for the -list of MEIDs to be associated with (owned by) the indicated -endpoint. The is the hostname:port, or IP -address and port, of the application which owns the MEID and -thus should receive any messages which are routed based on a -route table entry with %meid as the round-robin group. The -mme_del records allow for MEIDs to be deleted from RMR's -view. Finally, the is the number of add/replace and -delete records which were sent; if RMR does not match the - value to the number of records, then it will not add -the data to the table. Updates only need to list the -ownership changes that are necessary; in other words, the -*Route Manager* does not need to supply all of the MEID -relationships with each update. - -The optional field on the end record should be the -MD5 hash of all of the records between the start and end -records. This allows for a precise verification that the -transmitted data was correctly received. - -If a static seed file is being used for the route table, a -second section can be given which supplies the MEID map. The -following is a small example of a seed file: - - -:: - - newrt|start | id-64306 - mse|0|-1| %meid - mse|1|-1|172.19.0.2:4560 - mse|2|-1|172.19.0.2:4560 - mse|3|-1|172.19.0.2:4560 - mse|4|-1|172.19.0.2:4560 - mse|5|-1|172.19.0.2:4560 - newrt|end - - meid_map | start | id-028919 - mme_ar| 172.19.0.2:4560 | meid000 meid001 meid002 meid003 meid004 meid005 - mme_ar| 172.19.0.42:4560 | meid100 meid101 meid102 meid103 - mme_del | meid1000 - meid_map | end | 1 - -Figure 6: Illustration of both a route table and meid map in -the same file. - -The tables above will route all messages with a message type -of 0 based on the MEID. There are 10 meids which are owned by -two different endpoints. The table also deletes the MEID -meid1000 from RMR's view. +To select an endpoint for the message based on the MEID in a +message, RMR must know which endpoint owns the MEID. This +information, known as an MEID map, is provided by the *Route +Manager* over the same communication path as the route table +is supplied. The following is the syntax for an MEID map. + + +:: + + meid_map | start | + mme_ar | | [...] + mme_del | [...] + meid_map | end | [| ] + +Figure 5: Meid map table. + +The mme_ar records are add/update records and allow for the +list of MEIDs to be associated with (owned by) the indicated +endpoint. The is the hostname:port, or IP +address and port, of the application which owns the MEID and +thus should receive any messages which are routed based on a +route table entry with %meid as the round-robin group. The +mme_del records allow for MEIDs to be deleted from RMR's +view. Finally, the is the number of add/replace and +delete records which were sent; if RMR does not match the + value to the number of records, then it will not add +the data to the table. Updates only need to list the +ownership changes that are necessary; in other words, the +*Route Manager* does not need to supply all of the MEID +relationships with each update. + +The optional field on the end record should be the +MD5 hash of all of the records between the start and end +records. This allows for a precise verification that the +transmitted data was correctly received. + +If a static seed file is being used for the route table, a +second section can be given which supplies the MEID map. The +following is a small example of a seed file: + + +:: + + newrt|start | id-64306 + mse|0|-1| %meid + mse|1|-1|172.19.0.2:4560 + mse|2|-1|172.19.0.2:4560 + mse|3|-1|172.19.0.2:4560 + mse|4|-1|172.19.0.2:4560 + mse|5|-1|172.19.0.2:4560 + newrt|end + + meid_map | start | id-028919 + mme_ar| 172.19.0.2:4560 | meid000 meid001 meid002 meid003 meid004 meid005 + mme_ar| 172.19.0.42:4560 | meid100 meid101 meid102 meid103 + mme_del | meid1000 + meid_map | end | 1 + +Figure 6: Illustration of both a route table and meid map in +the same file. + +The tables above will route all messages with a message type +of 0 based on the MEID. There are 10 meids which are owned by +two different endpoints. The table also deletes the MEID +meid1000 from RMR's view. Reserved Message Types ====================== -RMR is currently reserving message types in the range of 0 -through 99 (inclusive) for its own use. Please do not use -these types in any production or test environment as the -results may be undesired. - +RMR is currently reserving message types in the range of 0 +through 99 (inclusive) for its own use. Please do not use +these types in any production or test environment as the +results may be undesired. + Appendix A -- Glossary ====================== -Many terms in networking can be interpreted with multiple -meanings, and several terms used in various RMR documentation -are RMR specific. The following definitions are the meanings -of terms used within RMR documentation and should help the -reader to understand the intent of meaning. - - .. list-table:: - :widths: 25,70 - :header-rows: 0 - :class: borderless - - * - **application** - - - A programme which uses RMR to send and/or receive messages - to/from another RMR based application. - - * - **Critical error** - - - An error that RMR has encountered which will prevent further - successful processing by RMR. Critical errors usually - indicate that the application should abort. - - * - **Endpoint** - - - An RMR based application that is defined as being capable of - receiving one or more types of messages (as defined by a - *routing key.*) - - * - **Environment variable** - - - A key/value pair which is set externally to the application, - but which is available to the application (and referenced - libraries) through the ``getenv`` system call. Environment - variables are the main method of communicating information - such as port numbers to RMR. - - * - **Error** - - - An abnormal condition that RMR has encountered, but will not - affect the overall processing by RMR, but may impact certain - aspects such as the ability to communicate with a specific - endpoint. Errors generally indicate that something, usually - external to RMR, must be addressed. - - * - **Host name** - - - The name of the host as returned by the ``gethostbyname`` - system call. In a containerised environment this might be the - container or service name depending on how the container is - started. From RMR's point of view, a host name can be used to - resolve an *endpoint* definition in a *route* table.) - - * - **IP** - - - Internet protocol. A low level transmission protocol which - governs the transmission of datagrams across network - boundaries. - - * - **Listen socket** - - - A *TCP* socket used to await incoming connection requests. - Listen sockets are defined by an interface and port number - combination where the port number is unique for the - interface. - - * - **Message** - - - A series of bytes transmitted from the application to another - RMR based application. A message is comprised of RMR specific - data (a header), and application data (a payload). - - * - **Message buffer** - - - A data structure used to describe a message which is to be - sent or has been received. The message buffer includes the - payload length, message type, message source, and other - information. - - * - **Message type** - - - A signed integer (0-32000) which identifies the type of - message being transmitted, and is one of the two components - of a *routing key.* See *Subscription ID.* - - * - **Payload** - - - The portion of a message which holds the user data to be - transmitted to the remote *endpoint.* The payload contents - are completely application defined. - - * - **RMR context** - - - A set of information which defines the current state of the - underlying transport connections that RMR is managing. The - application will be give a context reference (pointer) that - is supplied to most RMR functions as the first parameter. - - * - **Round robin** - - - The method of selecting an *endpoint* from a list such that - all *endpoints* are selected before starting at the head of - the list. - - * - **Route table** - - - A series of "rules" which define the possible *endpoints* for - each *routing key.* - - * - **Route table manager** - - - An application responsible for building a *route table* and - then distributing it to all applicable RMR based - applications. - - * - **Routing** - - - The process of selecting an *endpoint* which will be the - recipient of a message. - - * - **Routing key** - - - A combination of *message type* and *subscription ID* which - RMR uses to select the destination *endpoint* when sending a - message. - - * - **Source** - - - The sender of a message. - - * - **Subscription ID** - - - A signed integer value (0-32000) which identifies the - subscription characteristic of a message. It is used in - conjunction with the *message type* to determine the *routing - key.* - - * - **Target** - - - The *endpoint* selected to receive a message. - - * - **TCP** - - - Transmission Control Protocol. A connection based internet - protocol which provides for lossless packet transportation, - usually over IP. - - * - **Thread** - - - Also called a *process thread, or pthread.* This is a - lightweight process which executes in concurrently with the - application and shares the same address space. RMR uses - threads to manage asynchronous functions such as route table - updates. - - * - **Trace information** - - - An optional portion of the message buffer that the - application may populate with data that allows for tracing - the progress of the transaction or application activity - across components. RMR makes no use of this data. - - * - **Transaction ID** - - - A fixed number of bytes in the *message* buffer) which the - application may populate with information related to the - transaction. RMR makes use of the transaction ID for matching - response messages with the &c function is used to send a - message. - - * - **Transient failure** - - - An error state that is believed to be short lived and that - the operation, if retried by the application, might be - successful. C programmers will recognise this as - ``EAGAIN.`` - - * - **Warning** - - - A warning occurs when RMR has encountered something that it - believes isn't correct, but has a defined work round. - - * - **Wormhole** - - - A direct connection managed by RMR between the user - application and a remote, RMR based, application. - - - +Many terms in networking can be interpreted with multiple +meanings, and several terms used in various RMR documentation +are RMR specific. The following definitions are the meanings +of terms used within RMR documentation and should help the +reader to understand the intent of meaning. + + .. list-table:: + :widths: 25,70 + :header-rows: 0 + :class: borderless + + * - **application** + - + A programme which uses RMR to send and/or receive messages + to/from another RMR based application. + + * - **Critical error** + - + An error that RMR has encountered which will prevent further + successful processing by RMR. Critical errors usually + indicate that the application should abort. + + * - **Endpoint** + - + An RMR based application that is defined as being capable of + receiving one or more types of messages (as defined by a + *routing key.*) + + * - **Environment variable** + - + A key/value pair which is set externally to the application, + but which is available to the application (and referenced + libraries) through the ``getenv`` system call. Environment + variables are the main method of communicating information + such as port numbers to RMR. + + * - **Error** + - + An abnormal condition that RMR has encountered, but will not + affect the overall processing by RMR, but may impact certain + aspects such as the ability to communicate with a specific + endpoint. Errors generally indicate that something, usually + external to RMR, must be addressed. + + * - **Host name** + - + The name of the host as returned by the ``gethostbyname`` + system call. In a containerised environment this might be the + container or service name depending on how the container is + started. From RMR's point of view, a host name can be used to + resolve an *endpoint* definition in a *route* table.) + + * - **IP** + - + Internet protocol. A low level transmission protocol which + governs the transmission of datagrams across network + boundaries. + + * - **Listen socket** + - + A *TCP* socket used to await incoming connection requests. + Listen sockets are defined by an interface and port number + combination where the port number is unique for the + interface. + + * - **Message** + - + A series of bytes transmitted from the application to another + RMR based application. A message is comprised of RMR specific + data (a header), and application data (a payload). + + * - **Message buffer** + - + A data structure used to describe a message which is to be + sent or has been received. The message buffer includes the + payload length, message type, message source, and other + information. + + * - **Message type** + - + A signed integer (0-32000) which identifies the type of + message being transmitted, and is one of the two components + of a *routing key.* See *Subscription ID.* + + * - **Payload** + - + The portion of a message which holds the user data to be + transmitted to the remote *endpoint.* The payload contents + are completely application defined. + + * - **RMR context** + - + A set of information which defines the current state of the + underlying transport connections that RMR is managing. The + application will be give a context reference (pointer) that + is supplied to most RMR functions as the first parameter. + + * - **Round robin** + - + The method of selecting an *endpoint* from a list such that + all *endpoints* are selected before starting at the head of + the list. + + * - **Route table** + - + A series of "rules" which define the possible *endpoints* for + each *routing key.* + + * - **Route table manager** + - + An application responsible for building a *route table* and + then distributing it to all applicable RMR based + applications. + + * - **Routing** + - + The process of selecting an *endpoint* which will be the + recipient of a message. + + * - **Routing key** + - + A combination of *message type* and *subscription ID* which + RMR uses to select the destination *endpoint* when sending a + message. + + * - **Source** + - + The sender of a message. + + * - **Subscription ID** + - + A signed integer value (0-32000) which identifies the + subscription characteristic of a message. It is used in + conjunction with the *message type* to determine the *routing + key.* + + * - **Target** + - + The *endpoint* selected to receive a message. + + * - **TCP** + - + Transmission Control Protocol. A connection based internet + protocol which provides for lossless packet transportation, + usually over IP. + + * - **Thread** + - + Also called a *process thread, or pthread.* This is a + lightweight process which executes in concurrently with the + application and shares the same address space. RMR uses + threads to manage asynchronous functions such as route table + updates. + + * - **Trace information** + - + An optional portion of the message buffer that the + application may populate with data that allows for tracing + the progress of the transaction or application activity + across components. RMR makes no use of this data. + + * - **Transaction ID** + - + A fixed number of bytes in the *message* buffer) which the + application may populate with information related to the + transaction. RMR makes use of the transaction ID for matching + response messages with the &c function is used to send a + message. + + * - **Transient failure** + - + An error state that is believed to be short lived and that + the operation, if retried by the application, might be + successful. C programmers will recognise this as + ``EAGAIN.`` + + * - **Warning** + - + A warning occurs when RMR has encountered something that it + believes isn't correct, but has a defined work round. + + * - **Wormhole** + - + A direct connection managed by RMR between the user + application and a remote, RMR based, application. + + + diff --git a/docs/user-guide.rst b/docs/user-guide.rst index a825c50..e12e009 100644 --- a/docs/user-guide.rst +++ b/docs/user-guide.rst @@ -1,892 +1,892 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -User's Guide -============================================================================================ --------------------------------------------------------------------------------------------- -RIC Message Router -- RMR --------------------------------------------------------------------------------------------- +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +User's Guide +============================================================================================ +-------------------------------------------------------------------------------------------- +RIC Message Router -- RMR +-------------------------------------------------------------------------------------------- Overview ======== -The RIC Message Router (RMR) is a library for peer-to-peer -communication. Applications use the library to send and -receive messages where the message routing and endpoint -selection is based on the message type rather than DNS host -name-IP port combinations. The library provides the following -major features: - - -* Routing and endpoint selection is based on *message type.* - -* Application is insulated from the underlying transport - mechanism and/or protocols. - -* Message distribution (round robin or fanout) is selectable - by message type. - -* Route management updates are received and processed - asynchronously and without overt application involvement. - - +The RIC Message Router (RMR) is a library for peer-to-peer +communication. Applications use the library to send and +receive messages where the message routing and endpoint +selection is based on the message type rather than DNS host +name-IP port combinations. The library provides the following +major features: + + +* Routing and endpoint selection is based on *message type.* + +* Application is insulated from the underlying transport + mechanism and/or protocols. + +* Message distribution (round robin or fanout) is selectable + by message type. + +* Route management updates are received and processed + asynchronously and without overt application involvement. + + Purpose ------- -RMR's main purpose is to provide an application with the -ability to send and receive messages to/from other peer -applications with minimal effort on the application's part. -To achieve this, RMR manages all endpoint information, -connections, and routing information necessary to establish -and maintain communication. From the application's point of -view, all that is required to send a message is to allocate -(via RMR) a message buffer, add the payload data, and set the -message type. To receive a message, the application needs -only to invoke the receive function; when a message arrives a -message buffer will be returned as the function result. +RMR's main purpose is to provide an application with the +ability to send and receive messages to/from other peer +applications with minimal effort on the application's part. +To achieve this, RMR manages all endpoint information, +connections, and routing information necessary to establish +and maintain communication. From the application's point of +view, all that is required to send a message is to allocate +(via RMR) a message buffer, add the payload data, and set the +message type. To receive a message, the application needs +only to invoke the receive function; when a message arrives a +message buffer will be returned as the function result. Message Routing --------------- -Applications are required to place a message type into a -message before sending, and may optionally add a subscription -ID when appropriate. The combination of message type, and -subscription ID are refered to as the *message key,* and is -used to match an entry in a routing table which provides the -possible endpoints expecting to receive messages with the -matching key. +Applications are required to place a message type into a +message before sending, and may optionally add a subscription +ID when appropriate. The combination of message type, and +subscription ID are refered to as the *message key,* and is +used to match an entry in a routing table which provides the +possible endpoints expecting to receive messages with the +matching key. Round Robin Delivery -------------------- -An endpoint from RMR's perspective is an application to which -RMR may establish a connection, and expect to send messages -with one or more defined message keys. Each entry in the -route table consists of one or more endpoint groups, called -round robin groups. When a message matches a specific entry, -the entry's groups are used to select the destination of the -message. A message is sent once to each group, with messages -being *balanced* across the endpoints of a group via round -robin selection. Care should be taken when defining multiple -groups for a message type as there is extra overhead required -and thus the overall message latency is somewhat increased. +An endpoint from RMR's perspective is an application to which +RMR may establish a connection, and expect to send messages +with one or more defined message keys. Each entry in the +route table consists of one or more endpoint groups, called +round robin groups. When a message matches a specific entry, +the entry's groups are used to select the destination of the +message. A message is sent once to each group, with messages +being *balanced* across the endpoints of a group via round +robin selection. Care should be taken when defining multiple +groups for a message type as there is extra overhead required +and thus the overall message latency is somewhat increased. Routing Table Updates --------------------- -Route table information is made available to RMR a static -file (loaded once), or by updates sent from a separate route -manager application. If a static table is provided, it is -loaded during RMR initialization and will remain in use until -an external process connects and delivers a route table -update (often referred to as a dynamic update). Dynamic -updates are listened for in a separate process thread and -applied automatically; the application does not need to allow -for, or trigger, updates. +Route table information is made available to RMR a static +file (loaded once), or by updates sent from a separate route +manager application. If a static table is provided, it is +loaded during RMR initialization and will remain in use until +an external process connects and delivers a route table +update (often referred to as a dynamic update). Dynamic +updates are listened for in a separate process thread and +applied automatically; the application does not need to allow +for, or trigger, updates. Latency And Throughput ---------------------- -While providing insulation from the underlying message -transport mechanics, RMR must also do so in such a manner -that message latency and throughput are not impacted. In -general, the RMR induced overhead, incurred due to the -process of selecting an endpoint for each message, is minimal -and should not impact the overall latency or throughput of -the application. This impact has been measured with test -applications running on the same physical host and the -average latency through RMR for a message was on the order of -0.02 milliseconds. - -As an application's throughput increases, it becomes easy for -the application to overrun the underlying transport mechanism -(e.g. NNG), consume all available TCP transmit buffers, or -otherwise find itself in a situation where a send might not -immediately complete. RMR offers different *modes* which -allow the application to manage these states based on the -overall needs of the application. These modes are discussed -in the *Configuration* section of this document. +While providing insulation from the underlying message +transport mechanics, RMR must also do so in such a manner +that message latency and throughput are not impacted. In +general, the RMR induced overhead, incurred due to the +process of selecting an endpoint for each message, is minimal +and should not impact the overall latency or throughput of +the application. This impact has been measured with test +applications running on the same physical host and the +average latency through RMR for a message was on the order of +0.02 milliseconds. + +As an application's throughput increases, it becomes easy for +the application to overrun the underlying transport mechanism +(e.g. NNG), consume all available TCP transmit buffers, or +otherwise find itself in a situation where a send might not +immediately complete. RMR offers different *modes* which +allow the application to manage these states based on the +overall needs of the application. These modes are discussed +in the *Configuration* section of this document. General Use =========== -To use, the RMR based application simply needs to initialise -the RMR environment, wait for RMR to have received a routing -table (become ready), and then invoke either the send or -receive functions. These steps, and some behind the scenes -details, are described in the following paragraphs. +To use, the RMR based application simply needs to initialise +the RMR environment, wait for RMR to have received a routing +table (become ready), and then invoke either the send or +receive functions. These steps, and some behind the scenes +details, are described in the following paragraphs. Initialisation -------------- -The RMR function ``rmr_init()`` is used to set up the RMR -environment and must be called before messages can be sent or -received. One of the few parameters that the application must -communicate to RMR is the port number that will be used as -the listen port for new connections. The port number is -passed on the initialisation function call and a TCP listen -socket will be opened with this port. If the port is already -in use RMR will report a failure; the application will need -to reinitialise with a different port number, abort, or take -some other action appropriate for the application. - -In addition to creating a TCP listen port, RMR will start a -process thread which will be responsible for receiving -dynamic updates to the route table. This thread also causes a -TCP listen port to be opened as it is expected that the -process which generates route table updates will connect and -send new information when needed. The route table update port -is **not** supplied by the application, but is supplied via -an environment variable as this value is likely determined by -the mechanism which is starting and configuring the -application. +The RMR function ``rmr_init()`` is used to set up the RMR +environment and must be called before messages can be sent or +received. One of the few parameters that the application must +communicate to RMR is the port number that will be used as +the listen port for new connections. The port number is +passed on the initialisation function call and a TCP listen +socket will be opened with this port. If the port is already +in use RMR will report a failure; the application will need +to reinitialise with a different port number, abort, or take +some other action appropriate for the application. + +In addition to creating a TCP listen port, RMR will start a +process thread which will be responsible for receiving +dynamic updates to the route table. This thread also causes a +TCP listen port to be opened as it is expected that the +process which generates route table updates will connect and +send new information when needed. The route table update port +is **not** supplied by the application, but is supplied via +an environment variable as this value is likely determined by +the mechanism which is starting and configuring the +application. The RMR Context --------------- -On successful initialisation, a void pointer, often called a -*handle* by some programming languages, is returned to the -application. This is a reference to the RMR control -information and must be passed as the first parameter on most -RMR function calls. RMR refers to this as the context, or -ctx. +On successful initialisation, a void pointer, often called a +*handle* by some programming languages, is returned to the +application. This is a reference to the RMR control +information and must be passed as the first parameter on most +RMR function calls. RMR refers to this as the context, or +ctx. Wait For Ready -------------- -An application which is only receiving messages does not need -to wait for RMR to *become ready* after the call to the -initialization function. However, before the application can -successfully send a message, RMR must have loaded a route -table, and the application must wait for RMR to report that -it has done so. The RMR function ``rmr_ready()`` will return -the value *true* (1) when a complete route table has been -loaded and can be used to determine the endpoint for a send -request. +An application which is only receiving messages does not need +to wait for RMR to *become ready* after the call to the +initialization function. However, before the application can +successfully send a message, RMR must have loaded a route +table, and the application must wait for RMR to report that +it has done so. The RMR function ``rmr_ready()`` will return +the value *true* (1) when a complete route table has been +loaded and can be used to determine the endpoint for a send +request. Receiving Messages ------------------ -The process of receiving is fairly straight forward. The -application invokes the RMR ``rmr_rcv_msg()`` function which -will block until a message is received. The function returns -a pointer to a message block which provides all of the -details about the message. Specifically, the application has -access to the following information either directly or -indirectly: - - -* The payload (actual data) - -* The total payload length in bytes - -* The number of bytes of the payload which contain valid data - -* The message type and subscription ID values - -* The hostname and IP address of the source of the message - (the sender) - -* The transaction ID - -* Tracing data (if provided) - - +The process of receiving is fairly straight forward. The +application invokes the RMR ``rmr_rcv_msg()`` function which +will block until a message is received. The function returns +a pointer to a message block which provides all of the +details about the message. Specifically, the application has +access to the following information either directly or +indirectly: + + +* The payload (actual data) + +* The total payload length in bytes + +* The number of bytes of the payload which contain valid data + +* The message type and subscription ID values + +* The hostname and IP address of the source of the message + (the sender) + +* The transaction ID + +* Tracing data (if provided) + + The Message Payload ------------------- -The message payload contains the *raw* data that was sent by -the peer application. The format will likely depend on the -message type, and is expected to be known by the application. -A direct pointer to the payload is available from the message -buffer (see appendix B for specific message buffer details). - -Two payload-related length values are also directly -available: the total payload length, and the number of bytes -actually filled with data. The used length is set by the -caller, and may or not be an accurate value. The total -payload length is determined when the buffer is created for -sending, and is the maximum number of bytes that the -application may modify should the buffer be used to return a -response. +The message payload contains the *raw* data that was sent by +the peer application. The format will likely depend on the +message type, and is expected to be known by the application. +A direct pointer to the payload is available from the message +buffer (see appendix B for specific message buffer details). + +Two payload-related length values are also directly +available: the total payload length, and the number of bytes +actually filled with data. The used length is set by the +caller, and may or not be an accurate value. The total +payload length is determined when the buffer is created for +sending, and is the maximum number of bytes that the +application may modify should the buffer be used to return a +response. Message Type and Subscription ID -------------------------------- -The message type and subscription ID are both directly -available from the message buffer, and are the values which -were used to by RMR in the sending application to select the -endpoint. If the application resends the message, as opposed -to returning the message buffer as a response, the message -number and/or the subscription ID might need to be changed to -avoid potential issues[1]. +The message type and subscription ID are both directly +available from the message buffer, and are the values which +were used to by RMR in the sending application to select the +endpoint. If the application resends the message, as opposed +to returning the message buffer as a response, the message +number and/or the subscription ID might need to be changed to +avoid potential issues[1]. Sender Information ------------------ -The source, or sender information, is indirectly available to -the application via the ``rmr_get_src()`` and -``rmr_get_ip()`` functions. The former returns a string -containing ``hostname:port,`` while the string -``ip:port`` is returned by the latter. +The source, or sender information, is indirectly available to +the application via the ``rmr_get_src()`` and +``rmr_get_ip()`` functions. The former returns a string +containing ``hostname:port,`` while the string +``ip:port`` is returned by the latter. Transaction ID -------------- -The message buffer contains a fixed length set of bytes which -applications can set to track related messages across the -application concept of a transaction. RMR will use the -transaction ID for matching a response message when the -``rmr_call()`` function is used to send a message. +The message buffer contains a fixed length set of bytes which +applications can set to track related messages across the +application concept of a transaction. RMR will use the +transaction ID for matching a response message when the +``rmr_call()`` function is used to send a message. Trace Information ----------------- -RMR supports the addition of an optional trace information to -any message. The presence and size is controlled by the -application, and can vary from message to message if desired. -The actual contents of the trace information is determined by -the application; RMR provides only the means to set, extract, -and obtain a direct reference to the trace bytes. The trace -data field in a message buffer is discussed in greater detail -in the *Trace Data* section. +RMR supports the addition of an optional trace information to +any message. The presence and size is controlled by the +application, and can vary from message to message if desired. +The actual contents of the trace information is determined by +the application; RMR provides only the means to set, extract, +and obtain a direct reference to the trace bytes. The trace +data field in a message buffer is discussed in greater detail +in the *Trace Data* section. Sending Messages ---------------- -Sending requires only slightly more work on the part of the -application than receiving a message. The application must -allocate an RMR message buffer, populate the message payload -with data, set the message type and length, and optionally -set the subscription ID. Information such as the source IP -address, hostname, and port are automatically added to the -message buffer by RMR, so there is no need for the -application to worry about these. +Sending requires only slightly more work on the part of the +application than receiving a message. The application must +allocate an RMR message buffer, populate the message payload +with data, set the message type and length, and optionally +set the subscription ID. Information such as the source IP +address, hostname, and port are automatically added to the +message buffer by RMR, so there is no need for the +application to worry about these. Message Buffer Allocation ------------------------- -The function ``rmr_msg_alloc()`` allocates a *zero copy* -buffer and returns a pointer to the RMR ``rmr_mbuf_t`` -structure. The message buffer provides direct access to the -payload, length, message type and subscription ID fields. The -buffer must be preallocated in order to allow the underlying -transport mechanism to allocate the payload space from its -internal memory pool; this eliminates multiple copies as the -message is sent, and thus is more efficient. - -If a message buffer has been received, and the application -wishes to use the buffer to send a response, or to forward -the buffer to another application, a new buffer does **not** -need to be allocated. The application may set the necessary -information (message type, etc.), and adjust the payload, as -is necessary and then pass the message buffer to -``rmr_send_msg()`` or ``rmr_rts_msg()`` to be sent or -returned to the sender. +The function ``rmr_msg_alloc()`` allocates a *zero copy* +buffer and returns a pointer to the RMR ``rmr_mbuf_t`` +structure. The message buffer provides direct access to the +payload, length, message type and subscription ID fields. The +buffer must be preallocated in order to allow the underlying +transport mechanism to allocate the payload space from its +internal memory pool; this eliminates multiple copies as the +message is sent, and thus is more efficient. + +If a message buffer has been received, and the application +wishes to use the buffer to send a response, or to forward +the buffer to another application, a new buffer does **not** +need to be allocated. The application may set the necessary +information (message type, etc.), and adjust the payload, as +is necessary and then pass the message buffer to +``rmr_send_msg()`` or ``rmr_rts_msg()`` to be sent or +returned to the sender. Populating the Message Buffer ----------------------------- -The application has direct access to several of the message -buffer fields, and should set them appropriately. - - - .. list-table:: - :widths: 15,80 - :header-rows: 0 - :class: borderless - - * - **len** - - - This is the number of bytes that the application placed into - the payload. Setting length to 0 is allowed, and length may - be less than the allocated payload size. - - * - **mtype** - - - The message type that RMR will use to determine the endpoint - used as the target of the send. - - * - **sub_id** - - - The subscription ID if the message is to be routed based on - the combination of message type and subscription ID. If no - subscription ID is valid for the message, the application - should set the field with the RMR constant - ``RMR_VOID_SUBID.`` - - * - **payload** - - - The application should obtain the reference (pointer) to the - payload from the message buffer and place any data into the - payload. The application is responsible for ensuring that the - maximum payload size is not exceeded. The application may - obtain the maximum size via the ``rmr_payload_size()`` - function. - - * - **trace data** - - - Optionally, the application may add trace information to the - message buffer. - - - +The application has direct access to several of the message +buffer fields, and should set them appropriately. + + + .. list-table:: + :widths: 15,80 + :header-rows: 0 + :class: borderless + + * - **len** + - + This is the number of bytes that the application placed into + the payload. Setting length to 0 is allowed, and length may + be less than the allocated payload size. + + * - **mtype** + - + The message type that RMR will use to determine the endpoint + used as the target of the send. + + * - **sub_id** + - + The subscription ID if the message is to be routed based on + the combination of message type and subscription ID. If no + subscription ID is valid for the message, the application + should set the field with the RMR constant + ``RMR_VOID_SUBID.`` + + * - **payload** + - + The application should obtain the reference (pointer) to the + payload from the message buffer and place any data into the + payload. The application is responsible for ensuring that the + maximum payload size is not exceeded. The application may + obtain the maximum size via the ``rmr_payload_size()`` + function. + + * - **trace data** + - + Optionally, the application may add trace information to the + message buffer. + + + Sending a Message Buffer ------------------------ -Once the application has populated the necessary bits of a -message, it may be sent by passing the buffer to the -``rmr_send_msg()`` function. This function will select an -endpoint to receive the message, based on message type and -subscription ID, and will pass the message to the underlying -transport mechanism for actual transmission on the -connection. (Depending on the underlying transport mechanism, -the actual connection to the endpoint may happen at the time -of the first message sent to the endpoint, and thus the -latency of the first send might be longer than expected.) - -On success, the send function will return a reference to a -message buffer; the status within that message buffer will -indicate what the message buffer contains. When the status is -``RMR_OK`` the reference is to a **new** message buffer for -the application to use for the next send; the payload size is -the same as the payload size allocated for the message that -was just sent. This is a convenience as it eliminates the -need for the application to call the message allocation -function at some point in the future, and assumes the -application will send many messages which will require the -same payload dimensions. - -If the message contains any status other than ``RMR_OK,`` -then the message could **not** be sent, and the reference is -to the unsent message buffer. The value of the status will -indicate whether the nature of the failure was transient ( -``RMR_ERR_RETRY``) or not. Transient failures are likely to -be successful if the application attempts to send the message -at a later time. Unfortunately, it is impossible for RMR to -know the exact transient failure (e.g. connection being -established, or TCP buffer shortage), and thus it is not -possible to communicate how long the application should wait -before attempting to resend, if the application wishes to -resend the message. (More discussion with respect to message -retries can be found in the *Handling Failures* section.) +Once the application has populated the necessary bits of a +message, it may be sent by passing the buffer to the +``rmr_send_msg()`` function. This function will select an +endpoint to receive the message, based on message type and +subscription ID, and will pass the message to the underlying +transport mechanism for actual transmission on the +connection. (Depending on the underlying transport mechanism, +the actual connection to the endpoint may happen at the time +of the first message sent to the endpoint, and thus the +latency of the first send might be longer than expected.) + +On success, the send function will return a reference to a +message buffer; the status within that message buffer will +indicate what the message buffer contains. When the status is +``RMR_OK`` the reference is to a **new** message buffer for +the application to use for the next send; the payload size is +the same as the payload size allocated for the message that +was just sent. This is a convenience as it eliminates the +need for the application to call the message allocation +function at some point in the future, and assumes the +application will send many messages which will require the +same payload dimensions. + +If the message contains any status other than ``RMR_OK,`` +then the message could **not** be sent, and the reference is +to the unsent message buffer. The value of the status will +indicate whether the nature of the failure was transient ( +``RMR_ERR_RETRY``) or not. Transient failures are likely to +be successful if the application attempts to send the message +at a later time. Unfortunately, it is impossible for RMR to +know the exact transient failure (e.g. connection being +established, or TCP buffer shortage), and thus it is not +possible to communicate how long the application should wait +before attempting to resend, if the application wishes to +resend the message. (More discussion with respect to message +retries can be found in the *Handling Failures* section.) Advanced Usage ============== -Several forms of usage fall into a more advanced category and -are described in the following sections. These include -blocking call, return to sender and wormhole functions. +Several forms of usage fall into a more advanced category and +are described in the following sections. These include +blocking call, return to sender and wormhole functions. The Call Function ----------------- -The RMR function ``rmr_call()`` sends a message in the exact -same manner as the ``rmr_send_msg()()`` function, with the -endpoint selection based on the message key. But unlike the -send function, ``rmr_call()`` will block and wait for a -response from the application that is selected to receive the -message. The matching message is determined by the -transaction ID which the application must place into the -message buffer prior to invoking ``rmr_call()``. Similarly, -the responding application must ensure that the same -transaction ID is placed into the message buffer before -returning its response. - -The return from the call is a message buffer with the -response message; there is no difference between a message -buffer returned by the receive function and one returned by -the ``rmr_call()`` function. If a response is not received in -a reasonable amount of time, a nil message buffer is returned -to the calling application. +The RMR function ``rmr_call()`` sends a message in the exact +same manner as the ``rmr_send_msg()()`` function, with the +endpoint selection based on the message key. But unlike the +send function, ``rmr_call()`` will block and wait for a +response from the application that is selected to receive the +message. The matching message is determined by the +transaction ID which the application must place into the +message buffer prior to invoking ``rmr_call()``. Similarly, +the responding application must ensure that the same +transaction ID is placed into the message buffer before +returning its response. + +The return from the call is a message buffer with the +response message; there is no difference between a message +buffer returned by the receive function and one returned by +the ``rmr_call()`` function. If a response is not received in +a reasonable amount of time, a nil message buffer is returned +to the calling application. Returning a Response -------------------- -Because of the nature of RMR's routing policies, it is -generally not possible for an application to control exactly -which endpoint is sent a message. There are cases, such as -responding to a message delivered via ``rmr_call()`` that the -application must send a message and guarantee that RMR routes -it to an exact destination. To enable this, RMR provides the -``rmr_rts_msg(),`` return to sender, function. Upon receipt -of any message, an application may alter the payload, and if -necessary the message type and subscription ID, and pass the -altered message buffer to the ``rmr_rts_msg()`` function to -return the altered message to the application which sent it. -When this function is used, RMR will examine the message -buffer for the source information and use that to select the -connection on which to write the response. +Because of the nature of RMR's routing policies, it is +generally not possible for an application to control exactly +which endpoint is sent a message. There are cases, such as +responding to a message delivered via ``rmr_call()`` that the +application must send a message and guarantee that RMR routes +it to an exact destination. To enable this, RMR provides the +``rmr_rts_msg(),`` return to sender, function. Upon receipt +of any message, an application may alter the payload, and if +necessary the message type and subscription ID, and pass the +altered message buffer to the ``rmr_rts_msg()`` function to +return the altered message to the application which sent it. +When this function is used, RMR will examine the message +buffer for the source information and use that to select the +connection on which to write the response. Multi-threaded Calls -------------------- -The basic call mechanism described above is **not** thread -safe, as it is not possible to guarantee that a response -message is delivered to the correct thread. The RMR function -``rmr_mt_call()`` accepts an additional parameter which -identifies the calling thread in order to ensure that the -response is delivered properly. In addition, the application -must specifically initialise the multi-threaded call -environment by passing the ``RMRFL_MTCALL`` flag as an option -to the ``rmr_init()`` function. - -One advantage of the multi-threaded call capability in RMR is -the fact that only the calling thread is blocked. Messages -received which are not responses to the call are continued to -be delivered via normal ``rmr_rcv_msg()`` calls. - -While the process is blocked waiting for the response, it is -entirely possible that asynchronous, non-matching, messages -will arrive. When this happens, RMR will queues the messages -and return them to the application over the next calls to -``rmr_rcv_msg().`` +The basic call mechanism described above is **not** thread +safe, as it is not possible to guarantee that a response +message is delivered to the correct thread. The RMR function +``rmr_mt_call()`` accepts an additional parameter which +identifies the calling thread in order to ensure that the +response is delivered properly. In addition, the application +must specifically initialise the multi-threaded call +environment by passing the ``RMRFL_MTCALL`` flag as an option +to the ``rmr_init()`` function. + +One advantage of the multi-threaded call capability in RMR is +the fact that only the calling thread is blocked. Messages +received which are not responses to the call are continued to +be delivered via normal ``rmr_rcv_msg()`` calls. + +While the process is blocked waiting for the response, it is +entirely possible that asynchronous, non-matching, messages +will arrive. When this happens, RMR will queues the messages +and return them to the application over the next calls to +``rmr_rcv_msg().`` Wormholes --------- -As was mentioned earlier, the design of RMR is to eliminate -the need for an application to know a specific endpoint, even -when a response message is being sent. In some rare cases it -may be necessary for an application to establish a direct -connection to an RMR-based application rather than relying on -message type and subscription ID based routing. The -*wormhole* functions provide an application with the ability -to create a direct connection and then to send and receive -messages across the connection. The following are the RMR -functions which provide wormhole communications: - - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **rmr_wh_open** - - - Open a connection to an endpoint. Name or IP address and port - of the endpoint is supplied. Returns a wormhole ID that the - application must use when sending a direct message. - - * - **rmr_wh_send_msg** - - - Sends an RMR message buffer to the connected application. The - message type and subscription ID may be set in the message, - but RMR will ignore both. - - * - **rmr_wh_close** - - - Closes the direct connection. - - - +As was mentioned earlier, the design of RMR is to eliminate +the need for an application to know a specific endpoint, even +when a response message is being sent. In some rare cases it +may be necessary for an application to establish a direct +connection to an RMR-based application rather than relying on +message type and subscription ID based routing. The +*wormhole* functions provide an application with the ability +to create a direct connection and then to send and receive +messages across the connection. The following are the RMR +functions which provide wormhole communications: + + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **rmr_wh_open** + - + Open a connection to an endpoint. Name or IP address and port + of the endpoint is supplied. Returns a wormhole ID that the + application must use when sending a direct message. + + * - **rmr_wh_send_msg** + - + Sends an RMR message buffer to the connected application. The + message type and subscription ID may be set in the message, + but RMR will ignore both. + + * - **rmr_wh_close** + - + Closes the direct connection. + + + Handling Failures ================= -The vast majority of states reported by RMR are fatal; if -encountered during setup or initialization, then it is -unlikely that any message oriented processing should -continue, and when encountered on a message operation -continued operation on that message should be abandoned. -Specifically with regard to message sending, it is very -likely that the underlying transport mechanism will report a -*soft,* or transient, failure which might be successful if -the operation is retried at a later point in time. The -paragraphs below discuss the methods that an application -might deal with these soft failures. +The vast majority of states reported by RMR are fatal; if +encountered during setup or initialization, then it is +unlikely that any message oriented processing should +continue, and when encountered on a message operation +continued operation on that message should be abandoned. +Specifically with regard to message sending, it is very +likely that the underlying transport mechanism will report a +*soft,* or transient, failure which might be successful if +the operation is retried at a later point in time. The +paragraphs below discuss the methods that an application +might deal with these soft failures. Failure Notification -------------------- -When a soft failure is reported, the returned message buffer -returned by the RMR function will be ``RMR_ERR_RETRY.`` These -types of failures can occur for various reasons; one of two -reasons is typically the underlying cause: - - -* The session to the targeted recipient (endpoint) is not - connected. - -* The transport mechanism buffer pool is full and cannot - accept another buffer. - - - -Unfortunately, it is not possible for RMR to determine which -of these two cases is occurring, and equally as unfortunate -the time to resolve each is different. The first, no -connection, may require up to a second before a message can -be accepted, while a rejection because of buffer shortage is -likely to resolve in less than a millisecond. +When a soft failure is reported, the returned message buffer +returned by the RMR function will be ``RMR_ERR_RETRY.`` These +types of failures can occur for various reasons; one of two +reasons is typically the underlying cause: + + +* The session to the targeted recipient (endpoint) is not + connected. + +* The transport mechanism buffer pool is full and cannot + accept another buffer. + + + +Unfortunately, it is not possible for RMR to determine which +of these two cases is occurring, and equally as unfortunate +the time to resolve each is different. The first, no +connection, may require up to a second before a message can +be accepted, while a rejection because of buffer shortage is +likely to resolve in less than a millisecond. Application Response -------------------- -The action which an application takes when a soft failure is -reported ultimately depends on the nature of the application -with respect to factors such as tolerance to extended message -latency, dropped messages, and over all message rate. +The action which an application takes when a soft failure is +reported ultimately depends on the nature of the application +with respect to factors such as tolerance to extended message +latency, dropped messages, and over all message rate. RMR Retry Modes --------------- -In an effort to reduce the workload of an application -developer, RMR has a default retry policy such that RMR will -attempt to retransmit a message up to 1000 times when a soft -failure is reported. These retries generally take less than 1 -millisecond (if all 1000 are attempted) and in most cases -eliminates nearly all reported soft failures to the -application. When using this mode, it might allow the -application to simply treat all bad return values from a send -attempt as permanent failures. - -If an application is so sensitive to any delay in RMR, or the -underlying transport mechanism, it is possible to set RMR to -return a failure immediately on any kind of error (permanent -failures are always reported without retry). In this mode, -RMR will still set the state in the message buffer to -``RMR_ERR_RETRY,`` but will **not** make any attempts to -resend the message. This zero-retry policy is enabled by -invoking the ``rmr_set_stimeout()`` with a value of 0; this -can be done once immediately after ``rmr_init()`` is invoked. - -Regardless of the retry mode which the application sets, it -will ultimately be up to the application to handle failures -by queuing the message internally for resend, retrying -immediately, or dropping the send attempt all together. As -stated before, only the application can determine how to best -handle send failures. +In an effort to reduce the workload of an application +developer, RMR has a default retry policy such that RMR will +attempt to retransmit a message up to 1000 times when a soft +failure is reported. These retries generally take less than 1 +millisecond (if all 1000 are attempted) and in most cases +eliminates nearly all reported soft failures to the +application. When using this mode, it might allow the +application to simply treat all bad return values from a send +attempt as permanent failures. + +If an application is so sensitive to any delay in RMR, or the +underlying transport mechanism, it is possible to set RMR to +return a failure immediately on any kind of error (permanent +failures are always reported without retry). In this mode, +RMR will still set the state in the message buffer to +``RMR_ERR_RETRY,`` but will **not** make any attempts to +resend the message. This zero-retry policy is enabled by +invoking the ``rmr_set_stimeout()`` with a value of 0; this +can be done once immediately after ``rmr_init()`` is invoked. + +Regardless of the retry mode which the application sets, it +will ultimately be up to the application to handle failures +by queuing the message internally for resend, retrying +immediately, or dropping the send attempt all together. As +stated before, only the application can determine how to best +handle send failures. Other Failures -------------- -RMR will return the state of processing for message based -operations (send/receive) as the status in the message -buffer. For non-message operations, state is returned to the -caller as the integer return value for all functions which -are not expected to return a pointer (e.g. -``rmr_init()``.) The following are the RMR state constants -and a brief description of their meaning. - - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **RMR_OK** - - - state is good; operation finished successfully - - * - **RMR_ERR_BADARG** - - - argument passed to function was unusable - - * - **RMR_ERR_NOENDPT** - - - send/call could not find an endpoint based on msg type - - * - **RMR_ERR_EMPTY** - - - msg received had no payload; attempt to send an empty message - - * - **RMR_ERR_NOHDR** - - - message didn't contain a valid header - - * - **RMR_ERR_SENDFAILED** - - - send failed; errno may contain the transport provider reason - - * - **RMR_ERR_CALLFAILED** - - - unable to send the message for a call function; errno may - contain the transport provider reason - - * - **RMR_ERR_NOWHOPEN** - - - no wormholes are open - - * - **RMR_ERR_WHID** - - - the wormhole id provided was invalid - - * - **RMR_ERR_OVERFLOW** - - - operation would have busted through a buffer/field size - - * - **RMR_ERR_RETRY** - - - request (send/call/rts) failed, but caller should retry - (EAGAIN for wrappers) - - * - **RMR_ERR_RCVFAILED** - - - receive failed (hard error) - - * - **RMR_ERR_TIMEOUT** - - - response message not received in a reasonable amount of time - - * - **RMR_ERR_UNSET** - - - the message hasn't been populated with a transport buffer - - * - **RMR_ERR_TRUNC** - - - length in the received buffer is longer than the size of the - allocated payload, received message likely truncated (length - set by sender could be wrong, but we can't know that) - - * - **RMR_ERR_INITFAILED** - - - initialisation of something (probably message) failed - - * - **RMR_ERR_NOTSUPP** - - - the request is not supported, or RMR was not initialised for - the request - - - -Depending on the underlying transport mechanism, and the -nature of the call that RMR attempted, the system -``errno`` value might reflect additional detail about the -failure. Applications should **not** rely on errno as some -transport mechanisms do not set it with any consistency. +RMR will return the state of processing for message based +operations (send/receive) as the status in the message +buffer. For non-message operations, state is returned to the +caller as the integer return value for all functions which +are not expected to return a pointer (e.g. +``rmr_init()``.) The following are the RMR state constants +and a brief description of their meaning. + + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **RMR_OK** + - + state is good; operation finished successfully + + * - **RMR_ERR_BADARG** + - + argument passed to function was unusable + + * - **RMR_ERR_NOENDPT** + - + send/call could not find an endpoint based on msg type + + * - **RMR_ERR_EMPTY** + - + msg received had no payload; attempt to send an empty message + + * - **RMR_ERR_NOHDR** + - + message didn't contain a valid header + + * - **RMR_ERR_SENDFAILED** + - + send failed; errno may contain the transport provider reason + + * - **RMR_ERR_CALLFAILED** + - + unable to send the message for a call function; errno may + contain the transport provider reason + + * - **RMR_ERR_NOWHOPEN** + - + no wormholes are open + + * - **RMR_ERR_WHID** + - + the wormhole id provided was invalid + + * - **RMR_ERR_OVERFLOW** + - + operation would have busted through a buffer/field size + + * - **RMR_ERR_RETRY** + - + request (send/call/rts) failed, but caller should retry + (EAGAIN for wrappers) + + * - **RMR_ERR_RCVFAILED** + - + receive failed (hard error) + + * - **RMR_ERR_TIMEOUT** + - + response message not received in a reasonable amount of time + + * - **RMR_ERR_UNSET** + - + the message hasn't been populated with a transport buffer + + * - **RMR_ERR_TRUNC** + - + length in the received buffer is longer than the size of the + allocated payload, received message likely truncated (length + set by sender could be wrong, but we can't know that) + + * - **RMR_ERR_INITFAILED** + - + initialisation of something (probably message) failed + + * - **RMR_ERR_NOTSUPP** + - + the request is not supported, or RMR was not initialised for + the request + + + +Depending on the underlying transport mechanism, and the +nature of the call that RMR attempted, the system +``errno`` value might reflect additional detail about the +failure. Applications should **not** rely on errno as some +transport mechanisms do not set it with any consistency. Configuration and Control ========================= -With the assumption that most RMR based applications will be -executed in a containerised environment, there are some -underlying mechanics which the developer may need to know in -order to properly provide a configuration specification to -the container management system. The following paragraphs -briefly discuss these. - +With the assumption that most RMR based applications will be +executed in a containerised environment, there are some +underlying mechanics which the developer may need to know in +order to properly provide a configuration specification to +the container management system. The following paragraphs +briefly discuss these. + TCP Ports --------- -RMR requires two (2) TCP listen ports: one for general -application-to-application communications and one for -route-table updates. The general communication port is -specified by the application at the time RMR is initialised. -The port used to listen for route table updates is likely to -be a constant port shared by all applications provided they -are running in separate containers. To that end, the port -number defaults to 4561, but can be configured with an -environment variable (see later paragraph in this section). +RMR requires two (2) TCP listen ports: one for general +application-to-application communications and one for +route-table updates. The general communication port is +specified by the application at the time RMR is initialised. +The port used to listen for route table updates is likely to +be a constant port shared by all applications provided they +are running in separate containers. To that end, the port +number defaults to 4561, but can be configured with an +environment variable (see later paragraph in this section). Host Names ---------- -RMR is typically host name agnostic. Route table entries may -contain endpoints defined either by host name or IP address. -In the container world the concept of a *service name* might -exist, and likely is different than a host name. RMR's only -requirement with respect to host names is that a name used on -a route table entry must be resolvable via the -``gethostbyname`` system call. +RMR is typically host name agnostic. Route table entries may +contain endpoints defined either by host name or IP address. +In the container world the concept of a *service name* might +exist, and likely is different than a host name. RMR's only +requirement with respect to host names is that a name used on +a route table entry must be resolvable via the +``gethostbyname`` system call. Environment Variables --------------------- -Several environment variables are recognised by RMR which, in -general, are used to define interfaces and listen ports (e.g. -the route table update listen port), or debugging -information. Generally this information is system controlled -and thus RMR expects this information to be defined in the -environment rather than provided by the application. The -following is a list of the environment variables which RMR -recognises: - - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **RMR_BIND_IF** - - - The interface to bind to listen ports to. If not defined - 0.0.0.0 (all interfaces) is assumed. - - * - **RMR_RTG_SVC** - - - The port RMR will listen on for route manager connections. If - not defined 4561 is used. - - * - **RMR_SEED_RT** - - - Where RMR expects to find the name of the seed (static) route - table. If not defined no static table is read. - - * - **RMR_RTG_ISRAW** - - - If the value set to 0, RMR expects the route table manager - messages to be messages with and RMR header. If this is not - defined messages are assumed to be "raw" (without an RMR - header. - - * - **RMR_VCTL_FILE** - - - Provides a file which is used to set the verbose level of the - route table collection thread. The first line of the file is - read and expected to contain an integer value to set the - verbose level. The value may be changed at any time and the - route table thread will adjust accordingly. - - * - **RMR_SRC_NAMEONLY** - - - If the value of this variable is greater than 0, RMR will not - permit the IP address to be sent as the message source. Only - the host name will be sent as the source in the message - header. - - - +Several environment variables are recognised by RMR which, in +general, are used to define interfaces and listen ports (e.g. +the route table update listen port), or debugging +information. Generally this information is system controlled +and thus RMR expects this information to be defined in the +environment rather than provided by the application. The +following is a list of the environment variables which RMR +recognises: + + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **RMR_BIND_IF** + - + The interface to bind to listen ports to. If not defined + 0.0.0.0 (all interfaces) is assumed. + + * - **RMR_RTG_SVC** + - + The port RMR will listen on for route manager connections. If + not defined 4561 is used. + + * - **RMR_SEED_RT** + - + Where RMR expects to find the name of the seed (static) route + table. If not defined no static table is read. + + * - **RMR_RTG_ISRAW** + - + If the value set to 0, RMR expects the route table manager + messages to be messages with and RMR header. If this is not + defined messages are assumed to be "raw" (without an RMR + header. + + * - **RMR_VCTL_FILE** + - + Provides a file which is used to set the verbose level of the + route table collection thread. The first line of the file is + read and expected to contain an integer value to set the + verbose level. The value may be changed at any time and the + route table thread will adjust accordingly. + + * - **RMR_SRC_NAMEONLY** + - + If the value of this variable is greater than 0, RMR will not + permit the IP address to be sent as the message source. Only + the host name will be sent as the source in the message + header. + + + Logging ------- -RMR does **not** use any logging libraries; any error or -warning messages are written to standard error. RMR messages -are written with one of three prefix strings: - - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **[CRI]** - - - The event is of a critical nature and it is unlikely that RMR - will continue to operate correctly if at all. It is almost - certain that immediate action will be needed to resolve the - issue. - - * - **[ERR]** - - - The event is not expected and RMR is not able to handle it. - There is a small chance that continued operation will be - negatively impacted. Eventual action to diagnose and correct - the issue will be necessary. - - * - **[WRN]** - - - The event was not expected by RMR, but can be worked round. - Normal operation will continue, but it is recommended that - the cause of the problem be investigated. - - - +RMR does **not** use any logging libraries; any error or +warning messages are written to standard error. RMR messages +are written with one of three prefix strings: + + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **[CRI]** + - + The event is of a critical nature and it is unlikely that RMR + will continue to operate correctly if at all. It is almost + certain that immediate action will be needed to resolve the + issue. + + * - **[ERR]** + - + The event is not expected and RMR is not able to handle it. + There is a small chance that continued operation will be + negatively impacted. Eventual action to diagnose and correct + the issue will be necessary. + + * - **[WRN]** + - + The event was not expected by RMR, but can be worked round. + Normal operation will continue, but it is recommended that + the cause of the problem be investigated. + + + Notes ===== - - [1] It is entirely possible to design a routing table, and - application group, such that the same message type is is - left unchanged and the message is forwarded by an - application after updating the payload. This type of - behaviour is often referred to as service chaining, and can - be done without any "knowledge" by an application with - respect to where the message goes next. Service chaining is - supported by RMR in as much as it allows the message to be - resent, but the actual complexities of designing and - implementing service chaining lie with the route table - generator process. - - - - + + [1] It is entirely possible to design a routing table, and + application group, such that the same message type is is + left unchanged and the message is forwarded by an + application after updating the payload. This type of + behaviour is often referred to as service chaining, and can + be done without any "knowledge" by an application with + respect to where the message goes next. Service chaining is + supported by RMR in as much as it allows the message to be + resent, but the actual complexities of designing and + implementing service chaining lie with the route table + generator process. + + + + Appendix A -- Quick Reference ============================= -Please refer to the RMR manual pages on the Read the Docs -site - -https://docs.o-ran-sc.org/projects/o-ran-sc-ric-plt-lib-rmr/en/latest/index.html - +Please refer to the RMR manual pages on the Read the Docs +site + +https://docs.o-ran-sc.org/projects/o-ran-sc-ric-plt-lib-rmr/en/latest/index.html + Appendix B -- Message Buffer Details ==================================== -The RMR message buffer is a C structure which is exposed in -the ``rmr.h`` header file. It is used to manage a message -received from a peer endpoint, or a message that is being -sent to a peer. Fields include payload length, amount of -payload actually used, status, and a reference to the -payload. There are also fields which the application should -ignore, and could be hidden in the header file, but we chose -not to. These fields include a reference to the RMR header -information, and to the underlying transport mechanism -message struct which may or may not be the same as the RMR -header reference. +The RMR message buffer is a C structure which is exposed in +the ``rmr.h`` header file. It is used to manage a message +received from a peer endpoint, or a message that is being +sent to a peer. Fields include payload length, amount of +payload actually used, status, and a reference to the +payload. There are also fields which the application should +ignore, and could be hidden in the header file, but we chose +not to. These fields include a reference to the RMR header +information, and to the underlying transport mechanism +message struct which may or may not be the same as the RMR +header reference. The Structure ------------- -The following is the C structure. Readers are cautioned to -examine the ``rmr.h`` header file directly; the information -here may be out of date (old document in some cache), and -thus it may be incorrect. - - -:: - - +The following is the C structure. Readers are cautioned to +examine the ``rmr.h`` header file directly; the information +here may be out of date (old document in some cache), and +thus it may be incorrect. + + +:: + + typedef struct { int state; // state of processing int mtype; // message type @@ -895,7 +895,7 @@ thus it may be incorrect. unsigned char* xaction; // pointer to fixed length transaction id bytes int sub_id; // subscription id int tp_state; // transport state (errno) - + // these things are off limits to the user application void* tp_buf; // underlying transport allocated pointer (e.g. nng message) void* header; // internal message header (whole buffer: header+payload) @@ -906,287 +906,287 @@ thus it may be incorrect. int rts_fd; // SI fd for return to sender int cookie; // cookie to detect user misuse of free'd msg } rmr_mbuf_t; - - + + State vs Transport State ------------------------ -The state field reflects the state at the time the message -buffer is returned to the calling application. For a send -operation, if the state is not ``RMR_OK`` then the message -buffer references the payload that could not be sent, and -when the state is ``RMR_OK`` the buffer references a *fresh* -payload that the application may fill in. - -When the state is not ``RMR_OK,`` C programmes may examine -the global ``errno`` value which RMR will have left set, if -it was set, by the underlying transport mechanism. In some -cases, wrapper modules are not able to directly access the -C-library ``errno`` value, and to assist with possible -transport error details, the send and receive operations -populate ``tp_state`` with the value of ``errno.`` - -Regardless of whether the application makes use of the -``tp_state,`` or the ``errno`` value, it should be noted that -the underlying transport mechanism may not actually update -the errno value; in other words: it might not be accurate. In -addition, RMR populates the ``tp_state`` value in the message -buffer **only** when the state is not ``RMR_OK.`` +The state field reflects the state at the time the message +buffer is returned to the calling application. For a send +operation, if the state is not ``RMR_OK`` then the message +buffer references the payload that could not be sent, and +when the state is ``RMR_OK`` the buffer references a *fresh* +payload that the application may fill in. + +When the state is not ``RMR_OK,`` C programmes may examine +the global ``errno`` value which RMR will have left set, if +it was set, by the underlying transport mechanism. In some +cases, wrapper modules are not able to directly access the +C-library ``errno`` value, and to assist with possible +transport error details, the send and receive operations +populate ``tp_state`` with the value of ``errno.`` + +Regardless of whether the application makes use of the +``tp_state,`` or the ``errno`` value, it should be noted that +the underlying transport mechanism may not actually update +the errno value; in other words: it might not be accurate. In +addition, RMR populates the ``tp_state`` value in the message +buffer **only** when the state is not ``RMR_OK.`` Field References ---------------- -The transaction field was exposed in the first version of -RMR, and in hindsight this shouldn't have been done. Rather -than break any existing code the reference was left, but -additional fields such as trace data, were not directly -exposed to the application. The application developer is -strongly encouraged to use the functions which get and set -the transaction ID rather than using the pointer directly; -any data overruns will not be detected if the reference is -used directly. - -In contrast, the payload reference should be used directly by -the application in the interest of speed and ease of -programming. The same care to prevent writing more bytes to -the payload buffer than it can hold must be taken by the -application. By the nature of the allocation of the payload -in transport space, RMR is unable to add guard bytes and/or -test for data overrun. +The transaction field was exposed in the first version of +RMR, and in hindsight this shouldn't have been done. Rather +than break any existing code the reference was left, but +additional fields such as trace data, were not directly +exposed to the application. The application developer is +strongly encouraged to use the functions which get and set +the transaction ID rather than using the pointer directly; +any data overruns will not be detected if the reference is +used directly. + +In contrast, the payload reference should be used directly by +the application in the interest of speed and ease of +programming. The same care to prevent writing more bytes to +the payload buffer than it can hold must be taken by the +application. By the nature of the allocation of the payload +in transport space, RMR is unable to add guard bytes and/or +test for data overrun. Actual Transmission ------------------- -When RMR sends the application's message, the message buffer -is **not** transmitted. The transport buffer (tp_buf) which -contains the RMR header and application payload is the only -set of bytes which are transmitted. While it may seem to the -caller like the function ``rmr_send_msg()`` is returning a -new message buffer, the same struct is reused and only a new -transport buffer is allocated. The intent is to keep the -alloc/free cycles to a minimum. - +When RMR sends the application's message, the message buffer +is **not** transmitted. The transport buffer (tp_buf) which +contains the RMR header and application payload is the only +set of bytes which are transmitted. While it may seem to the +caller like the function ``rmr_send_msg()`` is returning a +new message buffer, the same struct is reused and only a new +transport buffer is allocated. The intent is to keep the +alloc/free cycles to a minimum. + Appendix C -- Glossary ====================== -Many terms in networking can be interpreted with multiple -meanings, and several terms used in various RMR documentation -are RMR specific. The following definitions are the meanings -of terms used within RMR documentation and should help the -reader to understand the intent of meaning. - - .. list-table:: - :widths: 25,70 - :header-rows: 0 - :class: borderless - - * - **application** - - - A programme which uses RMR to send and/or receive messages - to/from another RMR based application. - - * - **Critical error** - - - An error that RMR has encountered which will prevent further - successful processing by RMR. Critical errors usually - indicate that the application should abort. - - * - **Endpoint** - - - An RMR based application that is defined as being capable of - receiving one or more types of messages (as defined by a - *routing key.*) - - * - **Environment variable** - - - A key/value pair which is set externally to the application, - but which is available to the application (and referenced - libraries) through the ``getenv`` system call. Environment - variables are the main method of communicating information - such as port numbers to RMR. - - * - **Error** - - - An abnormal condition that RMR has encountered, but will not - affect the overall processing by RMR, but may impact certain - aspects such as the ability to communicate with a specific - endpoint. Errors generally indicate that something, usually - external to RMR, must be addressed. - - * - **Host name** - - - The name of the host as returned by the ``gethostbyname`` - system call. In a containerised environment this might be the - container or service name depending on how the container is - started. From RMR's point of view, a host name can be used to - resolve an *endpoint* definition in a *route* table.) - - * - **IP** - - - Internet protocol. A low level transmission protocol which - governs the transmission of datagrams across network - boundaries. - - * - **Listen socket** - - - A *TCP* socket used to await incoming connection requests. - Listen sockets are defined by an interface and port number - combination where the port number is unique for the - interface. - - * - **Message** - - - A series of bytes transmitted from the application to another - RMR based application. A message is comprised of RMR specific - data (a header), and application data (a payload). - - * - **Message buffer** - - - A data structure used to describe a message which is to be - sent or has been received. The message buffer includes the - payload length, message type, message source, and other - information. - - * - **Message type** - - - A signed integer (0-32000) which identifies the type of - message being transmitted, and is one of the two components - of a *routing key.* See *Subscription ID.* - - * - **Payload** - - - The portion of a message which holds the user data to be - transmitted to the remote *endpoint.* The payload contents - are completely application defined. - - * - **RMR context** - - - A set of information which defines the current state of the - underlying transport connections that RMR is managing. The - application will be give a context reference (pointer) that - is supplied to most RMR functions as the first parameter. - - * - **Round robin** - - - The method of selecting an *endpoint* from a list such that - all *endpoints* are selected before starting at the head of - the list. - - * - **Route table** - - - A series of "rules" which define the possible *endpoints* for - each *routing key.* - - * - **Route table manager** - - - An application responsible for building a *route table* and - then distributing it to all applicable RMR based - applications. - - * - **Routing** - - - The process of selecting an *endpoint* which will be the - recipient of a message. - - * - **Routing key** - - - A combination of *message type* and *subscription ID* which - RMR uses to select the destination *endpoint* when sending a - message. - - * - **Source** - - - The sender of a message. - - * - **Subscription ID** - - - A signed integer value (0-32000) which identifies the - subscription characteristic of a message. It is used in - conjunction with the *message type* to determine the *routing - key.* - - * - **Target** - - - The *endpoint* selected to receive a message. - - * - **TCP** - - - Transmission Control Protocol. A connection based internet - protocol which provides for lossless packet transportation, - usually over IP. - - * - **Thread** - - - Also called a *process thread, or pthread.* This is a - lightweight process which executes in concurrently with the - application and shares the same address space. RMR uses - threads to manage asynchronous functions such as route table - updates. - - * - **Trace information** - - - An optional portion of the message buffer that the - application may populate with data that allows for tracing - the progress of the transaction or application activity - across components. RMR makes no use of this data. - - * - **Transaction ID** - - - A fixed number of bytes in the *message* buffer) which the - application may populate with information related to the - transaction. RMR makes use of the transaction ID for matching - response messages with the &c function is used to send a - message. - - * - **Transient failure** - - - An error state that is believed to be short lived and that - the operation, if retried by the application, might be - successful. C programmers will recognise this as - ``EAGAIN.`` - - * - **Warning** - - - A warning occurs when RMR has encountered something that it - believes isn't correct, but has a defined work round. - - * - **Wormhole** - - - A direct connection managed by RMR between the user - application and a remote, RMR based, application. - - - +Many terms in networking can be interpreted with multiple +meanings, and several terms used in various RMR documentation +are RMR specific. The following definitions are the meanings +of terms used within RMR documentation and should help the +reader to understand the intent of meaning. + + .. list-table:: + :widths: 25,70 + :header-rows: 0 + :class: borderless + + * - **application** + - + A programme which uses RMR to send and/or receive messages + to/from another RMR based application. + + * - **Critical error** + - + An error that RMR has encountered which will prevent further + successful processing by RMR. Critical errors usually + indicate that the application should abort. + + * - **Endpoint** + - + An RMR based application that is defined as being capable of + receiving one or more types of messages (as defined by a + *routing key.*) + + * - **Environment variable** + - + A key/value pair which is set externally to the application, + but which is available to the application (and referenced + libraries) through the ``getenv`` system call. Environment + variables are the main method of communicating information + such as port numbers to RMR. + + * - **Error** + - + An abnormal condition that RMR has encountered, but will not + affect the overall processing by RMR, but may impact certain + aspects such as the ability to communicate with a specific + endpoint. Errors generally indicate that something, usually + external to RMR, must be addressed. + + * - **Host name** + - + The name of the host as returned by the ``gethostbyname`` + system call. In a containerised environment this might be the + container or service name depending on how the container is + started. From RMR's point of view, a host name can be used to + resolve an *endpoint* definition in a *route* table.) + + * - **IP** + - + Internet protocol. A low level transmission protocol which + governs the transmission of datagrams across network + boundaries. + + * - **Listen socket** + - + A *TCP* socket used to await incoming connection requests. + Listen sockets are defined by an interface and port number + combination where the port number is unique for the + interface. + + * - **Message** + - + A series of bytes transmitted from the application to another + RMR based application. A message is comprised of RMR specific + data (a header), and application data (a payload). + + * - **Message buffer** + - + A data structure used to describe a message which is to be + sent or has been received. The message buffer includes the + payload length, message type, message source, and other + information. + + * - **Message type** + - + A signed integer (0-32000) which identifies the type of + message being transmitted, and is one of the two components + of a *routing key.* See *Subscription ID.* + + * - **Payload** + - + The portion of a message which holds the user data to be + transmitted to the remote *endpoint.* The payload contents + are completely application defined. + + * - **RMR context** + - + A set of information which defines the current state of the + underlying transport connections that RMR is managing. The + application will be give a context reference (pointer) that + is supplied to most RMR functions as the first parameter. + + * - **Round robin** + - + The method of selecting an *endpoint* from a list such that + all *endpoints* are selected before starting at the head of + the list. + + * - **Route table** + - + A series of "rules" which define the possible *endpoints* for + each *routing key.* + + * - **Route table manager** + - + An application responsible for building a *route table* and + then distributing it to all applicable RMR based + applications. + + * - **Routing** + - + The process of selecting an *endpoint* which will be the + recipient of a message. + + * - **Routing key** + - + A combination of *message type* and *subscription ID* which + RMR uses to select the destination *endpoint* when sending a + message. + + * - **Source** + - + The sender of a message. + + * - **Subscription ID** + - + A signed integer value (0-32000) which identifies the + subscription characteristic of a message. It is used in + conjunction with the *message type* to determine the *routing + key.* + + * - **Target** + - + The *endpoint* selected to receive a message. + + * - **TCP** + - + Transmission Control Protocol. A connection based internet + protocol which provides for lossless packet transportation, + usually over IP. + + * - **Thread** + - + Also called a *process thread, or pthread.* This is a + lightweight process which executes in concurrently with the + application and shares the same address space. RMR uses + threads to manage asynchronous functions such as route table + updates. + + * - **Trace information** + - + An optional portion of the message buffer that the + application may populate with data that allows for tracing + the progress of the transaction or application activity + across components. RMR makes no use of this data. + + * - **Transaction ID** + - + A fixed number of bytes in the *message* buffer) which the + application may populate with information related to the + transaction. RMR makes use of the transaction ID for matching + response messages with the &c function is used to send a + message. + + * - **Transient failure** + - + An error state that is believed to be short lived and that + the operation, if retried by the application, might be + successful. C programmers will recognise this as + ``EAGAIN.`` + + * - **Warning** + - + A warning occurs when RMR has encountered something that it + believes isn't correct, but has a defined work round. + + * - **Wormhole** + - + A direct connection managed by RMR between the user + application and a remote, RMR based, application. + + + Appendix D -- Code Examples =========================== -The following snippet of code illustrate some of the basic -operation of the RMR library. Please refer to the examples -and test directories in the RMR repository for complete RMR -based programmes. +The following snippet of code illustrate some of the basic +operation of the RMR library. Please refer to the examples +and test directories in the RMR repository for complete RMR +based programmes. Sender Sample ------------- -The following code segment shows how a message buffer can be -allocated, populated, and sent. The snippet also illustrates -how the result from the ``rmr_send_msg()`` function is used -to send the next message. It does not illustrate error and/or -retry handling. - - -:: - - +The following code segment shows how a message buffer can be +allocated, populated, and sent. The snippet also illustrates +how the result from the ``rmr_send_msg()`` function is used +to send the next message. It does not illustrate error and/or +retry handling. + + +:: + + #include #include #include @@ -1194,9 +1194,9 @@ retry handling. #include #include #include - + #include - + int main( int argc, char** argv ) { void* mrc; // msg router context struct epoll_event events[1]; // list of events to give to epoll @@ -1212,7 +1212,7 @@ retry handling. int delay = 1000000; // mu-sec delay between messages int mtype = 0; int stats_freq = 100; - + if( argc > 1 ) { // simplistic arg picking listen_port = argv[1]; } @@ -1222,15 +1222,15 @@ retry handling. if( argc > 3 ) { mtype = atoi( argv[3] ); } - + fprintf( stderr, " listen port: %s; mtype: %d; delay: %d\\n", listen_port, mtype, delay ); - + if( (mrc = rmr_init( listen_port, 1400, RMRFL_NONE )) == NULL ) { fprintf( stderr, " unable to initialise RMR\\n" ); exit( 1 ); } - + rcv_fd = rmr_get_rcvfd( mrc ); // set up epoll things, start by getting the FD from RMR if( rcv_fd < 0 ) { fprintf( stderr, " unable to set up polling fd\\n" ); @@ -1242,26 +1242,26 @@ retry handling. } epe.events = EPOLLIN; epe.data.fd = rcv_fd; - + if( epoll_ctl( ep_fd, EPOLL_CTL_ADD, rcv_fd, &epe ) != 0 ) { fprintf( stderr, "[FAIL] epoll_ctl status not 0 : %s\\n", strerror( errno ) ); exit( 1 ); } - + sbuf = rmr_alloc_msg( mrc, 256 ); // alloc 1st send buf; subsequent bufs alloc on send rbuf = NULL; // don't need to alloc receive buffer - + while( ! rmr_ready( mrc ) ) { // must have route table sleep( 1 ); // wait til we get one } fprintf( stderr, " rmr is ready\\n" ); - - + + while( 1 ) { // send messages until the cows come home snprintf( sbuf->payload, 200, "count=%d received= %d ts=%lld %d stand up and cheer!", // create the payload count, rcvd_count, (long long) time( NULL ), rand() ); - + sbuf->mtype = mtype; // fill in the message bits sbuf->len = strlen( sbuf->payload ) + 1; // send full ascii-z string sbuf->state = 0; @@ -1270,7 +1270,7 @@ retry handling. sbuf = rmr_send_msg( mrc, sbuf ); // w/ simple spin that doesn't give up } count++; - + // check to see if anything was received and pull all messages in while( (nready = epoll_wait( ep_fd, events, 1, 0 )) > 0 ) { // 0 is non-blocking if( events[0].data.fd == rcv_fd ) { // waiting on 1 thing, so [0] is ok @@ -1281,40 +1281,40 @@ retry handling. } } } - + if( (count % stats_freq) == 0 ) { // occasional stats out to tty fprintf( stderr, " sent %d received %d\\n", count, rcvd_count ); } - + usleep( delay ); } } - - + + Receiver Sample --------------- -The receiver code is even simpler than the sender code as it -does not need to wait for a route table to arrive (only -senders need to do that), nor does it need to allocate an -initial buffer. The example assumes that the sender is -transmitting a zero terminated string as the payload. - - -:: - - +The receiver code is even simpler than the sender code as it +does not need to wait for a route table to arrive (only +senders need to do that), nor does it need to allocate an +initial buffer. The example assumes that the sender is +transmitting a zero terminated string as the payload. + + +:: + + #include #include #include #include #include - + #include - - + + int main( int argc, char** argv ) { void* mrc; // msg router context long long total = 0; @@ -1325,7 +1325,7 @@ transmitting a zero terminated string as the payload. long long count = 0; long long bad = 0; long long empty = 0; - + if( argc > 1 ) { listen_port = argv[1]; } @@ -1334,22 +1334,22 @@ transmitting a zero terminated string as the payload. } fprintf( stderr, " listening on port: %s\\n", listen_port ); fprintf( stderr, " stats will be reported every %d messages\\n", stat_freq ); - + mrc = rmr_init( listen_port, RMR_MAX_RCV_BYTES, RMRFL_NONE ); if( mrc == NULL ) { fprintf( stderr, " ABORT: unable to initialise RMr\\n" ); exit( 1 ); } - + while( ! rmr_ready( mrc ) ) { // wait for RMR to get a route table fprintf( stderr, " waiting for ready\\n" ); sleep( 3 ); } fprintf( stderr, " rmr now shows ready\\n" ); - + while( 1 ) { // receive until killed msg = rmr_rcv_msg( mrc, msg ); // block until one arrives - + if( msg ) { if( msg->state == RMR_OK ) { count++; // nothing fancy, just count @@ -1359,67 +1359,67 @@ transmitting a zero terminated string as the payload. } else { empty++; } - + if( (count % stat_freq) == 0 ) { fprintf( stderr, " total received: %lld; errors: %lld; empty: %lld\\n", count, bad, empty ); } } } - - + + Receive and Send Sample ----------------------- -The following code snippet receives messages and responds to -the sender if the message type is odd. The code illustrates -how the received message may be used to return a message to -the source. Variable type definitions are omitted for clarity -and should be obvious. - -It should also be noted that things like the message type -which id returned to the sender (99) is a random value that -these applications would have agreed on in advance and is -**not** an RMR definition. - - -:: - +The following code snippet receives messages and responds to +the sender if the message type is odd. The code illustrates +how the received message may be used to return a message to +the source. Variable type definitions are omitted for clarity +and should be obvious. + +It should also be noted that things like the message type +which id returned to the sender (99) is a random value that +these applications would have agreed on in advance and is +**not** an RMR definition. + + +:: + mrc = rmr_init( listen_port, MAX_BUF_SZ, RMRFL_NOFLAGS ); rmr_set_stimeout( mrc, 1 ); // allow RMR to retry failed sends for ~1ms - + while( ! rmr_ready( mrc ) ) { // we send, therefore we need a route table sleep( 1 ); } - + mbuf = NULL; // ensure our buffer pointer is nil for 1st call - + while( TRUE ) { mbuf = rmr_rcv_msg( mrc, mbuf ); // wait for message - + if( mbuf == NULL || mbuf->state != RMR_OK ) { break; } - + if( mbuf->mtype % 2 ) { // respond to odd message types plen = rmr_payload_size( mbuf ); // max size - + // reset necessary fields in msg mbuf->mtype = 99; // response type mbuf->sub_id = RMR_VOID_SUBID; // we turn subid off mbuf->len = snprintf( mbuf->payload, plen, "pong: %s", get_info() ); - + mbuf = rmr_rts_msg( mrc, mbuf ); // return to sender if( mbuf == NULL || mbuf->state != RMR_OK ) { fprintf( stderr, "return to sender failed\\n" ); } } } - + fprintf( stderr, "abort: receive failure\\n" ); rmr_close( mrc ); - - - + + + diff --git a/src/rmr/si/src/si95/siconnect.c b/src/rmr/si/src/si95/siconnect.c index 77dce63..ad5135d 100644 --- a/src/rmr/si/src/si95/siconnect.c +++ b/src/rmr/si/src/si95/siconnect.c @@ -131,14 +131,12 @@ extern int SIconnect( struct ginfo_blk *gptr, char *abuf ) { errno = 0; if( tpptr->flags & TPF_SAFEC ) { if( safe_connect( tpptr->fd, taddr, tpptr->palen ) != 0 ) { // fd closed on failure - SItrash( TP_BLK, tpptr ); tpptr->fd = -1; } } else { if( CONNECT( tpptr->fd, taddr, tpptr->palen ) != 0 ) { CLOSE( tpptr->fd ); // clean up fd and tp_block tpptr->fd = -1; - SItrash( TP_BLK, tpptr ); // free the trasnsport block } } @@ -152,6 +150,8 @@ extern int SIconnect( struct ginfo_blk *gptr, char *abuf ) { gptr->tplist = tpptr; // point at new head fd = tpptr->fd; // save for return value SImap_fd( gptr, fd, tpptr ); + } else { + SItrash( TP_BLK, tpptr ); // free the trasnsport block } } -- 2.16.6