if( NOT EXISTS ${tfm} ) # not yet built here, pull and build
# pull and build {X}fm tools needed to generate manpages
execute_process(
- COMMAND "bash" "-c" "git clone https://github.com/ScottDaniels/xfm.git && cd xfm && mkdir .build && cd .build && cmake .. && make"
+ COMMAND "bash" "-c" "git clone https://gitlab.com/rouxware/xfm.git && cd xfm && mkdir .build && cd .build && cmake .. && make"
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
)
message( "+++ xfm pulled and built" )
rmr_get_xact.3
rmr_init.3
rmr_init_trace.3
- rmr_mt_call.3
+ rmr_mt_call.3
rmr_mt_rcv.3
rmr_payload_size.3
rmr_rcv_msg.3
# for each source, build a specific command that runs tfm to generate the
# troff output as a gzipped file. Sed is needed to remove the leading blank
# that tfm likes to insert even if indention is 0. We also generate postscript
- # markdown, plain ascii and rts output which are left in the build directory
+ # markdown, plain ascii and rts output which are left in the build directory
# for the developer to use as needed.
#
foreach( nm IN LISTS man_names )
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
.dh 3 f=&bold_font p=10 s=1,0 m=.5i i=0i
.dv comment .** ignore
-
+
.dv h1 .h1 $1
.dv h2 .h2 $1
.dv h3 .h3 $1
-
- .dv fig
+
+ .dv fig .fg $1
+ .dv fig_ce .fg x=center $1
.dv set_font_cw .sf ^&cw_font
-
+
.dv nf .nf
.dv fo .fo
.dv center_start .bc start
.dv center_end .bc end
-
+
.dv line_len .ll $1 .dv cn_line_len $1 ^:
.dv space .sp 1
+ .dv break .br
.dv mult_space .sp $1
.dv half_space .sp .5
- .dv beg_list .bl $1
+ .dv beg_list .bl ${1!n}
.dv end_list .el
.dv lic1 n
.dv lic2 m
.dv lic3 l
+ .dv li .cc 2 .li
+ .dv li_sp .cc 2 .sp .5 .li
+ .dv item .cc 2 .li
.dv beg_dlist .bd $1 $2
.dv end_dlist .ed
- .dv ditem .cc 2 .sp .5 .di $1 ^:
- .dv di .cc 2 .sp .5 .di $1 ^:
- .dv li .cc 2 .sp .5 .li
- .dv item .cc 2 .li
-
+ .dv ditem .sp .5 .cc 2 .di $1 ^:
+ .dv ditem_nosp .cc 2 .di $1 ^:
+
+ .** these are deprecated, but must be supported til doc cleaned up
+ .dv di .sp .5 .cc 2 .di $1 ^:
+ .dv diitem .sp .5 .cc 2 .di $1 ^:
+
.dv proto_start .sp 1 .cc .5i .st 9 .sf Courier-bold .nf
.dv proto_end .fo on .sf ^&text_font .st ^&text_size .sp .3
.dv ex_start .sp .5 .st ^&ex_size .sf ^&cw_font .nf
.dv ex_end .fo on .sf ^&text_font .st ^&text_size .sp 1
-
+ .dv ex_end_fig .fo on .sf ^&text_font .st ^&text_size .sp 1 .fg $1 ^: .sp 1
+ .dv ex_end_cfig .fo on .sf ^&text_font .st ^&text_size .sp 1 .fg x=center $1 ^: .sp 1
+
.** fonts and font macros
.dv ital .tf ^&ital_font ^&text_size $1 ^:
.dv bold .tf ^&bold_font ^&text_size $1 ^:
.dv cw .tf ^&cw_font ^&text_size $1 ^:
.dv set_font_prop .sf ^&text_font
-
- .cd 1 6.0i
+
+ .cd 1 6.0i i=0i
.ll 6i
.pn off
.ju on
.in .5i
.dv cn_indent .5i
.dv cn_line_len 6i
-
+
.dv indent .ll -0.5i .in +0.25i
.dv uindent .in -0.25i .ll +0.5i
.dv ss_num 1
.dv note .dv ss_num ^[ ?%.0f ^&ss_num 1 + ] ^: .sm .tf superscript /2 ^&{ss_num} ^:
.dv atbot atbot
+
+ .** ---- table support -------------------
+ .dv beg_table .ta $2
+ .dv beg_table_nb .ta $2 b=0
+ .dv row .tr
+ .dv col .cl
+ .dv end_table .et
--- /dev/null
+.if false
+==================================================================================
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+==================================================================================
+.fi
+
+.if false
+ Mnemonic: html.im
+ Abstract: Imbed when output type is html. Defines macros which generate
+ things from an HTML/hfm point of view.
+
+ Author: E. Scott Daniels
+ Date: 11 May 2020
+
+.fi
+
+.cd 1 6.5i i=0
+.in .25i
+
+.** paragraph headers
+.dv h1 .h1 $1
+.dv h2 .h2 $1
+.dv h3 .h3 $1
+.dv h4 .h4 $1
+
+.dh 1 s=2,1 i=.25i m=.25i
+.dh 2 s=1,1 i=.25i m=.25i
+.dh 3 s=1,0 i=.25i m=.25i
+.hn off
+
+.dv fig .fg t=figure $1
+.dv set_font_cw
+
+.dv nf .sp 1 ^:^: .br .ll -2 .in +2
+.dv fo .in -2 .ll +2 .sp 1
+
+.dv indent .bl
+.dv uindent .el
+
+.dv lic1 *
+.dv lic2 +
+.dv lic3 -
+
+.dv esc : .** rst needs an escape for some things
+
+.dv line_len .ll $1
+.dv space .sp 1
+.dv mult_space .sp $1
+.dv half_space .sp 1
+.dv beg_list .bl $1
+.dv end_list .el
+.dv li .li
+.dv item .li
+
+.dv beg_dlist .sp 1 .bd $1
+.dv end_dlist .ed
+
+.dv center .ce $1 ^:
+.dv center_start .bc start
+.dv center_end .bc end
+
+.** for now we allow only a single layer of defitems
+.dv di .di $1 ^:
+.dv diitem .di $1 ^:
+.dv ditem .di $1 ^:
+.dv ditem_nosp .di $1 ^:
+.dv item .li
+
+.dv ex_start .ll -2 .in +2 .nf
+.dv ex_end .fo on .in -2 .ll +2
+.dv ex_end_fig .fo on .in -2 .ll +2 .fg $1 ^: .sp 1
+.dv ex_end_cfig .fo on .in -2 .ll +2 .fg x=center $1 ^: .sp 1
+
+.dv proto_start .sp 1 .cc .5i .st 9 .sf Courier-bold .nf
+.dv proto_end .fo on .sf ^&text_font .st ^&text_size .sp .3
+
+.dv cw ^<tt^>$1^</tt^>
+.dv Bold ^.st ^[ ^&textsize 4 + ] ^<b^>$1^</b^> .st ^&textsize
+.dv bold ^<b^>$1^</b^>
+.dv ital ^<i^>$1^</i^>
+.dv super ^<sup^>$1^</sup^>
+
+.dv set_font_prop
+
+.dv table .ta $1
+.dv tab_cell .cl
+.dv tab_row .tr
+.dv end_table .et
+
+.** .dv super .sm ^[ .sm ^&{ss_num}]
+.dv ss_num 1
+.dv note .dv ss_num ^[ ?%.0f ^&ss_num 1 + ] ^: .sm ^^[^&{ss_num}]
+.** html has no concept of a page, so all notes go to the close of the doc
+.dv atbot atclose
+.ju on
+
+.dv beg_table .ta $1
+.dv beg_table_nb .ta $1 b=0
+.dv row .tr
+.dv col .cl
+
-#==================================================================================
-# Copyright (c) 2019 Nokia
-# Copyright (c) 2018-2019 AT&T Intellectual Property.
+#=================================================================================2
+# Copyright (c) 2019-2020 Nokia
+# Copyright (c) 2018-2020 AT&T Intellectual Property.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# limitations under the License.
#==================================================================================
-# most things here require a two pass build, but these might be useful
+XP = XFM_PATH=".:.."
+P1 = $(XP) XFM_PASS=1
+P2 = $(XP) XFM_PASS=2
+# ----- generics --------------------------------------------------------
+# two pass builds in order to forward reference variables for figures and to insert
+# table of contents in postscript output
+#
%.ps: %.xfm
- pfm $< $@
+ $(P1) pfm $< /dev/null
+ $(P2) pfm $< $@
%.md: %.xfm
- OUTPUT_TYPE=markdown tfm $< stdout | sed 's/^ //' >$@
+ $(P1) OUTPUT_TYPE=markdown tfm $< /dev/null
+ $(P2) OUTPUT_TYPE=markdown tfm $< stdout | sed 's/^ //' >$@
%.rst: %.xfm
- OUTPUT_TYPE=rst tfm $< stdout | sed 's/^ //' >$@
+ $(P1) OUTPUT_TYPE=rst tfm $< /dev/null
+ $(P2) OUTPUT_TYPE=rst tfm $< stdout | sed 's/^ //' >$@
%.txt: %.xfm
- OUTPUT_TYPE=txt tfm $< stdout
- OUTPUT_TYPE=txt tfm $< $@
+ $(P1) OUTPUT_TYPE=txt tfm $< /dev/null
+ $(P2) OUTPUT_TYPE=txt tfm $< $@
+
+%.html: %.xfm
+ $(P1) OUTPUT_TYPE=html hfm $< /dev/null
+ $(P2) OUTPUT_TYPE=html hfm $< $@
%.pdf: %.ps
gs -dQUIET -dBATCH -dNOPAUSE -sDEVICE=pdfwrite -sOutputFile=$@ $<
-src = user.xfm advanced_use.im api_qref.im code_appendix.im code_send.im config.im failures.im general_use.im glossary.im index_snatch.im setup.im mbuf.im front_junk.im license.im
+# ----- lists --------------------------------------------------------
+# source common to all documents
+common_src = index_snatch.im setup.im mbuf.im front_junk.im license.im
+
+user_src = user.xfm advanced_use.im api_qref.im code_appendix.im code_send.im \
+ config.im failures.im general_use.im glossary.im
+
+# user guide code examples
code_src = $(shell ls code_*.im)
-all: user.pdf user.txt user.rst user.md
+rt_src = rt_tables.xfm
+
+# output types for different builds
+all_types = pdf md rst txt html
+rtd_types = rst
+
-# two pass build for pfm to allow for toc insertion
-user.ps: $(src) $(code_src)
- XFM_PASS=1 pfm $< /dev/null
- XFM_PASS=2 pfm $< $@
+# ------ rules --------------------------------------------------------
+all: $(all_types:%=user.%) $(all_types:%=rt_tables.%)
+ mv user.rst user-guide.rst
-user.md: $(src) $(code_src)
- OUTPUT_TYPE=markdown XFM_PASS=1 tfm $< /dev/null
- OUTPUT_TYPE=markdown XFM_PASS=2 tfm $< | sed 's/^ //' >$@
+# just the things which are pushed to the docs scraper dirctory,
+# renames to expected filenames where required.
+docs: $(rtd_types:%=user.%) $(rtd_types:%=rt_tables.%)
+ mv user.rst user-guide.rst
-user.rst: $(src) $(code_src)
- OUTPUT_TYPE=rst XFM_PASS=1 tfm $< /dev/null
- GEN_TITLE=1 OUTPUT_TYPE=rst XFM_PASS=2 tfm $< | sed 's/^ //' >$@
+# dependencies; actual recipes are generic
+$(all_types:%=user.%): $(user_src) $(code_src) $(common_src)
+$(all_types:%=rt_tables.%): $(rt_src) $(common_src)
-user.txt: $(src) $(code_src)
- OUTPUT_TYPE=txt XFM_PASS=1 tfm $< /dev/null
- OUTPUT_TYPE=txt XFM_PASS=2 tfm $< $@
-# intermeidate junk that might straggle
+# ---------- housekeeping ----------------------------------------------
+# remove only intermeidate junk that might straggle; leave output
clean:
- rm -fr *.bcnfile *.ca *.ecnfile
+ rm -fr *.bcnfile *.ca *.ecnfile *.sp *.toc
-# Anything that can be built
+# Remove anything that can be built
nuke: clean
- rm -fr *.ps *.pdf *.txt *.rst
+ rm -fr *.ps *.pdf *.txt *.rst *.md *.html
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
&h2(The Call Function)
The RMR function &func(rmr_call) sends a message in the exact same
-manner as the &cw(rmr_send_msg()) function, with the endpoint
+manner as the &func(rmr_send_msg()) function, with the endpoint
selection based on the message key. But unlike the send function,
&func(rmr_call) will block and wait for a response from the
application that is selected to receive the message. The matching
the response.
&h3(Multi-threaded Calls)
-
The basic call mechanism described above is &bold(not) thread safe, as
it is not possible to guarantee that a response message is delivered
to the correct thread. The RMR function &func(rmr_mt_call) accepts an
ensure that the response is delivered properly. In addition, the
application must specifically initialise the multi-threaded call
environment by passing the &cw(RMRFL_MTCALL) flag as an option to the
-&func(rmr_init) function ¬e .sm .
-.if pfm
-.dv cnopts l=&cn_line_len i=&cn_indent
-.dv cncmd .cn start &cnopts &atbot Times-roman 8p .7i
-.ei
-.dv cncmd .cn start &atbot Times-roman 8p .7i
-.fi
-
-&cncmd
- There is additional overhead to support multi-threaded call as
- a special listener thread must be used in order to deliver
- responses to the proper application thread.
-.cn end
+&func(rmr_init) function.
&space
One advantage of the multi-threaded call capability in RMR is the fact
receive messages across the connection. The following are the RMR
functions which provide wormhole communications:
-&space
+&half_space
&indent
&beg_dlist( 1i Helvetica )
- &di(rmr_wh_open) Open a connection to an endpoint. Name or IP
+ &ditem(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.
- &half_space
- &di(rmr_wh_send_msg) Sends an RMR message buffer to the
+ &ditem(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.
- &half_space
- &di(rmr_wh_close) Closes the direct connection.
+ &ditem(rmr_wh_close) Closes the direct connection.
&end_dlist
&uindent
&space
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
the state set to &cw(RMR_ERR_TIMEOUT.)
&proto_start
-rmr_mbuf_t* rmr_tralloc_msg( void* context, int msize, int trsize, unsigned const char* data );
+rmr_mbuf_t* rmr_tralloc_msg( void* context, int msize, int trsize,
+ unsigned const char* data );
&proto_end
Similar to the &func(rmr_alloc_msg) this function allocates a message
buffer, and adds the referenced trace data to the buffer. The new
This function closes an existing wormhole connection.
&proto_start
-extern rmr_mbuf_t* rmr_wh_call( void* vctx, rmr_whid_t whid, rmr_mbuf_t* msg, int call_id, int max_wait );
+extern rmr_mbuf_t* rmr_wh_call( void* vctx, rmr_whid_t whid, rmr_mbuf_t* msg,
+ int call_id, int max_wait );
&proto_end
-This provides the same synchronous &ital(procedure call) as the &cw(rmr_call()) function
+This provides the same synchronous &ital(procedure call) as the &func(rmr_call()) function
provides, excerpt that the message is sent to a specific endpoint as defined by an
open wormhole.
buffer is returned.
&proto_start
-extern rmr_mbuf_t* rmr_realloc_payload( rmr_mbuf_t* old_msg, int new_len, int copy, int clone );
+extern rmr_mbuf_t* rmr_realloc_payload( rmr_mbuf_t* old_msg, int new_len,
+ int copy, int clone );
&proto_end
This function allows the user programme to realloc the payload with a
larger length.
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
==================================================================================
.fi
-.** example sender code
+.** example sender code is pulled directly from the exaple directory
&h2(Receiver Sample)
The receiver code is even simpler than the sender code as it does not
&space
-&indent
&ex_start
-rmr_mbuf_t* rbuf = NULL;
-void* mrc = rmr_init( listen_port, MAX_BUF_SZ, RMRFL_NOFLAGS );
-
-while( TRUE ) {
- rbuf = rmr_rcv_msg( mrc, rbuf ); // reuse buffer on all but first loop
- if( rbuf == NULL || rbuf->state != RMR_OK ) {
- break;
- }
-
- fprintf( stdout, "mtype=%d sid=%d pay=%s\n",
- rbuf->mtype, rbuf->sub_id, rbuf->payload );
- sleep( delay_sec );
-}
-
-fprintf( stderr, "receive error\n" );
-rmr_close( mrc );
-
+.im j=start_example ../../../examples/receiver.c
&ex_end
-&uindent
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
==================================================================================
.fi
-.** example sender code
+.** example sender code is included directly from the examples directory
&h2(Sender Sample)
The following code segment shows how a message buffer can be
message. It does not illustrate error and/or retry handling.
&space
-&indent
&ex_start
-mrc = rmr_init( listen_port, MAX_BUF_SZ, RMRFL_NOFLAGS );
-rmr_set_stimeout( mrc, rmr_retries );
-
-while( ! rmr_ready( mrc ) ) {
- sleep( 1 );
-}
-
-sbuf = rmr_alloc_msg( mrc, 256 ); // 1st send buffer
-
-while( TRUE ) {
- sbuf->len = gen_status( (status_msg *) sbuf->payload );
- sbuf->mtype = STATUS_MSG;
- sbuf->sub_id = RMR_VOID_SUBID; // subscription not used
- sbuf = rmr_send_msg( mrc, sbuf );
-
- sleep( delay_sec );
-}
-
-rmr_close( mrc );
-
+.im j=start_example ../../../examples/sender.c
&ex_end
-&uindent
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
==================================================================================
.fi
-.** example sender code
+.** example combination send/receive loop; no example to pull yet
&h2(Receive and Send Sample)
The following code snippet receives messages and responds to the
which RMR recognises:
&half_space
-.st 8p
&indent
&beg_dlist( 1.25i &ditext )
- &di(RMR_BIND_IF) The interface to bind to listen ports to. If not defined 0.0.0.0 (all interfaces) is assumed.
- &half_space
+ &ditem(RMR_BIND_IF) The interface to bind to listen ports to. If not defined 0.0.0.0 (all interfaces) is assumed.
- &di(RMR_RTG_SVC) The port RMR will listen on for route manager connections. If not defined 4561 is used.
- &half_space
+ &ditem(RMR_RTG_SVC) The port RMR will listen on for route manager connections. If not defined 4561 is used.
- &di(RMR_SEED_RT) Where RMR expects to find the name of the seed (static) route table. If not defined no static table is read.
- &half_space
+ &ditem(RMR_SEED_RT) Where RMR expects to find the name of the seed (static) route table. If not defined no static table is read.
- &di(RMR_RTG_ISRAW) If the value set to 0, RMR expects the route table manager messages to be messages with and RMR header.
+ &ditem(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.
- &half_space
- &di(RMR_VCTL_FILE) Provides a file which is used to set the verbose level of the route table collection thread.
+ &ditem(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.
- &half_space
- &di(RMR_SRC_NAMEONLY) If the value of this variable is greater than 0, RMR will not permit the IP address to be
+ &ditem(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.
&end_dlist
&uindent
&half_space
&indent
&beg_dlist( .6i &ditext )
- &di(^[CRI]) The event is of a critical nature and it is unlikely that RMR will continue to operate correctly if at all.
+ &ditem(^[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.
- &half_space
- &di(^[ERR]) The event is not expected and RMR is not able to handle it. There is a small chance that continued operation
+ &ditem(^[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.
- &half_space
- &di(^[WRN]) The event was not expected by RMR, but can be worked round. Normal operation will continue, but it is recommended
+ &ditem(^[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.
&end_dlist
&space
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
.st 8p
&indent
&beg_dlist( 1.5i &ditext )
- &di(RMR_OK) state is good; operation finished successfully
- &half_space
+ &ditem(RMR_OK) state is good; operation finished successfully
- &di(RMR_ERR_BADARG) argument passed to function was unusable
- &half_space
+ &ditem(RMR_ERR_BADARG) argument passed to function was unusable
- &di(RMR_ERR_NOENDPT) send/call could not find an endpoint based on msg type
- &half_space
+ &ditem(RMR_ERR_NOENDPT) send/call could not find an endpoint based on msg type
- &di(RMR_ERR_EMPTY) msg received had no payload; attempt to send an empty message
- &half_space
+ &ditem(RMR_ERR_EMPTY) msg received had no payload; attempt to send an empty message
- &di(RMR_ERR_NOHDR) message didn't contain a valid header
- &half_space
+ &ditem(RMR_ERR_NOHDR) message didn't contain a valid header
- &di(RMR_ERR_SENDFAILED) send failed; errno may contain the transport provider reason
- &half_space
+ &ditem(RMR_ERR_SENDFAILED) send failed; errno may contain the transport provider reason
- &di(RMR_ERR_CALLFAILED) unable to send the message for a call function; errno may contain the transport provider reason
- &half_space
+ &ditem(RMR_ERR_CALLFAILED) unable to send the message for a call function; errno may contain the transport provider reason
- &di(RMR_ERR_NOWHOPEN) no wormholes are open
- &half_space
+ &ditem(RMR_ERR_NOWHOPEN) no wormholes are open
- &di(RMR_ERR_WHID) the wormhole id provided was invalid
- &half_space
+ &ditem(RMR_ERR_WHID) the wormhole id provided was invalid
- &di(RMR_ERR_OVERFLOW) operation would have busted through a buffer/field size
- &half_space
+ &ditem(RMR_ERR_OVERFLOW) operation would have busted through a buffer/field size
- &di(RMR_ERR_RETRY) request (send/call/rts) failed, but caller should retry (EAGAIN for wrappers)
- &half_space
+ &ditem(RMR_ERR_RETRY) request (send/call/rts) failed, but caller should retry (EAGAIN for wrappers)
- &di(RMR_ERR_RCVFAILED) receive failed (hard error)
- &half_space
+ &ditem(RMR_ERR_RCVFAILED) receive failed (hard error)
- &di(RMR_ERR_TIMEOUT) response message not received in a reasonable amount of time
- &half_space
+ &ditem(RMR_ERR_TIMEOUT) response message not received in a reasonable amount of time
- &di(RMR_ERR_UNSET) the message hasn't been populated with a transport buffer
- &half_space
+ &ditem(RMR_ERR_UNSET) the message hasn't been populated with a transport buffer
- &di(RMR_ERR_TRUNC) length in the received buffer is longer than the size of the allocated payload,
+ &ditem(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)
- &half_space
- &di(RMR_ERR_INITFAILED) initialisation of something (probably message) failed
- &half_space
+ &ditem(RMR_ERR_INITFAILED) initialisation of something (probably message) failed
- &di(RMR_ERR_NOTSUPP) the request is not supported, or RMR was not initialised for the request
+ &ditem(RMR_ERR_NOTSUPP) the request is not supported, or RMR was not initialised for the request
&end_dlist
&uindent
.st &textsize
.fi
.if false
- Title page, toc and license for page oriented output
+ Mnemonic: front_junk.im
+ Abstract: This will generate a title page, table of contents and
+ license/copyright page (between title page and toc).
+ It should only be embedded for postscript output
+
+ For non-postscript output, a simple title is embedded
+ without enabling table of contents, index, etc.
+
+ Expected to be defined before imbedding this:
+ doc_title
+ col_width
+ col_indent
+ pass
+ textfont
+ textsize
+ indent_size
+ toc_file
+
+ Optional vars that are used if set
+ doc_subtitle
+ orig_date
+
+ Date: August 2019
+ Author: E. Scott Daniels
.fi
.if ! _front_junk
-.sp 20
-.st 24
-.bc start
-&doc_title
-.br
-&doc_subtitle
-.bc end
-.st &textsize
-
-.sp 25
-Original: 30 July 2019 .br
-.gv Date
-Revised: &_date
-.pa
-
-
-.im license.im
-.pa
-
-.if &pass 1 =
- .tc on
-.ei
- .tc off
- .pn on noline center roman 0
- .im user.toc .** initial page eject inside
+
+.if pfm
+ .sp 20
+ .st 24
+ .bc start
+ &doc_title
+ .br
+ .if doc_subtitle
+ &doc_subtitle
+ .fi
+ .bc end
+ .st &textsize
+
+ .sp 25
+ .if orig_date
+ Original: &orig_date .br
+ .fi
+ .gv Date
+ Revised: &_date
.pa
+
+
+ .** license/copyright onto the page after the title
+ .im license.im
+ .pa
+
+ .if &pass 1 =
+ .tc on
+ .ei
+ .tc off
+ .pn on noline center roman 0
+
+ .im &toc_file
+ .pa
+ .pn on 0
+ .fi
+
+.ei
+ .if "&ot" "rst" =
+ .** copyright into .rst because it supports internal comments
+ .im license.im
+
+ &many_equals .br
+ &doc_title
+ &many_equals .br
+ .if doc_subtitle
+ &many_dashes .br
+ &doc_subtitle .br
+ &many_dashes .br
+ .fi
+ .ei
+ ¢er_start
+ &doc_title .br
+ .if doc_subtitle
+ &doc_subtitle .br
+ .fi
+ .fi
.fi
-.** ensure this is restored after toc spits
+.** ensure these are restored after toc spits
.if pfm
- .cd 1 6.0i
+ .cd 1 &col_width i=&col_indent
+ .in &indent_size
+ .sf &textfont
+ .st &textsize
.fi
+
.dv _front_junk 1
.fi
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
failure; the application will need to reinitialise with a different
port number, abort, or take some other action appropriate for the
application.
-.sp
+&space
+
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
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.
+&space
-.sp
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 &bold(not) need to be allocated. The
fields, and should set them appropriately.
&half_space
&indent
-&beg_dlist( 1i &ditext )
- &di(len) This is the number of bytes that the application
- placed into the payload. Setting length to 0
+&beg_dlist( 1i &ditext : : 15,80 )
+ &ditem(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.
- &half_space
- &di(mtype) The message type that RMR will use to determine the
- endpoint used as the target of the send.
+ &ditem(mtype) The message type that RMR will use to determine the
+ endpoint used as the target of the send.
- &half_space
- &di(sub_id) The subscription ID if the message is to be routed
- based on the combination of message type and
+ &ditem(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
&cw(RMR_VOID_SUBID.)
- &half_space
- &di(payload) The application should obtain the reference
- (pointer) to the payload from the message
+ &ditem(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 &func(rmr_payload_size:) function.
- &half_space
- &di(trace data) Optionally, the application may add trace
- information to the message buffer.
-
+ &ditem(trace data) Optionally, the application may add trace
+ information to the message buffer.
+
&end_dlist
&space
&uindent
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
.fi
-.dv term ^&half_space ^&di($1)
.ix pause
&h1(Appendix &gloss_appendix -- Glossary)
Many terms in networking can be interpreted with multiple meanings,
-and several terms used in this document are RMR specific. The
-following definitions are the meanings of terms used within this
-document and should help the reader to understand the intent of
+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.
-&beg_dlist( &1.0i Helvetica-bold )
-&term(application) A programme which uses RMR to send and/or receive
+&beg_dlist( &1.0i Helvetica-bold : : 25,70 )
+&ditem(application) A programme which uses RMR to send and/or receive
messages to/from another RMR based application.
-&term(Critical error) An error that RMR has encountered which will
+&ditem(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.
-&term(Endpoint) An RMR based application that is defined as being
+&ditem(Endpoint) An RMR based application that is defined as being
capable of receiving one or more types of
messages (as defined by a &ital(message key.)
.sm )
-&term(Environment variable) A key/value pair which is set externally
+&ditem(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 &cw(getenv) system
method of communicating information such as
port numbers to RMR.
-&term(Error) An abnormal condition that RMR has encountered, but will
+&ditem(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.
-&term(Host name) The name of the host as returned by the
+&ditem(Host name) The name of the host as returned by the
&cw(gethostbyname) system call. In a
containerised environment this might be the
container or service name depending on how the
&ital(endpoint) definition in a &ital(route
table.)
-&term(IP) Internet protocol. A low level transmission protocol
+&ditem(IP) Internet protocol. A low level transmission protocol
which governs the transmission of datagrams
across network boundaries.
-&term(Listen socket) A &ital(TCP) socket used to await incoming
+&ditem(Listen socket) A &ital(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.
-&term(Message) A series of bytes transmitted from the application to
+&ditem(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).
-&term(Message buffer) A data structure used to describe a message
+&ditem(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.
-&term(Messgae type) A signed integer (0-32000) which identifies the
+&ditem(Messgae type) A signed integer (0-32000) which identifies the
type of message being transmitted, and is one
of the two components of a &ital(routing key.)
See &ital(Subscription ID.)
-&term(Payload) The portion of a message which holds the user data to
+&ditem(Payload) The portion of a message which holds the user data to
be transmitted to the remote &ital(endpoint.)
The payload contents are completely
application defined.
-&term(RMR context) A set of information which defines the current
+&ditem(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.
-&term(Round robin) The method of selecting an &ital(endpoint) from a
+&ditem(Round robin) The method of selecting an &ital(endpoint) from a
list such that all &ital(endpoints) are
selected before starting at the head of the list.
-&term(Route table) A series of "rules" which define the possible
- &ital(endpoints) for each &ital(message key.)
+&ditem(Route table) A series of "rules" which define the possible
+ &ital(endpoints) for each &ital(message key.)
-&term(Route table manager) An application responsible for building a
+&ditem(Route table manager) An application responsible for building a
&ital(route table) and then distributing it to
all applicable RMR based applications.
-&term(Routing) The process of selecting an &ital(endpoint) which will
-be the recipient of a message.
+&ditem(Routing) The process of selecting an &ital(endpoint) which will
+ be the recipient of a message.
-&term(Routing key) A combination of &ital(message type) and
+&ditem(Routing key) A combination of &ital(message type) and
&ital(subscription ID) which RMR uses to
select the destination &ital(endpoint) when
sending a message.
-&term(Source) The sender of a message.
+&ditem(Source) The sender of a message.
-&term(Subscription ID) A signed integer value (0-32000) which
+&ditem(Subscription ID) A signed integer value (0-32000) which
identifies the subscription characteristic of
a message. It is used in conjunction with the
&ital(message type) to determine the
&ital(routing key.)
-&term(Target) The &ital(endpoint) selected to receive a message.
+&ditem(Target) The &ital(endpoint) selected to receive a message.
-&term(TCP) Transmission Control Protocol. A connection based
+&ditem(TCP) Transmission Control Protocol. A connection based
internet protocol which provides for lossless
packet transportation, usually over IP.
-&term(Thread) Also called a &ital(process thread, or pthread.) This
+&ditem(Thread) Also called a &ital(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
transaction or application activity across
components. RMR makes no use of this data.
-&term(Transaction ID) A fixed number of bytes in the &ital(message
+&ditem(Transaction ID) A fixed number of bytes in the &ital(message
buffer) which the application may populate
with information related to the
transaction. RMR makes use of the transaction
&c(rmr_call) function is used to send a
message.
-&term(Transient failure) An error state that is believed to be short
+&ditem(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
&cw(EAGAIN.)
-
-&term(Warning) A warning occurs when RMR has encountered something
+
+&ditem(Warning) A warning occurs when RMR has encountered something
that it believes isn't correct, but has a
defined work round.
-&term(Wormhole) A direct connection managed by RMR between the user
+&ditem(Wormhole) A direct connection managed by RMR between the user
application and a remote, RMR based, application.
&end_dlist
==================================================================================
.fi
+.if ! _license_im
.** this file is imbedded after the cover page for Postscript generated
.** documents, and at the top for text based documents. It's purpose is
described in this document, are all governed by the following
copyright statement.
+.** enable lines to match text line length here
+.cd 1 &line_size i=&col_indent
.sp 2
+.lw 1
.ln
-.nf
- Copyright (c) 2019-2020 Nokia
- Copyright (c) 2019-2020 AT&T Intellectual Property.
+.ll -.5i
+.in +.25i
+Copyright (c) 2019-2020 Nokia
+.br
+Copyright (c) 2019-2020 AT&T Intellectual Property.
+.sp 1
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
+.sp 1
+.nf
http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
.fo
+.sp
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+.sp .7
+.in -.25i
+.ll +.5i
.ln
.sp 2
+.cd 1 &col_width i=&col_indent
+
+.dv _license_im 1
.fi
--- /dev/null
+.if false
+==================================================================================
+ Copyright (c) 2020 Nokia
+ Copyright (c) 2020 AT&T Intellectual Property.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+==================================================================================
+.fi
+
+.if false
+ Mnemonic: rt_tables.xfm
+ Abstract: An overview of route tables in RMR.
+ Date: 25 February 2020
+ Author: E. Scott Daniels
+.fi
+
+.** constants
+.dv MT_REQ_TABLE 21
+.dv MT_TABLE_STATE 22
+.dv MT_TABLE_DATA 20
+
+.dv RTMGR ^&ital(Route Manager)
+
+.** -------------------------------------------------------------------------------
+
+.** force setup to generate a title and to reverse title/subtitle for rst docs
+.dv GEN_TITLE 1
+.dv doc_title RIC Message Router -- RMR
+.dv doc_subtitle Route Table Guide
+.dv reverse_titles 1
+
+
+.dv textfont Helvetica
+.dv textsize 10p
+.dv index_snare_file index_snatch.im
+.dv orig_date 30 April 2020
+
+.gv e XFM_PASS pass
+
+.** setup will do the right thing with the index configuration; a common snatch
+.** file is used for all documents in this directory.
+.**
+.dv index_snare_file index_snatch.im
+.im setup.im
+
+
+&line_len( &line_size )
+.** -------------------------------------------------------------------------------
+
+&h1(Overview)
+Messages sent via the RIC Message Router (RMR) are routed to an endpoint (another application)
+based on a combination of the &ital(message type) (MT) and &ital(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 &RTMGR service, or as a static table loaded
+during RMR initialisation.
+It is also possible to route messages directly to an endpoint which is the &ital(managed entity)
+"owner," using the &ital(managed entity ID) (MEID).
+
+&space
+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 &RTMGR service, the need is certainly a requirement.
+This document describes the overall syntax of a route table and the interface between the
+&RTMGR service and RMR.
+
+
+&h1(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.
+.gv fig
+Figure &_fig illustrates a very basic route table with two message types, 1000 and 2000, and two
+subscription IDs for message type 1000.
+&half_space
+
+&ex_start
+ newrt | start | rt-0928
+ rte | 2000 | logger:30311
+ mse | 1000 | 10 | forwarder:43086
+ mse | 1000 | 21 | app0:43086,app1:43086
+ newrt | end | 3
+&ex_end
+&fig(A basic route table.)
+
+
+
+&h2(Entry record syntax)
+Two types of table entries are supported for compatibility with the original RMR implementation, but only the &ital(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:
+&space
+
+&ex_start
+ rte | <msg-type>[,<sender-endpoint>] | <endpoint-group>[;<endpoint-group>;...]
+ mse | <msg-type>[,<sender-endpoint>] | <sub-id> | <endpoint-group>[;<endpoint-group>;...]
+&ex_end
+&space
+
+Where:
+&half_space
+
+&indent
+&beg_dlist( 1i : Helvetica-bold : 25,70 )
+&ditem(mse, rte)
+ is the table entry type
+
+&ditem(<msg-type>)
+ is the integer message type
+
+&ditem(<sender-endpoint>)
+ 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.
+
+&ditem(<sub-id>)
+ is the subscription id (integer) for subscription-based messages, or -1 if the message type is not subscription-based.
+ An &ital(mse) entry with a sub-id of -1 is the &bold(same) as an &ital(rte) entry with the same message type.
+
+&ditem(<endpoint-group>)
+ is one or more, comma separated, endpoint descriptions.
+&end_dlist
+&uindent
+&space
+
+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.
+
+&h3(Line separation)
+Table entries &bold(must) end with a record termination sequence which may be one of the following
+three sequences:
+&half_space
+&indent
+&beg_list(&lic1)
+&li a single newline (&{backslant}n)
+&li a DOS style CRLF pair (&{backslant}r&{backslant}n)
+&li a single carriage return (&{backslant}r)
+&end_list
+&uindent
+
+&space
+
+Care must be taken when manually editing a static table; some editors do &bold(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).
+
+&h2(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 &ital(newrt) record.
+Each &ital(newrt) record has one of two possible syntax layouts as described below.
+
+&half_space
+&ex_start
+ newrt | begin [| table-id-string]
+ newrt | end [| record-count]
+&ex_end
+&fig(Illustration of the newrt records in the table.)
+&space
+
+The &ital(table-id-string) is an optional string which is used by RMR when sending an acknowledgement
+back to the &RTMGR service (see the &ital(Route Manager Interface) section for more details).
+If a &ital(record-count) is given as the final field on the &ital(end) record, RMR will verify that the
+number of &ital(mse) and &ital(rte) entries in the table matches the count; if there is a mismatch in
+values the table is not used.
+
+
+&h2(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.
+
+&space
+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.
+
+
+&h2(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).
+
+
+&h1(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.
+
+.cc 20
+
+&space
+&beg_table_nb( 75,10 : 4.5i .3i)
+&row
+&ex_start
+ 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
+&ex_end
+&col
+&ex_start
+(1)
+(2)
+(3)
+(4)
+(5)
+(6)
+&ex_end
+&end_table
+
+.gv fig
+.dv table_fig &_fig
+&fig( A complete RMR routing table (line numbers to the right for reference). )
+
+&h2(Table Entry Ordering)
+Whether a table is read from a file on disk, or is received from a &RTMGR 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.
+&space
+
+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 &bold(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.
+&space
+
+Using the table in figure &table_fig 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 &ital(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.
+
+&space
+As a rule, the ordering of entries for a given MT/SID pair should be from most generic to
+most specific.
+
+
+
+&h1(Route Manager Communications)
+During initialisation RMR will use the value of the &cw(RMR_RTG_SVC) environment variable to
+connect to the &RTMGR service in order to request a route table.
+The connection between RMR and the &RTMGR is also an RMR session and thus
+RMR messages will be used to exchange requests and responses.
+
+&h2(Table Request)
+During initialisation, RMR will establish a wormhole connection to the &RTMGR and sends
+a message type of &MT_REQ_TABLE 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 &RTMGR to ignore the requests if it is not ready to respond.
+
+&h2(Sending Tables To RMR)
+Table entry data is expected to arrive via RMR message with a message type of &MT_TABLE_DATA.
+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.
+
+&h2(Table Acceptance and Acknowledgement)
+When RMR receives the table end entry (newrt|end), it will send a state message back to
+the &RTMGR to indicate the state of the received table.
+The message type is &MT_TABLE_STATE and the payload will contain UTF-8 tokens which indicate the state.
+The second token will be the &ital(table ID) supplied on the start record, or the string "<id-missing>."
+When the state is an error state, RMR might add a final set of tokens which contain the reason
+for the failure.
+&space
+
+Upon receipt of a status message which indicates an "OK" response, the &RTMGR 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.
+
+
+
+
+&h1(Providing A Static Table)
+For testing, or possibly bootstrapping purposes, a static route table can be supplied.
+During initialisation, RMR will check the &cw(RMR_SEED_RT) environment variable.
+If it exists, and references a file, RMR will open and read the file expecting to find
+a static route table.
+This route table is used until an update is received from a &RTMGR.
+Normally, when the RMR initialisation function is invoked, a listener is started to receive route table information from a route
+manager process.
+During testing it is often useful to supply a static table which is available should no route management process exist,
+or to provide a seed table to use before the first table is delivered.
+The environment variable &cw(RMR_SEED_RT) can be set to provide the RMR initialisation function with the name
+of the static table to use.
+If a static table is provided, it will be loaded only once, and will be overlaid if
+a dynamically delivered table is received.
+
+
+
+&h1(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 &ital(owns,) or is responsible for the managed entity.
+Should the &ital(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 &cw(%meid)
+instead of providing a round robin list.
+As an example, consider the following route table entry:
+&space
+
+&ex_start
+ mse| 1000,forwarder:43086 | 10 | %meid
+&ex_end
+&fig( Sample route entry with the meid flag.)
+&space
+
+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.
+
+
+
+&h2(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 &RTMGR over the same communication path as the route
+table is supplied.
+The following is the syntax for an MEID map.
+&half_space
+
+
+&ex_start
+ meid_map | start | <table-id>
+ mme_ar | <owner-endpoint> | <meid> [<meid>...]
+ mme_del | <meid> [<meid>...]
+ meid_map | end | <count> [| <md5sum> ]
+&ex_end
+&fig( Meid map table.)
+&space
+
+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 <owner-endpoint> 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 <count> is the number of add/replace and delete records which were sent; if RMR does not match the <count> 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 &RTMGR does not need to supply
+all of the MEID relationships with each update.
+&space
+
+The optional <md5sum> 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.
+&space
+
+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:
+&half_space
+
+&ex_start
+ 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
+&ex_end
+&fig( Illustration of both a route table and meid map in the same file. )
+&space
+
+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.
+
+
+&h1(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.
+
+.** -- appendices ------------------------------
+
+.dv gloss_appendix A
+.pa
+.im glossary.im
+
+.** ----------- end housekeeping ---------------
+
+.** if pfm and index was setup, include it now
+.if index_here
+ .st 8p
+ &index_here
+ .st &textsize
+.fi
+.pa
+
+.** capture all interesting variables to be used as forward references during pass 2
+.ca expand start p1var_setup.ca
+ .** pass 1 variable settings -- do NOT commit to repo
+
+ .** set vars which need to be referenced prior to use, for example:
+ .** .dv qr_appendix &qr_appendix
+.ca end
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
Mnemonic: setup.im
Abstract: Look at environment variables and pull in the correct setup prep
imbed file based on the desired output type (when running tfm).
- Obviously, when running pfm we are always generating postscript
- so this isn't really doing much.
+
+ This also sets up the front junk (table of contents, copyright page
+ and page numbering) when generating postscript. For non-postscript
+ output a licence/caution are added if the output type supports
+ comments. Document title is also added.
+
+ These variables are expected to be defined:
+ pass (current parsing pass over the source)
+
+ See front_junk.im for the list of variables it expects.
+
Date: 29 July 2019
.fi
+.if ! _setup_im
+
.gv e LIB lib
.if ! lib
.dv lib ..
.fi
-.** sane default for everything except rst
+.if ! ot
+ .gv e OUTPUT_TYPE ot
+.fi
+
+.** sane default for everything except rst and markdown which override later
.dv col_width 6.5i
+.dv col_indent .75i
+.dv indent_size .5i
+.dv line_size 6i
+.hn off
+.dv col_width 7i
-.** CAUTION: xfm comparisons are reverse polish so "a b =" is true if a == b.
+
+.** for everything except rst backslants don't need to be escaped
+.dv backslant \
+
+.dv ditext Helvetica-bold
.if pfm
.im &{lib}/generic_ps.im
+ .dv lic1 n
+ .dv lic2 m
.ei
+ .dv lic1 *
+ .dv lic2 +
+
.gv e OUTPUT_TYPE ot
+ .** CAUTION: xfm comparisons are reverse polish so "a b =" is true if a == b.
.if "&ot" "txt" =
.im &{lib}/txt.im
.fi
.if "&ot" "rst" =
- .** bleeding rst needs bullet lists to have no line breaks
- .dv col_width 20i
+ .dv backslant \\
+ .if &reverse_titles 1 =
+ .** for some RST output reversing disambiguates the generated document list
+ .dv _hold &doc_title
+ .dv doc_title &doc_subtitle
+ .dv doc_subtitle &_hold
+ .fi
+
+ .dv col_indent 0i
+ .dv indent_size 0i
.im &{lib}/rst.im
.fi
.if "&ot" "markdown" =
+ .dv col_indent 0i
+ .dv indent_size 0i
.im &{lib}/markdown.im
.fi
.if "&ot" "troff" =
.im &{lib}/roff.im
.fi
+ .if "&ot" "html" =
+ .im &{lib}/html.im
+ .fi
.fi
+.** do not force header level 1s to all upper case
+.dh 1 u=off
+
+.cd 1 &col_width i=&col_indent
+.in &indent_size
+.ll &line_size
+
.** set up for an index when using pfm and snare file is defined
.if pfm
.if index_snare_file
.fi
.fi
+.if &pass 2 =
+ .** two pass mode -- pull in variables captured during pass 1 for forward references
+ .im p1var_setup.ca
+.ei
+ .** clear the capture file if it was there (end must be in col 0)
+ .ca start p1var_setup.ca
+.ca end
+.fi
+
+.gv e GEN_TITLE gen_title
+.if "&gen_title" "1" =
+ .im ../rtd/gen_title.im
+.fi
+
+
+.** func allows us to force an index entry for the function without having to
+.** define function names in the capture file. func is a bit odd; if punct
+.** needs to be added, it must be supplied as the second .** parm because
+.** we add () to the first. E.g. &func(foo_bar:.) will add a full stop.
+.**
+.if pfm
+ .dv func .ix force ${1} ^: ^&cw(${1}()$2 )
+.ei
+ .dv func ^&cw(${1}()$2)
+.fi
+
+.** license/copyright, table of contents, title page, start index capture
+.im front_junk.im
+
+.if pfm
+ .** page numbering
+ .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
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
Author: E. Scott Daniels
.fi
+.dv textfont Helvetica
+.dv textsize 10p
+.gv e XFM_PASS pass
+
+.** vars picked up by front_junk or gen_title as it's a generic module
+.dv doc_title RIC Message Router -- RMR
+.dv doc_subtitle User's Guide
+.dv orig_date 30 July 2019
+.** must reverse titles when generating rst to disambiguate in the doc list
+.dv reverse_titles 1
+
.** setup will do the right thing with the index configuration
.dv index_snare_file index_snatch.im
.im ./setup.im
-.** func is a bit odd; if punct needs to be added, it must be supplied as the second
-.** parm because we add () to the first. E.g. &func(foo_bar:.) will add a parm
-.**
-.dv func .ix force ${1} ^: ^&cw(${1}()$2 )
-
.dv mtsid message type and subscription ID
.dv Mtsid Message type and subscription ID
.dv mt message type
.dv Mt Message type
.dv mts message types
-.dv textfont Helvetica
-.dv textsize 10p
-.hn off
-
-
-.gv e XFM_PASS pass
-.if &pass 2 =
- .** two pass mode -- pull in variables captured during pass 1 for forward references
- .im p1var_setup.ca
-.fi
-
-.if pfm
- .** add licence, a title page, and table of contents
- .im front_junk.im
-.ei
- .** for text based things, nothing more than license
- .im license.im
-.fi
-
-.** vars picked up by gen_title as it's a generic module
-.dv doc_title RIC Message Router -- RMR
-.dv doc_subtitle User's Manual
-
-.gv e GEN_TITLE gen_title
-.if "&gen_title" "1" =
- .im ../rtd/gen_title.im
-.fi
-
-.if pfm
- .pn on noline center f=%d 0
-.fi
-
.** --------------------------------------------------------------------------------------
+&line_len( &line_size )
&h1(Overview)
The RIC Message Router (RMR) is a library for peer-to-peer
.if tfm
.** show all column/foot notes
+ &h1(Notes)
.cn showend
&mult_space( 3 )
.fi
.pa
.if "&ot" "rst" =
&h1(Appendix &qr_appendix -- Quick Reference)
-Please refer to the RMR manual pages on the Read the Docs site
-&space
-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
+ &space
+ https://docs.o-ran-sc.org/projects/o-ran-sc-ric-plt-lib-rmr/en/latest/index.html
.ei
-.im api_qref.im
+ .im api_qref.im
.fi
.dv mbuf_appendix B
.** vim: ts=4 noet sw=42
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
.fi
+&indent
&beg_dlist(.75i : ^&bold_font )
&ditem(RMR_ASYNC_CONN) Allows the async connection mode to be turned off (by setting the
value to 0). When set to 1, or missing from the environment, RMR will invoke the
mode. This will likely result in many "soft failures" (retry) until the connection
is established, but allows the application to continue unimpeded should the
connection be slow to set up.
- &half_space
&ditem(RMR_BIND_IF) This provides the interface that RMR will bind listen ports to, allowing
for a single interface to be used rather than listening across all interfaces.
This should be the IP address assigned to the interface that RMR should listen
on, and if not defined RMR will listen on all interfaces.
- &half_space
&ditem(RMR_CTL_PORT)
This variable defines the port that RMR should open for communications
be defined.
In the case where both variables are defined, RMR will behave exactly as is
communicated with the variable's values.
- &half_space
&ditem(RMR_RTG_SVC)
The value of this variable depends on the Route Manager in use.
When the Route Manager is expecting RMR to connect and request a
table update during initialisation, the variable should be the
&cw(host:port) of the Route Manager process.
-
+
&space
The &cw(RMR_CTL_PORT) variable (added with the support of sending table update
requests to Route manager), controls the behaviour if this variable is not set.
See the description of that variable for details.
- &half_space
&ditem(RMR_HR_LOG)
By default RMR writes messages to standard error (incorrectly referred to as log messages)
If this environment variable is set to 0, the format of standard error messages might
be written in some format not easily read by humans.
If missing, a value of 1 is assumed.
- &half_space
&ditem(RMR_LOG_VLEVEL)
This is a numeric value which corresponds to the verbosity level used to limit messages
The following is the current relationship between the value set on this variable and
the messages written:
+ &half_space
+ &indent
&beg_dlist(.25i : &bold_font )
&ditem(0) Off; no messages of any sort are written.
- &half_space
+
&ditem(1) Only critical messages are written (default if this variable does not exist)
- &half_space
+
&ditem(2) Errors and all messages written with a lower value.
- &half_space
+
&ditem(3) Warnings and all messages written with a lower value.
- &half_space
+
&ditem(4) Informational and all messages written with a lower value.
- &half_space
- &ditem(5) Debugging mode -- all messages written, however this requires RMR to have been compiled with debugging support enabled.
+
+ &ditem(5) Debugging mode -- all messages written, however this requires RMR to have
+ been compiled with debugging support enabled.
&end_dlist
- &half_space
+ &uindent
&ditem(RMR_RTG_ISRAW)
&bold(Deprecated.)
the rmr_rts_msg() function to return a response to the sender. If not supplied
RMR will use the hostname which in some container environments might not be
routable.
- &half_space
+ &space
The value of this variable is also used for Route Manager messages which are
sent via an RMR connection.
additional warnings.
&end_dlist
+&uindent
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
conditions occurs:
&half_space
&indent
-&beg_dlist( 0.3i : ^&bold_font )
- &di(1.) The message is sent without error
- &half_space
- &di(2.) The underlying transport reports a &ital(hard) failure
- &half_space
+&beg_list(&lic1)
+&item
+ The message is sent without error
- &di(3.) The maximum number of retry loops has been attempted
- &end_dlist
+&half_space
+&item
+ The underlying transport reports a &ital(hard) failure
+
+&half_space
+&item
+ The maximum number of retry loops has been attempted
+&end_list
&uindent
&space
&line_len(6i)
&h1(RMR Library)
+
&h2(NAME)
RMR -- Ric Message Router Library
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.
+
&ex_start
rte | 1 | app10:4560
&ex_end
meid_map | end | 2
&ex_end
+&space
This table indicates that the application (endpoint) &ital(control1)
"owns" 6 MEIDs and &ital(control2) owns 4. When message type 0 is
sent, the MEID in the message will be used to select the endpoint via
meid_map | start
mme_ar | <owner-endpoint> | <meid> [<meid>...]
mme_del | <meid> [<meid>...]
-meid_map | end | <count> [| <md5sum>
+meid_map | end | <count> | <md5sum>
&ex_end
&space
The following is a list of the various environment variables, what they control
and the defaults which RMR uses if undefined.
-&space
.** the list of environment vars supported
.im &{lib}/man/env_var_list.im
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
When &ital(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
-managerment (e.g. malloc) functions may impose a limit.
+management (e.g. malloc) functions may impose a limit.
&space
The &ital(ctx) parameter is the void context pointer that was returned by
&ex_end
&space
+Where:
&beg_dlist(.75i : ^&bold_font )
-&diitem(state) Is the current buffer state. Following a call to &cw(rmr_send_msg)
+&ditem(state) Is the current buffer state. Following a call to &cw(rmr_send_msg)
the state indicates whether the buffer was successfully sent which determines
exactly what the payload points to. If the send failed, the payload referenced
by the buffer is the message that failed to send (allowing the application to
When the state is &cw(RMR_OK) the buffer represents an empty buffer that the application
may fill in in preparation to send.
-&half_space
-&diitem(mtype) When sending a message, the application is expected to set this field
+&ditem(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.
-&half_space
-&diitem(len) The application using a buffer to send a message is expected to set the
+&ditem(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.
-&half_space
-&diitem(payload) The payload is a pointer to the actual received data. The
+&ditem(payload) The payload is a pointer to the actual received data. The
user programme may read and write from/to the memory referenced by the payload
up until the point in time that the buffer is used on a &cw(rmr_send, rmr_call)
or &cw(rmr_reply) function call.
should &bold(NOT) make use of the payload pointer.
-&half_space
-&diitem(xaction) The &ital(xaction) field is a pointer to a fixed sized area in
+&ditem(xaction) The &ital(xaction) field is a pointer to a fixed sized area in
the message into which the user may write a transaction ID.
The ID is optional with the exception of when the user application uses the &cw(rmr_call)
function to send a message and wait for the reply; the underlying RMR processing
expects that the matching reply message will also contain the same data in the
&ital(xaction) field.
-&half_space
-&diitem(sub_id)
+&ditem(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
When an application is forwarding or returning a buffer to the sender, it is the
application's responsibility to set/reset this value.
-&half_space
-&diitem(tp_state)
+&ditem(tp_state)
For C applications making use of RMR, the state of a transport based failure will
often be available via &cw(errno.)
However, some wrapper environments may not have direct access to the C-lib &cw(errno)
&di(ENOMEM) Unable to allocate memory.
&end_dlist
-.** &h2(EXAMPLE)
-
&h2(SEE ALSO )
rmr_tralloc_msg(3),
rmr_call(3),
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
The &cw(rmr_bytes2xact) function will copy up to &ital(len) bytes from &ital(src) to the
transaction ID (xaction) field in the message.
The field is a fixed length, gated by the constant &cw(RMR_MAX_XID) and if len is larger
-than this value, only RMR_MAX_XID bytes will actually be copied.
+than this value, only &cw(RMR_MAX_XID) bytes will actually be copied.
-&beg_dlist(.75i : ^&bold_font )
&h2(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, &cw(errno) is set
If the returned length does not match the length passed in, &cw(errno) will be set to one
of the following constants with the meaning listed below.
-&half_space
-&di(EINVAL) The message, or an internal portion of the message, was corrupted or the pointer was invalid.
+&beg_dlist(1i : &bold_font )
+ &ditem(EINVAL) The message, or an internal portion of the message, was corrupted or the pointer was invalid.
-&half_space
-&di(EOVERFLOW) The length passed in was larger than the maximum length of the field; only a portion of
- the source bytes were copied.
+ &ditem(EOVERFLOW) The length passed in was larger than the maximum length of the field; only a portion of
+ the source bytes were copied.
&end_dlist
&h2(EXAMPLE)
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
The timeout period is &bold(not) based on time (calls to clock are deemed too expensive
for a low latency system level library), but instead the period is based on the number of
received messages which are not the response.
-Using a non-time mechanism for &ital(timeout) prevents the async queue from filling
+Using a mechanism which is not time based for &ital(timeout) prevents the async queue from filling
(which would lead to message drops) in an environment where there is heavy message traffic.
&space
&half_space
&beg_dlist(.75i : ^&bold_font )
-&di(RMR_OK) The call was successful and the message buffer references the response message.
-&half_space
-&di(RMR_ERR_CALLFAILED) The call failed and the value of &ital(errno,) as described below,
+&ditem(RMR_OK) The call was successful and the message buffer references the response message.
+
+&ditem(RMR_ERR_CALLFAILED) The call failed and the value of &ital(errno,) as described below,
should be checked for the specific reason.
&end_dlist
&half_space
&beg_dlist(.75i : ^&bold_font )
-&di(ETIMEDOUT) Too many messages were queued before receiving the expected response
-&half_space
-&di(ENOBUFS) The queued message ring is full, messages were dropped
-&half_space
-&di(EINVAL) A parameter was not valid
-&half_space
-&di(EAGAIN) The underlying message system was interrupted or the device was busy;
+&ditem(ETIMEDOUT) Too many messages were queued before receiving the expected response
+
+&ditem(ENOBUFS) The queued message ring is full, messages were dropped
+
+&ditem(EINVAL) A parameter was not valid
+
+&ditem(EAGAIN) The underlying message system was interrupted or the device was busy;
the message was &bold(not) sent, and the user application should call
this function with the message again.
&end_dlist
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
the following with the indicated meaning.
&beg_dlist(.75i : ^&bold_font )
-&half_space
-&di(EINVAL) The message, or an internal portion of the message, was corrupted or the pointer was invalid.
-&half_space
-&di(ENOMEM) A nil pointer was passed for &ital(dest,) however it was not possible to allocate a
+&ditem(EINVAL) The message, or an internal portion of the message, was corrupted or the pointer was invalid.
+
+&ditem(ENOMEM) A nil pointer was passed for &ital(dest,) however it was not possible to allocate a
buffer using malloc().
&end_dlist
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
error message of a system call is propagated up, and thus this list might be incomplete.
&beg_dlist(.75i : ^&bold_font )
-&di(EINVAL) The use of this function is invalid in this environment.
+&ditem(EINVAL) The use of this function is invalid in this environment.
&end_dlist
&h2(EXAMPLE)
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
the following with the indicated meaning.
&beg_dlist(.75i : ^&bold_font )
-&half_space
-&di(EINVAL) The message, or an internal portion of the message, was corrupted or the pointer was invalid.
+&ditem(EINVAL) The message, or an internal portion of the message, was corrupted or the pointer was invalid.
&end_dlist
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
the following with the indicated meaning.
&beg_dlist(.75i : ^&bold_font )
-&half_space
-&di(EINVAL) The message, or an internal portion of the message, was corrupted or the pointer was invalid.
+&ditem(EINVAL) The message, or an internal portion of the message, was corrupted or the pointer was invalid.
&end_dlist
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
&h2(ERRORS)
&beg_dlist(.75i : ^&bold_font )
-&di(INVAL) Parameter(s) passed to the function were not valid.
+&ditem(INVAL) Parameter(s) passed to the function were not valid.
&end_dlist
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
the following with the indicated meaning.
&beg_dlist(.75i : ^&bold_font )
-&half_space
-&di(EINVAL) The message, or an internal portion of the message, was corrupted or the pointer was invalid.
+&ditem(EINVAL) The message, or an internal portion of the message, was corrupted or the pointer was invalid.
-&half_space
-&di(ENOMEM) A nil pointer was passed for &ital(dest,) however it was not possible to allocate a
+&ditem(ENOMEM) A nil pointer was passed for &ital(dest,) however it was not possible to allocate a
buffer using malloc().
&end_dlist
error message of a system call is propagated up, and thus this list might be incomplete.
&beg_dlist(.75i : ^&bold_font )
-&di(ENOMEM) Unable to allocate memory.
+&ditem(ENOMEM) Unable to allocate memory.
&end_dlist
&h2(EXAMPLE)
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
&half_space
&beg_dlist(.75i : ^&bold_font )
-&di(RMR_OK) The call was successful and the message buffer references the response message.
+&ditem(RMR_OK) The call was successful and the message buffer references the response message.
-&half_space
-&di(RMR_ERR_BADARG) An argument passed to the function was invalid.
+&ditem(RMR_ERR_BADARG) An argument passed to the function was invalid.
-&half_space
-&di(RMR_ERR_CALLFAILED) The call failed and the value of &ital(errno,) as described below,
+&ditem(RMR_ERR_CALLFAILED) The call failed and the value of &ital(errno,) as described below,
should be checked for the specific reason.
-&half_space
-&di(RMR_ERR_NOENDPT) An endpoint associated with the message type could not be found in the
+&ditem(RMR_ERR_NOENDPT) An endpoint associated with the message type could not be found in the
route table.
-&half_space
-&di(RMR_ERR_RETRY) The underlying transport mechanism was unable to accept the message
+&ditem(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.
&half_space
&beg_dlist(.75i : ^&bold_font )
-&di(ETIMEDOUT) Too many messages were queued before receiving the expected response
+&ditem(ETIMEDOUT) Too many messages were queued before receiving the expected response
-&half_space
-&di(ENOBUFS) The queued message ring is full, messages were dropped
+&ditem(ENOBUFS) The queued message ring is full, messages were dropped
-&half_space
-&di(EINVAL) A parameter was not valid
+&ditem(EINVAL) A parameter was not valid
-&half_space
-&di(EAGAIN) The underlying message system wsa interrupted or the device was busy;
+&ditem(EAGAIN) The underlying message system wsa interrupted or the device was busy;
the message was &bold(not) sent, and user application should call
this function with the message again.
&end_dlist
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
&space
&beg_dlist(.75i : ^&bold_font )
-&di(RMR_OK) The message was received without error.
+&ditem(RMR_OK) The message was received without error.
-&half_space
-&di(RMR_ERR_BADARG) A parameter passed to the function was not valid (e.g. a nil pointer).
+&ditem(RMR_ERR_BADARG) A parameter passed to the function was not valid (e.g. a nil pointer).
indicate either &cw(RMR_OK) or
&cw(RMR_ERR_EMPTY) if an empty message was received.
-&half_space
-&di(RMR_ERR_EMPTY) The message received had no associated data. The length of the
+&ditem(RMR_ERR_EMPTY) The message received had no associated data. The length of the
message will be 0.
-&half_space
-&di(RMR_ERR_NOTSUPP) The multi-threaded option was not enabled when RMR was
+&ditem(RMR_ERR_NOTSUPP) The multi-threaded option was not enabled when RMR was
initialised. See the man page for &ital(rmr_init()) for details.
-&half_space
-&di(RMR_ERR_RCVFAILED) A hard error occurred preventing the receive from completing.
+&ditem(RMR_ERR_RCVFAILED) A hard error occurred preventing the receive from completing.
&end_dlist
&space
&beg_dlist(.75i : ^&bold_font )
-&di(INVAL) Parameter(s) passed to the function were not valid.
+&ditem(INVAL) Parameter(s) passed to the function were not valid.
-&half_space
-&di(EBADF) The underlying message transport is unable to process the request.
+&ditem(EBADF) The underlying message transport is unable to process the request.
-&half_space
-&di(ENOTSUP) The underlying message transport is unable to process the request.
+&ditem(ENOTSUP) The underlying message transport is unable to process the request.
-&half_space
-&di(EFSM) The underlying message transport is unable to process the request.
+&ditem(EFSM) The underlying message transport is unable to process the request.
-&half_space
-&di(EAGAIN) The underlying message transport is unable to process the request.
+&ditem(EAGAIN) The underlying message transport is unable to process the request.
-&half_space
-&di(EINTR) The underlying message transport is unable to process the request.
+&ditem(EINTR) The underlying message transport is unable to process the request.
-&half_space
-&di(ETIMEDOUT) The underlying message transport is unable to process the request.
+&ditem(ETIMEDOUT) The underlying message transport is unable to process the request.
-&half_space
-&di(ETERM) The underlying message transport is unable to process the request.
+&ditem(ETERM) The underlying message transport is unable to process the request.
&end_dlist
&h2(EXAMPLE)
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
&h2(ERRORS)
&beg_dlist(.75i : ^&bold_font )
-&di(INVAL) Parameter(s) passed to the function were not valid.
+&ditem(INVAL) Parameter(s) passed to the function were not valid.
&end_dlist
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
&half_space
&beg_dlist(.75i : ^&bold_font )
-&di(RMR_ERR_EMPTY) The message received had no payload, or was completely empty.
+&ditem(RMR_ERR_EMPTY) The message received had no payload, or was completely empty.
&half_space
-&di(RMR_ERR_TIMEOUT) For some transport mechanisms, or if reading the receive
+&ditem(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
&space
&beg_dlist(.75i : ^&bold_font )
-&di(INVAL) Parameter(s) passed to the function were not valid.
+&ditem(INVAL) Parameter(s) passed to the function were not valid.
-&half_space
-&di(EBADF) The underlying message transport is unable to process the request.
+&ditem(EBADF) The underlying message transport is unable to process the request.
-&half_space
-&di(ENOTSUP) The underlying message transport is unable to process the request.
+&ditem(ENOTSUP) The underlying message transport is unable to process the request.
-&half_space
-&di(EFSM) The underlying message transport is unable to process the request.
+&ditem(EFSM) The underlying message transport is unable to process the request.
-&half_space
-&di(EAGAIN) The underlying message transport is unable to process the request.
+&ditem(EAGAIN) The underlying message transport is unable to process the request.
-&half_space
-&di(EINTR) The underlying message transport is unable to process the request.
+&ditem(EINTR) The underlying message transport is unable to process the request.
-&half_space
-&di(ETIMEDOUT) The underlying message transport is unable to process the request.
+&ditem(ETIMEDOUT) The underlying message transport is unable to process the request.
-&half_space
-&di(ETERM) The underlying message transport is unable to process the request.
+&ditem(ETERM) The underlying message transport is unable to process the request.
&end_dlist
&h2(EXAMPLE)
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
&half_space
&beg_dlist(.75i : ^&bold_font )
-&di(ENOMEM) Memory allocation of the new payload failed.
-&half_space
+&ditem(ENOMEM) Memory allocation of the new payload failed.
-&di(EINVAL) The pointer passed in was nil, or refrenced an invalid message, or the required
+&ditem(EINVAL) The pointer passed in was nil, or referenced an invalid message, or the required
length was not valid.
&end_dlist
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
&space
&beg_dlist(.75i : ^&bold_font )
-&di(RMR_ERR_BADARG) The message buffer pointer did not refer to a valid message.
-&di(RMR_ERR_NOHDR) The header in the message buffer was not valid or corrupted.
-&di(RMR_ERR_NOENDPT) The message type in the message buffer did not map to a known endpoint.
-&di(RMR_ERR_SENDFAILED) The send failed; &cw(errno) has the possible reason.
+&ditem(RMR_ERR_BADARG) The message buffer pointer did not refer to a valid message.
+&ditem(RMR_ERR_NOHDR) The header in the message buffer was not valid or corrupted.
+&ditem(RMR_ERR_NOENDPT) The message type in the message buffer did not map to a known endpoint.
+&ditem(RMR_ERR_SENDFAILED) The send failed; &cw(errno) has the possible reason.
&end_dlist
&space
The following values may be assigned to &cw(errno) on failure.
+
&beg_dlist(.75i : ^&bold_font )
-&di(INVAL) Parameter(s) passed to the function were not valid, or the underlying message processing environment was unable to interpret the message.
+&ditem(INVAL) Parameter(s) passed to the function were not valid, or the underlying message processing environment was unable to interpret the message.
-&half_space
-&di(ENOKEY) The header information in the message buffer was invalid.
+&ditem(ENOKEY) The header information in the message buffer was invalid.
-&half_space
-&di(ENXIO) No known endpoint for the message could be found.
+&ditem(ENXIO) No known endpoint for the message could be found.
-&half_space
-&di(EMSGSIZE) The underlying transport refused to accept the message because of a size value issue (message was not attempted to be sent).
+&ditem(EMSGSIZE) The underlying transport refused to accept the message because of a size value issue (message was not attempted to be sent).
-&half_space
-&di(EFAULT) The message referenced by the message buffer is corrupt (nil pointer or bad internal length).
+&ditem(EFAULT) The message referenced by the message buffer is corrupt (nil pointer or bad internal length).
-&half_space
-&di(EBADF) Internal RMR error; information provided to the message transport environment was not valid.
+&ditem(EBADF) Internal RMR error; information provided to the message transport environment was not valid.
-&half_space
-&di(ENOTSUP) Sending was not supported by the underlying message transport.
+&ditem(ENOTSUP) Sending was not supported by the underlying message transport.
-&half_space
-&di(EFSM) The device is not in a state that can accept the message.
+&ditem(EFSM) The device is not in a state that can accept the message.
-&half_space
-&di(EAGAIN) The device is not able to accept a message for sending. The user application should attempt to resend.
+&ditem(EAGAIN) The device is not able to accept a message for sending. The user application should attempt to resend.
-&half_space
-&di(EINTR) The operation was interrupted by delivery of a signal before the message was sent.
+&ditem(EINTR) The operation was interrupted by delivery of a signal before the message was sent.
-&half_space
-&di(ETIMEDOUT) The underlying message environment timed out during the send process.
+&ditem(ETIMEDOUT) The underlying message environment timed out during the send process.
-&half_space
-&di(ETERM) The underlying message environment is in a shutdown state.
+&ditem(ETERM) The underlying message environment is in a shutdown state.
&end_dlist
&h2(EXAMPLE)
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
&space
&beg_dlist(.75i : ^&bold_font )
-&di(RMR_RETRY) The message could not be sent, but the underlying transport mechanism
+&ditem(RMR_RETRY) The message could not be sent, but the underlying transport mechanism
indicates that the failure is temporary. If the send operation is tried again
it might be successful.
-&di(RMR_SEND_FAILED) The send operation was not successful and the underlying transport
+&ditem(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.
-&di(RMR_ERR_BADARG) The message buffer pointer did not refer to a valid message.
-&di(RMR_ERR_NOHDR) The header in the message buffer was not valid or corrupted.
-&di(RMR_ERR_NOENDPT) The message type in the message buffer did not map to a known endpoint.
+&ditem(RMR_ERR_BADARG) The message buffer pointer did not refer to a valid message.
+&ditem(RMR_ERR_NOHDR) The header in the message buffer was not valid or corrupted.
+&ditem(RMR_ERR_NOENDPT) The message type in the message buffer did not map to a known endpoint.
&end_dlist
&space
The following values may be assigned to &cw(errno) on failure.
&beg_dlist(.75i : ^&bold_font )
-&di(INVAL) Parameter(s) passed to the function were not valid, or the underlying message processing environment was unable to interpret the message.
+&ditem(INVAL) Parameter(s) passed to the function were not valid, or the underlying message processing environment was unable to interpret the message.
-&half_space
-&di(ENOKEY) The header information in the message buffer was invalid.
+&ditem(ENOKEY) The header information in the message buffer was invalid.
-&half_space
-&di(ENXIO) No known endpoint for the message could be found.
+&ditem(ENXIO) No known endpoint for the message could be found.
-&half_space
-&di(EMSGSIZE) The underlying transport refused to accept the message because of a size value issue (message was not attempted to be sent).
+&ditem(EMSGSIZE) The underlying transport refused to accept the message because of a size value issue (message was not attempted to be sent).
-&half_space
-&di(EFAULT) The message referenced by the message buffer is corrupt (nil pointer or bad internal length).
+&ditem(EFAULT) The message referenced by the message buffer is corrupt (nil pointer or bad internal length).
-&half_space
-&di(EBADF) Internal RMR error; information provided to the message transport environment was not valid.
+&ditem(EBADF) Internal RMR error; information provided to the message transport environment was not valid.
-&half_space
-&di(ENOTSUP) Sending was not supported by the underlying message transport.
+&ditem(ENOTSUP) Sending was not supported by the underlying message transport.
-&half_space
-&di(EFSM) The device is not in a state that can accept the message.
+&ditem(EFSM) The device is not in a state that can accept the message.
-&half_space
-&di(EAGAIN) The device is not able to accept a message for sending. The user application should attempt to resend.
+&ditem(EAGAIN) The device is not able to accept a message for sending. The user application should attempt to resend.
-&half_space
-&di(EINTR) The operation was interrupted by delivery of a signal before the message was sent.
+&ditem(EINTR) The operation was interrupted by delivery of a signal before the message was sent.
-&half_space
-&di(ETIMEDOUT) The underlying message environment timed out during the send process.
+&ditem(ETIMEDOUT) The underlying message environment timed out during the send process.
-&half_space
-&di(ETERM) The underlying message environment is in a shutdown state.
+&ditem(ETERM) The underlying message environment is in a shutdown state.
&end_dlist
&h2(EXAMPLE)
Mnemonic rmr_set_fack.3.xfm
Abstract The manual page for the set fast ack function.
Author E. Scott Daniels
- Date 19 Fabruary 2020
+ Date 19 February 2020
.fi
.gv e LIB lib
The &cw(new_vlevel) value must be one of the following constants which have the
indicated meanings:
+&indent
&beg_dlist(1i : &bold_font )
&ditem(RMR_VL_OFF)
Turns off all message writing. This includes the stats and debugging messages generated by the
route collector thread which are normally affected only by the externally managed verbose
level file (and related environment variable).
-&half_space
&ditem(RMR_VL_CRIT)
Write only messages of critical importance.
Debugging must have also been enabled during the build as a precaution to accidentally
enabling this level of output as it can grossly affect performance.
&end_dlist
+&uindent
&space
Generally RMR does not write messages to the standard error device from &ital(critical path)
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
&h2(ERRORS)
If the return value is not RMR_OK, then it will be set to one of the values below.
-&half_space
&beg_dlist(.75i : ^&bold_font )
-&di(RMR_ERR_BADARG) The message, or an internal portion of the message, was corrupted or the pointer was invalid.
+&ditem(RMR_ERR_BADARG) The message, or an internal portion of the message, was corrupted or the pointer was invalid.
-&half_space
-&di(RMR_ERR_OVERFLOW) The length passed in was larger than the maximum length of the field; only a portion of
+&ditem(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.
&end_dlist
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
than this value, then &bold(nothing) will be copied. (Note, this differs slightly from the
behaviour of the &cw(lrmr_bytes2xact()) function.)
-&beg_dlist(.75i : ^&bold_font )
&h2(RETURN VALUE)
On success, the value RMR_OK is returned.
If the string cannot be copied to the message, the return value will be one of the
&h2(ERRORS)
If the return value is not RMR_OK, then it will be set to one of the values below.
-&half_space
-&di(RMR_ERR_BADARG) The message, or an internal portion of the message, was corrupted or the pointer was invalid.
+&beg_dlist(.75i : ^&bold_font )
+ &ditem(RMR_ERR_BADARG) The message, or an internal portion of the message, was corrupted or the pointer was invalid.
-&half_space
-&di(RMR_ERR_OVERFLOW) The length passed in was larger than the maximum length of the field; only a portion of
- the source bytes were copied.
+ &ditem(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.
&end_dlist
&h2(EXAMPLE)
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
&h2(ERRORS)
Not many of these functions set the value in &cw(errno,) however the value may be one of the following:
&beg_dlist(.75i : ^&bold_font )
-&di(INVAL) Parameter(s) passed to the function were not valid.
+&ditem(INVAL) Parameter(s) passed to the function were not valid.
&end_dlist
&h2(EXAMPLE)
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
&h2(ERRORS)
The &ital(state) field in the message buffer will be one of the following:
&space
+
&beg_dlist(.75i : ^&bold_font )
-&di(RMR_OK) The message buffer (payload) references the received data.
+&ditem(RMR_OK) The message buffer (payload) references the received data.
-&space
-&di(RMR_ERR_INITFAILED) The first call to this function must initialise an underlying
+&ditem(RMR_ERR_INITFAILED) The first call to this function must initialise an underlying
system notification mechanism. On failure, this error is returned and errno
- will have the system error status set. If this function fails to intialise,
- the poll mechansim, it is likely that message receives will never be successful.
+ 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.
-&space
-&di(RMR_ERR_TIMEOUT) The timeout expired before a complete message was received.
+&ditem(RMR_ERR_TIMEOUT) The timeout expired before a complete message was received.
All other fields in the message buffer are not valid.
-&space
-&di(RMR_ERR_EMPTY) A message was received, but it had no payload. All other
+&ditem(RMR_ERR_EMPTY) A message was received, but it had no payload. All other
fields in the message buffer are not valid.
&end_dlist
-&space
+
+Upon return the system error number, &ital(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:
&beg_dlist(.75i : ^&bold_font )
-&di(INVAL) Parameter(s) passed to the function were not valid.
+&ditem(INVAL) Parameter(s) passed to the function were not valid.
-&half_space
-&di(EBADF) The underlying message transport is unable to process the request.
+&ditem(EBADF) The underlying message transport is unable to process the request.
-&half_space
-&di(ENOTSUP) The underlying message transport is unable to process the request.
+&ditem(ENOTSUP) The underlying message transport is unable to process the request.
-&half_space
-&di(EFSM) The underlying message transport is unable to process the request.
+&ditem(EFSM) The underlying message transport is unable to process the request.
-&half_space
-&di(EAGAIN) The underlying message transport is unable to process the request.
+&ditem(EAGAIN) The underlying message transport is unable to process the request.
-&half_space
-&di(EINTR) The underlying message transport is unable to process the request.
+&ditem(EINTR) The underlying message transport is unable to process the request.
-&half_space
-&di(ETIMEDOUT) The underlying message transport is unable to process the request.
+&ditem(ETIMEDOUT) The underlying message transport is unable to process the request.
-&half_space
-&di(ETERM) The underlying message transport is unable to process the request.
+&ditem(ETERM) The underlying message transport is unable to process the request.
&end_dlist
&h2(EXAMPLE)
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
&ex_end
&space
-&beg_dlist(.75i : ^&bold_font )
-&diitem(state ) Is the current buffer state. Following a call to &cw(rmr_send_msg)
-the state indicates whether the buffer was successfully sent which determines
-exactly what the payload points to. If the send failed, the payload referenced
-by the buffer is the message that failed to send (allowing the application to
-attempt a retransmission).
-When the state is &cw(a_OK) the buffer represents an empty buffer that the application
-may fill in in preparation to send.
-
+Where:
&half_space
-&diitem(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.
-&half_space
-&diitem(len ) The application using a buffer to send a message is expected to set the
-length value to the actual number of bytes that it placed into the message. This
-is likely less than the total number of bytes that the message can carry.
-For a message buffer that is passed to the application as the result of a receive
-call, this will be the value that the sending application supplied and should
-indicate the number of bytes in the payload which are valid.
-
-&half_space
-&diitem(payload ) The payload is a pointer to the actual received data. The
-user programme may read and write from/to the memory referenced by the payload
-up until the point in time that the buffer is used on a &cw(rmr_send, rmr_call)
-or &cw(rmr_reply) function call.
-Once the buffer has been passed back to a a library function the user programme
-should &bold(NOT) make use of the payload pointer.
-
-
-&half_space
-&diitem(xaction) The &ital(xaction) field is a pointer to a fixed sized area in
-the message into which the user may write a transaction ID.
-The ID is optional with the exception of when the user application uses the &cw(rmr_call)
-function to send a message and wait for the reply; the underlying processing
-expects that the matching reply message will also contain the same data in the
-&ital(xaction) field.
+&beg_dlist(.75i : ^&bold_font )
+&ditem(state) Is the current buffer state. Following a call to &cw(rmr_send_msg)
+ the state indicates whether the buffer was successfully sent which determines
+ exactly what the payload points to. If the send failed, the payload referenced
+ by the buffer is the message that failed to send (allowing the application to
+ attempt a retransmission).
+ When the state is &cw(a_OK) the buffer represents an empty buffer that the application
+ may fill in in preparation to send.
+
+&ditem(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.
+
+&ditem(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.
+
+&ditem(payload) The payload is a pointer to the actual received data. The
+ user programme may read and write from/to the memory referenced by the payload
+ up until the point in time that the buffer is used on a &cw(rmr_send, rmr_call)
+ or &cw(rmr_reply) function call.
+ Once the buffer has been passed back to a a library function the user programme
+ should &bold(NOT) make use of the payload pointer.
+
+&ditem(xaction) The &ital(xaction) field is a pointer to a fixed sized area in
+ the message into which the user may write a transaction ID.
+ The ID is optional with the exception of when the user application uses the &cw(rmr_call)
+ function to send a message and wait for the reply; the underlying processing
+ expects that the matching reply message will also contain the same data in the
+ &ital(xaction) field.
&end_dlist
&h2(RETURN VALUE)
&h2(ERRORS)
&beg_dlist(.75i : ^&bold_font )
-&di(ENOMEM) Unable to allocate memory.
+&ditem(ENOMEM) Unable to allocate memory.
&end_dlist
.** &h2(EXAMPLE)
&space
&beg_dlist(.75i : ^&bold_font )
-&di(RMR_ERR_WHID) The wormhole ID passed in was not associated with an open wormhole, or was out of range for a valid ID.
-&di(RMR_ERR_NOWHOPEN) No wormholes exist, further attempt to validate the ID are skipped.
-&di(RMR_ERR_BADARG) The message buffer pointer did not refer to a valid message.
-&di(RMR_ERR_NOHDR) The header in the message buffer was not valid or corrupted.
+&ditem(RMR_ERR_WHID) The wormhole ID passed in was not associated with an open wormhole, or was out of range for a valid ID.
+&ditem(RMR_ERR_NOWHOPEN) No wormholes exist, further attempt to validate the ID are skipped.
+&ditem(RMR_ERR_BADARG) The message buffer pointer did not refer to a valid message.
+&ditem(RMR_ERR_NOHDR) The header in the message buffer was not valid or corrupted.
&end_dlist
&h2(EXAMPLE)
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
&space
&ital(Target) is the &ital(name:port,) or &ital(IP-address:port,) combination of the
-processess that the wormhole should be connected to.
+processes that the wormhole should be connected to.
&ital(Vctx) is the RMR void context pointer that was returned by the &cw(rmr_init) function.
&space
-When invoked, this function immediatly attempts to connect to the target process.
+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
the &cw(rmr_wh_send_msg) function when sending a message.
The id may also be tested to determine success or failure of the connection by
using the RMR_WH_CONNECTED macro and passing the ID as the parameter; a result of
-1 indicates that the connection was esablished and that the ID is valid.
+1 indicates that the connection was established and that the ID is valid.
&h2(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.
&beg_dlist(.75i : ^&bold_font )
-&di(EINVAL) A parameter passed was not valid.
-&di(EACCESS) The user application does not have the ability to establish a wormhole to the
+&ditem(EINVAL) A parameter passed was not valid.
+&ditem(EACCESS) The user application does not have the ability to establish a wormhole to the
indicated target (or maybe any target).
-&di(ECONNREFUSED) The connection was refused.
+&ditem(ECONNREFUSED) The connection was refused.
&end_dlist
&h2(EXAMPLE)
&space
&beg_dlist(.75i : ^&bold_font )
-&di(RMR_ERR_WHID) The wormhole ID passed in was not associated with an open wormhole, or was out of range for a valid ID.
-&di(RMR_ERR_NOWHOPEN) No wormholes exist, further attempt to validate the ID are skipped.
-&di(RMR_ERR_BADARG) The message buffer pointer did not refer to a valid message.
-&di(RMR_ERR_NOHDR) The header in the message buffer was not valid or corrupted.
+&ditem(RMR_ERR_WHID) The wormhole ID passed in was not associated with an open wormhole, or was out of range for a valid ID.
+&ditem(RMR_ERR_NOWHOPEN) No wormholes exist, further attempt to validate the ID are skipped.
+&ditem(RMR_ERR_BADARG) The message buffer pointer did not refer to a valid message.
+&ditem(RMR_ERR_NOHDR) The header in the message buffer was not valid or corrupted.
&end_dlist
&space
The following values may be assigned to &cw(errno) on failure.
&beg_dlist(.75i : ^&bold_font )
-&di(INVAL) Parameter(s) passed to the function were not valid, or the underlying message processing environment was unable to interpret the message.
+&ditem(INVAL) Parameter(s) passed to the function were not valid, or the underlying message processing environment was unable to interpret the message.
-&half_space
-&di(ENOKEY) The header information in the message buffer was invalid.
+&ditem(ENOKEY) The header information in the message buffer was invalid.
-&half_space
-&di(ENXIO) No known endpoint for the message could be found.
+&ditem(ENXIO) No known endpoint for the message could be found.
-&half_space
-&di(EMSGSIZE) The underlying transport refused to accept the message because of a size value issue (message was not attempted to be sent).
+&ditem(EMSGSIZE) The underlying transport refused to accept the message because of a size value issue (message was not attempted to be sent).
-&half_space
-&di(EFAULT) The message referenced by the message buffer is corrupt (nil pointer or bad internal length).
+&ditem(EFAULT) The message referenced by the message buffer is corrupt (nil pointer or bad internal length).
-&half_space
-&di(EBADF) Internal RMR error; information provided to the message transport environment was not valid.
+&ditem(EBADF) Internal RMR error; information provided to the message transport environment was not valid.
-&half_space
-&di(ENOTSUP) Sending was not supported by the underlying message transport.
+&ditem(ENOTSUP) Sending was not supported by the underlying message transport.
-&half_space
-&di(EFSM) The device is not in a state that can accept the message.
+&ditem(EFSM) The device is not in a state that can accept the message.
-&half_space
-&di(EAGAIN) The device is not able to accept a message for sending. The user application should attempt to resend.
+&ditem(EAGAIN) The device is not able to accept a message for sending. The user application should attempt to resend.
-&half_space
-&di(EINTR) The operation was interrupted by delivery of a signal before the message was sent.
+&ditem(EINTR) The operation was interrupted by delivery of a signal before the message was sent.
-&half_space
-&di(ETIMEDOUT) The underlying message environment timed out during the send process.
+&ditem(ETIMEDOUT) The underlying message environment timed out during the send process.
-&half_space
-&di(ETERM) The underlying message environment is in a shutdown state.
+&ditem(ETERM) The underlying message environment is in a shutdown state.
&end_dlist
&h2(EXAMPLE)
&space
&beg_dlist(.75i : ^&bold_font )
-&di(RMR_OK)
+&ditem(RMR_OK)
The wormhole ID is valid and the connection is "open."
- &half_space
-&di(RMR_ERR_WHID)
+&ditem(RMR_ERR_WHID)
THe wormhole ID passed into the function was not valid.
- &half_space
-&di(RMR_ERR_NOENDPT)
+&ditem(RMR_ERR_NOENDPT)
The wormhole is not open (not connected).
- &half_space
-&di(RMR_ERR_BADARG)
+&ditem(RMR_ERR_BADARG)
The context passed to the function was nil or invalid.
- &half_space
-&di(RMR_ERR_NOWHOPEN)
+&ditem(RMR_ERR_NOWHOPEN)
Wormholes have not been initialised (no wormhole open call has been made).
- &half_space
&end_dlist
.if ! _setup_im
+.** get lib, default to ..
.gv e LIB lib
-.if ! lib
- .dv lib ..
-.fi
+.dv lib &{lib!..}
+
+.hn off
+.ju on
.** CAUTION: xfm comparisons are reverse polish so "a b =" is true if a == b.
.if pfm
.im &{lib}/generic_ps.im
+ .cd 1 6.5i i=.75i
+ .pn on center noline f=%d
.ei
.gv e OUTPUT_TYPE ot
.if "&ot" "txt" =
.if "&ot" "troff" =
.im &{lib}/roff.im
.fi
+ .if "&ot" "html" =
+ .im &{lib}/html.im
+ .fi
.fi
.gv e GEN_TITLE gen_title
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
.dv bd .sp 1
.dv end_dlist .sp 1
.dv ed .sp 1
-.dv di ^&break **$1:**
+.dv ditem ^&break **$1:**
+.dv ditem_nosp ^&break **$1:**
.dv beg_list .bl *
.dv item .li
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
.dv h2 .sp 1 ^&bold($1) .br ^&space
.dv h3 .sp 1 ^&bold($1) .br ^&space
-.dv fig
+.dv fig
.dv set_font_cw .br ^^.ft CW
.dv nf ^^.nf .br .nf
.dv mult_space .br ^^.sp $1 .br
.dv beg_list
.dv end_list
+.dv item ^&space \(bu
+.dv li ^&space \(bu
+.dv li_sp ^&space \(bu
+
.dv beg_dlist .dv udi -$1 ^: ^^.in +$1 .br ^^.sp 1 .br
.dv end_dlist .br ^^.in &udi .br
.dv ditem ^^.ti ^&udi .br ^&space .br \fB$1\fR .br
-.dv item ^&space \(bu
-.dv li ^&space \(bu
-.** .dv di ^&ditem
-.dv di ^^.ti ^&udi .br ^&space .br \fB$1\fR .br
+.dv ditem_nosp ^^.ti ^&udi .br \fB$1\fR .br
+
+.** deprecated, but needed til doc cleaned up
+.dv diitem ^^.ti ^&udi .br ^&space .br \fB$1\fR .br
+.dv di ^^.ti ^&udi .br ^&space .br \fB$1\fR .br
.dv ex_start ^^.IP .br ^^.nf .br ^^.ft CW .br .nf
.dv ex_end .fo on .br ^^.ft P .br ^^.fi .br ^&space
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
.** convert {X}fm input into rts.
.** post processing is needed to strip the leading space that tfm insists on adding.
- .** bloody rst has no consistant marking character, and each header level must be different and as long as the text.
- .** and of course they don't generate <hx> tags in the resulting HTML, but <section> tags. WTF?
+ .** character offsets needed to provide bloody indention significant crap.
+ .** tfm converts points to characters using 7p/ch so these guarentee correct
+ .** spacing.
+ .**
+ .dv _ch2 14p
+ .dv _ch4 28p
+ .dv _ch6 42p
+ .dv _ch8 56p
+ .dv _ch10 70p
+
+ .** Long strings of equals and dashes needed to make title/subtitle easier to generate. Multi
+ .** line annotations for headers could be used, but the code is messy for what results in
+ .** 4 lines in the setup files.
+ .**
.dv many_equals ============================================================================================
.dv many_dashes --------------------------------------------------------------------------------------------
.dv many_tildas ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- .dv h1 .sp 1 $1 .br &many_equals .sp 1
- .dv h2 .sp 1 $1 .br &many_dashes .sp 1
- .dv h3 .sp 1 $1 .br &many_tildas .sp 1
- .** bloody rst won't allow breaks in a bullet list so we have to allow the column to go wide.
- .dv cd 1 180i m=0i
+ .gv semver
+ .if &_major 1 >
+ .** tfm version 2.0.0+ supports header annotation for rst
+ .dh 1 a==after s=2,1 i=0 m=0
+ .dh 2 a=-after s=2,1 i=0 m=0
+ .dh 3 a=~after s=2,0 i=0 m=0
+
+ .dv h1 .h1 $1
+ .dv h2 .h2 $1
+ .dv h3 .h2 $1
+ .ei
+ .dv __alert ### WARNING ### rst.im detects an old(er) version of tfm some formatting might not be right
+ .sv __alert
+
+ .dh 1 s=2,1 i=0 m=0
+ .dh 2 s=1.1 i=0 m=0
+ .dh 3 s=1,0 i=0 m=0
+
+ .dv h1 .sp 1 $1 .br &many_equals .sp 1
+ .dv h2 .sp 1 $1 .br &many_dashes .sp 1
+ .dv h3 .sp 1 $1 .br &many_tildas .sp 1
+ .fi
+
+ .dv cd 1 &{col_width!8.0i} m=0i
.dv h4 **$1**
- .** .dv h1 === $1 .br === .sp 1
- .** .dv h2 === $1 .br === .sp 1
- .** .dv h3 === $1 .br === .sp 1
- .dv fig
+ .dv fig .fg $1
+ .dv fig_cen .fg $1
.dv set_font_cw
.dv nf .sp 1 ^:^: .br .ll -2 .in +2
.dv indent
.dv uindent
- .dv lic1 +
+ .** list item characters
+ .dv lic1 *
.dv lic2 -
- .dv lic3 *
+ .dv lic3 +
.in 0i .** bloody rst is indention sensitive like markdown; sheesh
- .dv esc \ : .** bloody need to escape _ and * at the end of a word
+ .dv esc \$1 : .** bloody need to escape _ and * at the end of a word
.dv line_len .ll $1
.dv space .sp 1
.dv half_space .sp 1
+ .dv break .br |
.dv mult_space .sp $1
- .dv beg_list .ll 17i .sp 1 .dv lic $1 ^:
- .dv end_list .ll 6i .sp 1
- .dv beg_dlist .sp 1 .ll -3
- .dv end_dlist .br .in 0i .ll +3
+ .** ------- bullet lists -------------------------
+ .dv beg_list .sp 1 .bl ${1!*} ^: .br
+ .dv end_list .el .sp 1
+ .dv li .br .li
- .** for now we allow only a single layer of defitems
- .dv di .in 0i .br $1 .br .in +3
- .dv ditem .in 0i .br $1 .br .in +3
- .** diitem is odd and deprecated
- .dv diitem .in 0i .br $1 .br .in +3
- .dv item .br &lic
- .dv li .br &lic
-
- .dv ex_start .sp 1 ^:^: .br .ll -2 .in +2 .nf
+ .dv ex_start .sp 1 ^:^: .sp 1 .ll -2 .in +2 .nf
.dv ex_end .fo on .in -2 .ll +2 .sp 1
+ .dv ex_end_fig .fo on .in -2 .ll +2 .fg $1 ^: .sp 1
+ .dv ex_end_cfig .fo on .in -2 .ll +2 .fg $1 ^: .sp 1
.dv proto_start .sp 1 .cc .5i .st 9 .sf Courier-bold .nf
.dv proto_end .fo on .sf ^&text_font .st ^&text_size .sp .3
.dv center .br $1 .br
- .dv center_start .br
- .dv center_end .br
+ .dv center_start ^.. class:: center .br
+ .dv center_end .sp 1
.** fonts and font macros
.dv ital *$1*
.dv bold **$1**
- .dv cw $1
+ .dv cw ^^^`^^^`$1^^^`^^^`
+ .** global font changes seem impossible in RST
.dv set_font_prop
- .dv table .sp 1 ^[table not supported in rst output] .if false
- .dv tab_cell
- .dv tab_row
- .dv end_table .fi
-
.dv super .sm ^[ .sm ^&{ss_num}]
.dv ss_num 1
.dv note .dv ss_num ^[ ?%.0f ^&ss_num 1 + ] ^: .sm ^^[^&{ss_num}]
.** rst has no concept of a page, so all notes go to the close of the doc
.dv atbot atclose
+
+ .** ----------- definition lists and tables ------------------------------------
+ .if false
+ A list table without borders should build a reasonable def list in
+ RST. What RST touts as a def list turns out looking like crap, so we
+ jump some hoops to generate a two column table.
+ The usual pratcice of adding half space between items is ignored
+ by rst, and we add addtional "logic" to insert a blank line betwen
+ rows in order to visually separate the entries. Better than the default
+ but certainly not great. The output of these macros is extreamely space
+ sensitive (leading spaces because python programmers believe these
+ kinds of "everythign must align" parsers are good).
+
+ It seems that not all HTML generated from RST is done consistently. As an example
+ the HTML generated for read the docs does NOT respect the no boarder option
+ on tables, and adds additional space at the bottom of each table. Thus there
+ are two sets of definition list macros; by default the RTD style of ignoring
+ directives is assumed. The alternate set can be enabled by setting the variable
+ 'sane_dlist' before imbedding this definition file.
+
+ When sane_dlist is set to 1, definition list items will be separated with a row
+ separater applied at the start of rows 2-n.
+
+ RST requires a blank line prior to the start of the list, so we force one.
+ .fi
+
+ .** beg_dlist parms 1 and 2 are for PFM, $3 is for rst and is optionally the term,def widths (e.g. 15,80)
+ .** mind the tildas (end of line escapes in {X}fm
+ .**
+ .if &{sane_dlist!0} 1 =
+ .dv beg_dlist .dv di_term 1 ^: ~
+ .dv row_sep .sp 1 ^: ~
+ .sp 1 ~
+ .in +&_ch4 ~
+ ^.. list-table^:^: .in +&_ch2 ^:widths^: ${3!auto} .br ^:header-rows^: 0 .br ^:class^: borderless ~
+ .in +&ch_6
+
+ .dv ditem ^&row_sep * - **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .sp 1 | .in -&{_ch4} .sp 1 ^:
+ .dv ditem_nosp .in -&{_ch4} * - **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .sp 1 | .in -&{_ch4} .sp 1 ^:
+
+ .dv di ^&row_sep * - **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .sp 1 | .in -&{_ch4} .sp 1 ^:
+ .dv diitem ^&row_sep * - **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .sp 1 | .in -&{_ch4} .sp 1 ^:
+
+ .ei
+ .dv beg_dlist .dv di_term 1 ^: ~
+ .dv row_sep .sp 1 ^: ~
+ .sp 1 ~
+ .in +&_ch4 ~
+ ^.. list-table^:^: .in +&_ch2 ^:widths^: ${3!auto} .br ^:header-rows^: 0 .br ^:class^: borderless ~
+ .in +&ch_6
+
+ .dv ditem ^&row_sep * - **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .in -&{_ch4} .sp 1 ^:
+ .dv ditem_nosp ^&row_sep * - **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .in -&{_ch4} .sp 1 ^:
+ .dv di ^&row_sep * - **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .in -&{_ch4} .sp 1 ^:
+ .dv diitem ^&row_sep * - **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .in -&{_ch4} .sp 1 ^:
+ .fi
+
+ .** auto numbering ditem has to be hacked in since we're completely unable to use {X}fm's list gen for RST
+ .dv aditem ^&row_sep .in &_ch6 * - **^&{di_term}** .in &_ch8 - .in &_ch10 .dv row_sep .sp 1 | .sp 1 ^: .dv di_term ^[ %.0f ^&di_term 1 + ]
+
+ .dv end_dlist .sp 1 .in -&{_ch10} .sp 1
+
+ .** generate a table with borders
+ .dv beg_table ^.. list-table^:^: .br ^` ^` ^:widths^: $1 .br ^` ^` ^:header-rows^: 0 .sp 1
+
+ .** generate a table without borders
+ .dv beg_table_nb ^.. list-table^:^: .br ^` ^` ^:widths^: $1 .br ^` ^` ^:header-rows^: 0 .br ^` ^` ^:class^: borderless .sp 1
+
+ .** remainder of table support commands not dependent on borders/borderless
+ .dv col .in 0i .br ^` ` -` ^` .in 56p
+ .dv row .in 0i .sp 1 ^` ` * -` ^` .in 56p
+ .dv end_table .sp 1 .in 0i
+ .dv tab_cell ^&col
+ .dv tab_row ^&row
+
.ju off
# {X}fm is required to compile the source.
-%.rst:: %.xfm man_list.im
+%.rst:: %.xfm
OUTPUT_TYPE=rst tfm $< | sed 's/^ //' >$@
-%.ps:: %.xfm man_list.im
+%.ps:: %.xfm
OUTPUT_TYPE=ps pfm $< $@
-%.txt:: %.xfm man_list.im
+%.txt:: %.xfm
OUTPUT_TYPE=txt tfm $< $@
-%.md:: %.xfm man_list.im
+%.md:: %.xfm
OUTPUT_TYPE=markdown tfm $< | sed 's/^ //' >$@
-docs = config-deploy developer-guide rel-notes overview
+%.html:: %.xfm
+ OUTPUT_TYPE=html hfm $< $@
-all:: $(docs:%=%.rst) $(docs:%=%.txt) $(docs:%=%.md)
+docs = config-deploy developer-guide rel-notes
-man_list.im:: always
- bash gen_man_list.sh >man_list.im
+all:: $(docs:%=%.rst) $(docs:%=%.txt) $(docs:%=%.md)
rel-notes.xfm:: always
ksh fmt_changes.ksh >rel-notes.xfm
$(docs:%=%.rst): always
$(docs:%=%.txt): always
$(docs:%=%.md): always
+$(docs:%=%.html): always
# copy the .rst files which have changed into the docs (plural) directory at the root of the repo
files must be checked into the repo and committed with changes to the
source (maybe not the best practice).
-The command 'make all' should be all that is needed to build the
+The command 'make all' should be all that is needed to build the
rtd documentation. Follow that with 'make publish' to actually move
the .rst files into the docs directory at the root; only the changed
files are moved.
Adding A New Man Page
-When a new manual page is added to the source (../man), it must be
+When a new manual page is added to the source (../man), it must be
added to the list in the user's guide source in this directory.
Rationale
Documentation is just code, and by maintaining the documentation as
-source is is possible to generate various forms of output with a
+source is is possible to generate various forms of output with a
single make. While it is possible to convert X to Y, a true document
composition language is far better at generating readable Postscript
-output with embedded figures as well as text and tables.
+output with embedded figures as well as text and tables.
CAUTION:
The RST syntax is as bad as python when it comes to dealing with
spaces. For example &bold( foo ) will insert spaces after the initial
bold trigger, and before the trailing bold trigger which will throw
-the tox validation into a tizzy. Further, something like 'void *'
+the tox validation into a tizzy. Further, something like 'void *'
and 'rmr_ ' does as well. If needed, use the defined escape macro
to add an escape in such situations; it should only generate for RST
and not impact other output formats.
Author: E. Scott Daniels
.fi
+.gv e LIB lib
+.dv lib &{lib!..}
+
+.dv GEN_TITLE 1
+.dv doc_title Configuration and Deployment
+
.im setup.im
-&h1(RMR Configuration and Deployment)
+&h1(Overview)
The RIC Message Router (RMR) is a library for peer-to-peer
communication. Applications use the library to send and receive
.** vim: ts=4 noet sw=4:
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
Author: E. Scott Daniels
.fi
+.dv GEN_TITLE=1
+.dv doc_title Developer's Guide
+
.im setup.im
-&h1(RMR Developer Guide)
+&h1(Overview)
The RIC Message Router (RMR) is a library for peer-to-peer
communication. Applications use the library to send and receive
&beg_dlist(.75i : ^&bold_font )
-&di(common) Source in the common directory is agnostic to the
+&ditem(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.
-&di(nano) Source which is tightly coupled with the underlying Nanomsg library.
+&ditem(nano) Source which is tightly coupled with the underlying Nanomsg library.
(Nanomsg has been deprecated, but the RMR source remains as an example.)
-&di(nng) Source which is tightly coupled with the underlying NNG library.
+&ditem(nng) Source which is tightly coupled with the underlying NNG library.
(NNG has been deprecated, but the RMR source remains as an example.)
-&di(si) Source which is tightly coupled with the underlying SI95 library.
+&ditem(si) Source which is tightly coupled with the underlying SI95 library.
&end_dlist
# RTD file is created.
cat <<endKat
+
+.dv GEN_TITLE 1
+.dv doc_title RMR Release Notes
.im setup.im
+.dh 1 u=off
+
&h1(RMR Release Notes)
-The following is a list of release highlights for the core RMR library and
-wrappers which are housed in the same repository.
-These are extracted directly from the CHANGES_*.txt files at the repo root;
-please refer to those files for a completely up to date listing of
-API changes (as generated documents may lag).
+The following is a list of release highlights for the RMR library.
+At one point in time the RMR repo also housed a wrapper library with a
+separate version and release cycle.
+This resulted in &ital(leap frogging) versions for each package; the
+RMR core library was assigned odd major numbers (e.g. 3.1.0).
+When the wrapper code was moved to a different repo the need to leap frog
+versions ceased, and beginning with version 4.0.0, the RMR versions should
+no longer skip.
&space
-The RMR repo houses two distinct release entities: the core RMR package
-and the python wrapper package.
-To avoid naming conflicts (tags mostly) The core package uses odd
-major version numbers (e.g. 3.2.1) and the wrapper package uses even
-major version numbers.
-The release notes are split into two sections; please be sure to
-scroll to the section that is appropriate.
-
endKat
for x in ../../../CHANGES*.txt
do
- case $x in
- *CORE*) printf "&h2(Core RMR Changes)\n" ;;
- *) printf "&h2(Wrapper Changes)\n" ;;
- esac
+ sed 's/^/!/' $x | awk '
+ print_raw && /^!$/ {
+ printf( "&space\n\n" );
+ next
+ }
- sed 's/^/!/' $x | awk '
- print_raw && /^!$/ {
- printf( "&space\n\n" );
- next
- }
-
{ gsub ( "!", "", $1 ) }
-
+
$1 + 0 >= 2019 {
print_raw = 1
- printf( "&h3(%s)\n", $0 )
- next
+ printf( "&h2(%s)\n", $0 )
+ next
}
-
- print_raw { print }
+
+ print_raw { print }
' ###
done
Date: 10 April 2020
.fi
+.** special man page title generator
.gv e INPUT_FILE in
.if in
.if ! doc_title
.fi
.fi
+.** add license to the document as a comment; where possible
.im license.im
.gv e OUTPUT_TYPE ot
&doc_subtitle .br
&many_dashes .br
.fi
+ .sp 2
.ei
- .sf Helvetica
- .sp 5
- .st 18
- .ce &doc_title
- .st 12
- .if doc_subtitle
- .ce &doc_subtitle
+ if pfm
+ .sf Helvetica-bold
+ .sp 5
+ .st 18
+ .ce &doc_title
+ .st 12
+ .if doc_subtitle
+ .ce &doc_subtitle
+ .fi
+ .st &textsize
+ .sf &txtfont
+ .sp 2
+ .ei
+ .sp 1
+ .ce &doc_title
+ .br
+ .if doc_subtitle
+ .ce &doc_subtitle
+ .fi
+
+ .sp 2
.fi
- .st &textsize
- .sf &txtfont
- .sp 2
.fi
.fi
.** vim: ts=4 noet sw=4:
.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
.if ! _license_im
-.cd 1 14i i=0
-.ll 14i
-.in 0i
-
.dv lic_comment_1 This work is licensed under a Creative Commons Attribution 4.0 International License.
.dv lic_comment_2 SPDX-License-Identifier: CC-BY-4.0
.dv caution_1 CAUTION: this document is generated from source in doc/src/rtd.
.dv caution_2 To make changes edit the source and recompile the document.
.dv caution_3 Do NOT make changes directly to .rst or ^.md files.
-.if &ot "postscript" =
- .** this is native postscript, so as is
- .ai
- % &lic_comment_1
- % &lic_comment_2
- .fo
+.if pfm
+ .** this is native postscript, so as is and NO indention in this source
+.ai
+% &lic_comment_1
+% &lic_comment_2
+.fo
.** no caution because nobody will change the postscript
.ei
+ .if ! ot
+ .gv e OUTPUT_TYPE ot
+ .fi
+
+ .** only rst supports comments
.if "&ot" "rst" =
+ .pu
+ .** we have to ensure that our lines don't break as there is no block comment
+ .cd 1 14i i=0
+ .ll 14i
+ .in 0i
+
^.. &lic_comment_1
.br
^.. &lic_comment_2
^.. &caution_2
.br
^.. &caution_3
+
+ .po
.fi
.fi
.if ! col_width
.cd 1 8i i=0
.ei
- .cd 1 &col_width i=0
+ .if col_indent
+ .cd 1 &col_width i=&col_indent
+ .ei
+ .cd 1 &col_width i=.5i
+ .fi
.fi
-.ll 8i
-.in 0
-
.dv _license_im 1
.fi
Author: E. Scott Daniels
.fi
+.dv GEN_TITLE 1
+.dv doc_title RMR Overview
.im setup.im
-&h1(RMR Overview)
+.sp
+Please refer to the main RMR manual page for an overview of the library:
-.im &{lib}/man/rmr.7.xfm
+&space
+https://docs.o-ran-sc.org/projects/o-ran-sc-ric-plt-lib-rmr/en/latest/index.html
# limitations under the License.
#==================================================================================
-# Build the user doc in ../library and if there are changes publish it into
+# Build the documents in ../library and if there are changes publish it into
# the scraper (../../../docs) directory.
sdir="../../../docs" # the scraper dir
set -e
cd ../library
-make -B user.rst
+make -B docs # make all documents pushed to scraper dir
-new_m5=$( md5sum user.rst | sed 's/ .*//' )
-old_md5=$( md5sum $sdir/user-guide.rst | sed 's/ .*//' )
-if [[ $new_m5 != $old_m5 ]]
-then
- echo "publishing user-guide.rst"
- cp user.rst $sdir/user-guide.rst
-fi
+for f in *.rst
+do
+ touch $sdir/$f # must ensure it is there if new
+ new_md5=$( md5sum $f | sed 's/ .*//' )
+ old_md5=$( md5sum $sdir/$f | sed 's/ .*//' )
+
+ if [[ $new_md5 != $old_md5 ]]
+ then
+ echo "publishing $f"
+ cp $f $sdir/$f
+ fi
+done
# scarper directory we will copy it over there. We inject a title so that the
# RTD scripts won't object.
-sdir="../../../docs" # the scraper dir
+sdir="${RTD_SCRAPER_DIR:-../../../docs}" # the scraper dir (allow for testing/alternate)
if [[ ! -d $sdir ]]
then
mkdir -p stuff
ls -al ../man/*.xfm|sed 's!^.*man/!!' | while read x
do
- if [[ $x != *".7.xfm" ]]
+ if true
then
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/^ //' >$out
new_m5=$( md5sum $out | sed 's/ .*//' )
if [[ ! -f $target || $new_m5 != $( md5sum $target | sed 's/ .*//' ) ]]
then
+ echo "publishing to: ${target##*/}"
cp $out $target
fi
- echo "${target##*/}"
rm $out
fi
.dv lib ..
.fi
+.hn off
+
.** CAUTION: xfm comparisons are reverse polish so "a b =" is true if a == b.
.if pfm
.dv ot postscript
.if "&ot" "troff" =
.im &{lib}/roff.im
.fi
+ .if "&ot" "html" =
+ .im &{lib}/html.im
+ .fi
.fi
+.dh u=off
+
.** if we can set a license into the output, do it early
.cd 1 11i
&line_len(10i)
.dv textfont Helvetica
.fi
+.if doc_title
+ .im &{lib}/library/front_junk.im
+.fi
+
.dv _setup_im 1
.fi
-.if false
+f false
==================================================================================
Copyright (c) 2019 Nokia
Copyright (c) 2018-2019 AT&T Intellectual Property.
.dv center_start .bc start
.dv center_end .bc end
-.** for now we allow only a single layer of defitems
-.dv di .di $1 ^:
-.dv diitem .di $1 ^:
.dv item .li
+.dv ditem .sp 1 .di $1 ^:
+.dv ditem_nosp .di $1 ^:
+
+.** for now we allow only a single layer of defitems
+.dv di .sp 1 .di $1 ^:
+.dv diitem .sp 1 .di $1 ^:
.dv ex_start .sp 1 .ll -2 .in +2 .nf
.dv ex_end .fo on .in -2 .ll +2 .sp 1
+.dv ex_end_fig .fo on .in -2 .ll +2 .fg $1 ^: .sp 1
+.dv ex_end_cfig .fo on .in -2 .ll +2 .fg x=center $1 ^: .sp 1
.dv proto_start .sp 1 .cc .5i .st 9 .sf Courier-bold .nf
.dv proto_end .fo on .sf ^&text_font .st ^&text_size .sp .3
-
-
.. 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.
-
-
+============================================================================================
RMR 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
configuration of RMR when it is embedded by a *user
application* . RMR itself is a library, not a deployable
entity.
-
-Configuration
---------------------------------------------------------------------------------------------
-
+
+
+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
recognizes. Also see the main RMR manual page in the
development package for more details.
-
-RMR_ASYNC_CONN
-
- Allows the async connection mode to be turned off (by
- setting the value to 0). When set to 1, or missing from
- the environment, RMR will invoke the connection interface
- in the transport mechanism using the non-blocking (async)
- 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:
-
-
-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.
+ .. 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.
+
-
-
.. 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.
-
-
-RMR Developer Guide
============================================================================================
-
+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
This document contains information that developers need to
know to contribute to the RMR project.
-
-Language
---------------------------------------------------------------------------------------------
-
+
+
+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.
-
-Code Structure
---------------------------------------------------------------------------------------------
-
+
+
+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,
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.
+example, ``librmr_nng.a`` is the library generated for use
+with the NNG transport.
As such the library source is organised into multiple
components:
-
-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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+ .. 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
+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\_. This allows internal functions to
-have shorter names while still being meaningful.
-
-Coding Style
---------------------------------------------------------------------------------------------
-
+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
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
---------------------------------------------------------------------------------------------
-
+
+
+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
RIC Message Router -- RMR
==========================
-
.. toctree::
:maxdepth: 1
:caption: Documents:
+ :titlesonly:
- overview.rst
config-deploy.rst
user-guide.rst
developer-guide.rst
+ rt_tables.rst
.. toctree::
- :maxdepth: 2
+ :maxdepth: 1
:caption: Misc:
rel-notes.rst
:maxdepth: 1
:caption: Manual Pages:
+ rmr.7.rst
rmr_alloc_msg.3.rst
rmr_bytes2meid.3.rst
rmr_bytes2payload.3.rst
+++ /dev/null
-
-
-.. 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.
-
-
-
-RMR Overview
-============================================================================================
-
-
-RMR Library
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
-
-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.
-
-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
-
-
-
-Route Table Syntax
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The following illustrates the syntax for both types of route
-table entries.
-
-
-::
-
- newrt | start
- rte | <message-type>[,<sender-endpoint>] | <round-robin-grp>[;<round-robin-grp>]...
- mse | <message-type>[,<sender-endpoint>] | <sub-id> | <round-robin-grp>[;<round-robin-grp>]...
- 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 | <owner-endpoint> | <meid> [<meid>...]
- mme_del | <meid> [<meid>...]
- meid_map | end | <count> [| <md5sum>
-
-
-
-The <count> 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
-<owner-endpoint> 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 <md5sum> 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.
-
-
-
-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:
-
-
-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)
.. To make changes edit the source and recompile the document.
.. Do NOT make changes directly to .rst or .md files.
-
+============================================================================================
RMR Release Notes
============================================================================================
-
-The following is a list of release highlights for the core
-RMR library and wrappers which are housed in the same
-repository. These are extracted directly from the
-CHANGES_*.txt files at the repo root; please refer to those
-files for a completely up to date listing of API changes (as
-generated documents may lag).
-
-The RMR repo houses two distinct release entities: the core
-RMR package and the python wrapper package. To avoid naming
-conflicts (tags mostly) The core package uses odd major
-version numbers (e.g. 3.2.1) and the wrapper package uses
-even major version numbers. The release notes are split into
-two sections; please be sure to scroll to the section that is
-appropriate.
-
-Core RMR Changes
---------------------------------------------------------------------------------------------
-
-
-2020 May 06; version 4.0.5
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+RMR Release Notes
+=================
+
+The following is a list of release highlights for the RMR
+library. At one point in time the RMR repo also housed a
+wrapper library with a separate version and release cycle.
+This resulted in *leap frogging* versions for each package;
+the RMR core library was assigned odd major numbers (e.g.
+3.1.0). When the wrapper code was moved to a different repo
+the need to leap frog versions ceased, and beginning with
+version 4.0.0, the RMR versions should no longer skip.
+
+
+
+2020 May 06; version 4.0.5
+--------------------------
+
Fix the bug in SI95 receive message management semaphore
count issue. (RIC-355)
-
-2020 April 29; version 4.0.4
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 April 29; version 4.0.4
+----------------------------
+
Fix the traffic steering message type constants (again)
(RIC-342)
-
-2020 April 28; version 4.0.3
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 April 28; version 4.0.3
+----------------------------
+
Fix sonar flagged bugs (RIC-78)
-
-2020 April 24; version 4.0.2
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 April 24; version 4.0.2
+----------------------------
+
Correct bug in SI95 transport header length validation
(RIC-341)
-
-2020 April 22; version 4.0.1
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 April 22; version 4.0.1
+----------------------------
+
Correct message type constant for Traffic Steering
predication (RIC-342)
-
-2020 April 21; version 4.0.0
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 April 21; version 4.0.0
+----------------------------
+
The NNG based libraries are no longer included in the RMR
packages. This is considered a breaking change as NNG will
not be supported by default. It is still possible to build
necessary only for NNG and Nanomsg support. Its use should be
discontinued.
-
-2020 April 20; version 3.8.2
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 April 20; version 3.8.2
+----------------------------
+
Fix bug which was preventing an instance receiving dynamic
route table updates. (RIC-336)
-
-2020 April 20; version 3.8.1
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 April 20; version 3.8.1
+----------------------------
+
Add user guide which replaces the concatenation of man pages
(RIC-328)
-
-2020 April 17; version 3.8.0
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 April 17; version 3.8.0
+----------------------------
+
Add safe connect to avoid potential connect bug on Linux
(RIC-332)
Change debugging in route table collector to avoid possible
segment fault when in level 2 debug (RIC-335)
-
-2020 April 15; version 3.7.4
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 April 15; version 3.7.4
+----------------------------
+
Add missing message type to header file (RIC-334)
-
-2020 April 14; version 3.7.3
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 April 14; version 3.7.3
+----------------------------
+
Fix bug in rmr_call() when using SI95 (RIC-333)
-
-2020 April 10; version 3.7.2
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 April 10; version 3.7.2
+----------------------------
+
Fix bug related to static route table only mode (RIC-331)
-
-2020 April 9; version 3.7.1
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 April 9; version 3.7.1
+---------------------------
+
The max length restriction for receiving messages when using
SI95 has been removed. The length supplied during
initialisation is used as the "normal maximum" and default
buffer allocation size, but messages arriving which are
larger are accepted. (RIC-309)
-
-2020 April 7; version 3.7.0
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 April 7; version 3.7.0
+---------------------------
+
The health check support programme was renamed to rmr_probe
(RIC-308).
-
-2020 April 6; version 3.6.6
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 April 6; version 3.6.6
+---------------------------
+
Correct bug in SI95 address conversion module (RIC-327)
Correct bug in SI initialisation module
-
-2020 April 2; version 3.6.5
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 April 2; version 3.6.5
+---------------------------
+
Correct potential nil pointer use when examining interfaces
for use as a listen target (RIC-307)
-
-2020 April 1; version 3.6.4
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 April 1; version 3.6.4
+---------------------------
+
Correct potential nil pointer use in the NNG interface
(RIC-303) Correct issue preventing CI build without a
container
-
-2020 March 30; version 3.6.3
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 March 30; version 3.6.3
+----------------------------
+
Correct the max receive message size constant in rmr.h
(RIC-301)
-
-2020 March 23; version 3.6.2
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 March 23; version 3.6.2
+----------------------------
+
Fix message initialisation bug when pulling a message from
the pool (RIC-295)
-
-2020 March 19; version 3.6.1
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 March 19; version 3.6.1
+----------------------------
+
Fix problem with RPM package install
-
-2020 March 18; version 3.6.0
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 March 18; version 3.6.0
+----------------------------
+
Add message types to support traffic steering
-
-2020 March 16; version 3.5.2
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 March 16; version 3.5.2
+----------------------------
+
Correct bug in the meid table parser that prevented the
ack/nack of meid tables (RIC-273)
-
-2020 March 10; version 3.5.1
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 March 10; version 3.5.1
+----------------------------
+
Add missing health check message types.
-
-2020 March 9; version 3.5.0
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 March 9; version 3.5.0
+---------------------------
+
Added new wormhole send function: rmr_wh_call().
-
-2020 March 6; version 3.4.0
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 March 6; version 3.4.0
+---------------------------
+
Add new wormhole state function: rmr_wh_state().
-
-2020 March 5; Version 3.3.1
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 March 5; Version 3.3.1
+---------------------------
+
Correct several "bugs" identified by automatic code analysis.
-
-2020 March 4; Version 3.3.0
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 March 4; Version 3.3.0
+---------------------------
+
Add SI95 based unit testing Health check support binary added
(reason for minor bump)
-
-2020 February 26; version 3.2.5
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 February 26; version 3.2.5
+-------------------------------
+
Fix source address bug in SI95 receive/send funcitons. Fix
threading issues involving session disconnection in SI95
Remove unused SI95 status variable.
-
-2020 February 24; version 3.2.4
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 February 24; version 3.2.4
+-------------------------------
+
Fix meid bug (RIC-220) causing core dump.
-
-2020 February 21; version 3.2.3
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 February 21; version 3.2.3
+-------------------------------
+
Add meid routing support to the SI95 interface.
-
-2020 February 20; version 3.2.2
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 February 20; version 3.2.2
+-------------------------------
+
Fix receive thread related core dump (ring early unlock).
-
-2020 February 19; version 3.2.1
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 February 19; version 3.2.1
+-------------------------------
+
Added missing message types (E2-Setup)
-
-2020 February 18; version 3.2.0
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 February 18; version 3.2.0
+-------------------------------
+
Added support for new Route Manager and it's ability to
accept a request for table update.
-
-2020 February 14; version 3.1.3
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 February 14; version 3.1.3
+-------------------------------
+
Fix bug in SIsend which was causing a core dump in some cases
where the application attempted to send on a connection that
had disconnected. (RIC-207).
-
-2020 February 6; version 3.1.2
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 February 6; version 3.1.2
+------------------------------
+
Fix disconnection detection bug in interface to SI95.
-
-2020 January 31; verison 3.1.1
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 January 31; verison 3.1.1
+------------------------------
+
Allow route table thread logging to be completely disabled
when logging is turned off.
-
-2020 January 26; verison 3.1.0
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 January 26; verison 3.1.0
+------------------------------
+
First step to allowing the user programme to control messages
written to standard error. Introduces the rmr_set_vlevel()
function, and related environment variable.
-
-2020 January 24; verison 3.0.5
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 January 24; verison 3.0.5
+------------------------------
+
Fix bug in SI95 with receive buffer allocation.
-
-2020 January 23; verison 3.0.4
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 January 23; verison 3.0.4
+------------------------------
+
Fix bug in SI95 causing excessive CPU usage on poll.
-
-2020 January 22; verison 3.0.3
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 January 22; verison 3.0.3
+------------------------------
+
Enable thread support for multiple receive threads.
-
-2020 January 21; verison 3.0.2
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 January 21; verison 3.0.2
+------------------------------
+
Fix bug in SI95 (missing reallocate payload function).
-
-2020 January 20; verison 3.0.1
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 January 20; verison 3.0.1
+------------------------------
+
Enable support for dynamic route table updates via RMR
session.
-
-2020 January 16; version 3.0.0
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 January 16; version 3.0.0
+------------------------------
+
Introduce support for SI95 transport library to replace NNG.
(RMR library versions will use leading odd numbers to avoid
tag collisions with the wrapper tags which will use even
numbers.)
-
-2019 December 9; version 1.13.1
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2019 December 9; version 1.13.1
+-------------------------------
+
Correct documentation and missing rel-notes update for RTD.
-
-2019 December 6; version 1.13.0
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2019 December 6; version 1.13.0
+-------------------------------
+
Add ability to route messages based on the MEID in a message
combined with the message type/subscription-ID.
-
-2019 November 14; version 1.11.1 (Amber)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2019 November 14; version 1.11.1 (Amber)
+----------------------------------------
+
Fix bug in payload reallocation function; correct length of
payload was not always copied.
-
-2019 November 13; version 1.12.1
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2019 November 13; version 1.12.1
+--------------------------------
+
New message type constants added to support A1.
-
-2019 November 4; version 1.11.0 (Amber)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2019 November 4; version 1.11.0 (Amber)
+---------------------------------------
+
Version bump to move away from the 1.10.* to distinguish
between release A and the trial.
-
-2019 November 7; version 1.12.0
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2019 November 7; version 1.12.0
+-------------------------------
+
Version cut to support continued development for next release
preserving the 1.11.* versions for release 1 (Amber) and
related fixes.
-
-2019 October 31; version 1.10.2
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2019 October 31; version 1.10.2
+-------------------------------
+
Provide the means to increase the payload size of a received
message without losing the data needed to use the
rmr_rts_msg() funciton.
-
-2019 October 21; version 1.10.1
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2019 October 21; version 1.10.1
+-------------------------------
+
Fix to prevent null message buffer from being returned by the
timeout receive function if the function is passed one to
reuse.
-
-2019 October 21; version 1.10.1
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2019 October 21; version 1.10.1
+-------------------------------
+
Add periodic dump of send count info to stderr.
-
-2019 September 27; version 1.9.0
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2019 September 27; version 1.9.0
+--------------------------------
+
Python bindings added receive all queued function and
corrected a unit test
-
-2019 September 25; version 1.8.3
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2019 September 25; version 1.8.3
+--------------------------------
+
Correct application level test issue causing timing problems
during jenkins verification testing at command and merge
Handle the NNG connection shutdown status which may now be
generated when a connection throug a proxy is reset.
-
-2019 September 25; version 1.8.2
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2019 September 25; version 1.8.2
+--------------------------------
+
Correct bug in rmr_torcv_msg() when timeout set to zero (0).
-
-2019 September 19; version 1.8.1
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2019 September 19; version 1.8.1
+--------------------------------
+
Correct missing constant for wrappers.
-
-2019 September 19; version 1.8.0
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2019 September 19; version 1.8.0
+--------------------------------
+
New message types added: RAN_CONNECTED, RAN_RESTARTED,
RAN_RECONFIGURED
-
-2019 September 17; version 1.7.0
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2019 September 17; version 1.7.0
+--------------------------------
+
Initial connection mode now defaults to asynchronous. Set
RMR_ASYNC_CONN=0 in the environment before rmr_init() is
invoked to revert to synchronous first TCP connections.
(Recovery connection attempts have always been asynchronous).
-
-2019 September 3; version 1.6.0
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2019 September 3; version 1.6.0
+-------------------------------
+
Fix bug in the rmr_rts_msg() function. If a return to sender
message failed, the source IP address was not correctly
adjusted and could cause the message to be "reflected" back
return a response to the sender. If this environment variable
is not present, the host name (original behaviour) is used.
-
-2019 August 26; version 1.4.0
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2019 August 26; version 1.4.0
+-----------------------------
+
New message types were added.
-
-2019 August 16; version 1.3.0
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2019 August 16; version 1.3.0
+-----------------------------
+
New mesage types added.
-
-2019 August 13; version 1.2.0 (API change, non-breaking)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2019 August 13; version 1.2.0 (API change, non-breaking)
+--------------------------------------------------------
+
The function rmr_get_xact() was added to proide a convenient
way to extract the transaction field from a message.
-
-2019 August 8; version 1.1.0 (API change)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2019 August 8; version 1.1.0 (API change)
+-----------------------------------------
+
This change should be backward compatable/non-breaking A new
field has been added to the message buffer (rmr_mbuf_t). This
field (tp_state) is used to communicate the errno value that
to access errno and this provides the value to them. See the
rmr_alloc_msg manual page for more details.
-
-2019 August 6; version 1.0.45 (build changes)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2019 August 6; version 1.0.45 (build changes)
+---------------------------------------------
+
Support for the Nanomsg transport library has been dropped.
The library librmr.* will no longer be included in packages.
file was generated on a Linux flavour that has a different
preference than the one where the package is installed.
-
-2019 August 6; version 1.0.44 (API change)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2019 August 6; version 1.0.44 (API change)
+------------------------------------------
+
Added a new message type constant.
-
-2019 July 15; Version 1.0.39 (bug fix)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2019 July 15; Version 1.0.39 (bug fix)
+--------------------------------------
+
Prevent unnecessary usleep in retry loop.
-
-2019 July 12; Version 1.0.38 (API change)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2019 July 12; Version 1.0.38 (API change)
+-----------------------------------------
+
Added new message types to RIC_message_types.h.
-
-2019 July 11; Version 1.0.37
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2019 July 11; Version 1.0.37
+----------------------------
+
librmr and librmr_nng - Add message buffer API function
rmr_trace_ref() (see rmr_trace_ref.3 manual page in dev
package).
-
-Wrapper Changes
---------------------------------------------------------------------------------------------
-
-
-2020 April 8; Version n/a
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 April 8; Version n/a
+-------------------------
+
RMR Python moved to Python Xapp Framework
(https://gerrit.o-ran-sc.org/r/admin/repos/ric-plt/xapp-frame-py)
-
-2020 February 29; Version 2.4.0
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 February 29; Version 2.4.0
+-------------------------------
+
Add consolidated testing under CMake Add support binary for
health check (SI95 only)
-
-2020 February 28; Version 2.3.6
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+2020 February 28; Version 2.3.6
+-------------------------------
+
Fix bug in Rt. Mgr comm which prevented table ID from being
sent on ack message (RIC-232).
--- /dev/null
+.. 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
+===========
+
+
+
+NAME
+----
+
+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.
+
+
+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
+
+
+
+Route Table Syntax
+------------------
+
+The following illustrates the syntax for both types of route
+table entries.
+
+
+::
+
+ newrt | start
+ rte | <message-type>[,<sender-endpoint>] | <round-robin-grp>[;<round-robin-grp>]...
+ mse | <message-type>[,<sender-endpoint>] | <sub-id> | <round-robin-grp>[;<round-robin-grp>]...
+ 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 | <owner-endpoint> | <meid> [<meid>...]
+ mme_del | <meid> [<meid>...]
+ meid_map | end | <count> | <md5sum>
+
+
+The <count> 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
+<owner-endpoint> 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 <md5sum> 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.
+
+
+
+
+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)
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_alloc_msg
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
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
+
+
+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
+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 managerment (e.g. malloc) functions
+underlying system memory management (e.g. malloc) functions
may impose a limit.
The *ctx* parameter is the void context pointer that was
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.
+is described in ``rmr.h,`` and is illustrated below.
::
-
+
typedef struct {
int state;
int mtype;
} rmr_mbuf_t;
-
-
-
-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.
-
-ERRORS
---------------------------------------------------------------------------------------------
-
-
-
-ENOMEM
-
- Unable to allocate memory.
-
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+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.
+
+
+ERRORS
+------
+
+
+ .. 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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_bytes2meid
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
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
+
+
+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.
-
-RETURN VALUE
---------------------------------------------------------------------------------------------
-
+
+
+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.
-
-ERRORS
---------------------------------------------------------------------------------------------
-
+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.
-
-
-
-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
---------------------------------------------------------------------------------------------
-
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+``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
+-------
+
+
+
+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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_bytes2payload
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
void rmr_bytes2payload( rmr_mbuf_t* mbuf, unsigned char* src, int len )
-
-
-DESCRIPTION
---------------------------------------------------------------------------------------------
-
+
+
+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
+``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
---------------------------------------------------------------------------------------------
-
+
+
+RETURN VALUE
+------------
+
None.
-
-EXAMPLE
---------------------------------------------------------------------------------------------
-
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+
+
+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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_bytes2xact
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
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.
-
-
-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.
-
-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.
-
-
-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
---------------------------------------------------------------------------------------------
-
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+
+
+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.
+
+
+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.
+
+
+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.
+
+
+
+
+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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_call
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
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
+
+
+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
+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
+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
-non-time mechanism for *timeout* prevents the async queue
-from filling (which would lead to message drops) in an
-environment where there is heavy message traffic.
+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 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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+Retries
+-------
+
The send operations in RMR will retry *soft* send failures
until one of three conditions occurs:
-
-1.
-
- The message is sent without error
-
-
-2.
-
- The underlying transport reports a *hard* failure
-
-
-3.
-
- The maximum number of retry loops has been attempted
+ &item The message is sent without error
+
+ &item The underlying transport reports a *hard* failure
+
+ &item The maximum number of retry loops has been attempted
A retry loop consists of approximately 1000 send attempts
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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+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
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.
-
-ERRORS
---------------------------------------------------------------------------------------------
-
+
+
+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.
+
+
+ERRORS
+------
+
These values are reflected in the state field of the returned
message.
-
-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.
+ .. 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
successful.
-
-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
---------------------------------------------------------------------------------------------
-
+ .. 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
+``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
---------------------------------------------------------------------------------------------
-
+
+
+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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_close
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
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.
-
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+
+
+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.
+
+
+
+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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_free_msg
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
void rmr_free_msg( rmr_mbuf_t* mbuf );
-
-
-DESCRIPTION
---------------------------------------------------------------------------------------------
-
+
+
+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.
+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
---------------------------------------------------------------------------------------------
-
+
+
+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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_get_const
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
unsigned char* rmr_get_const();
-
-
-DESCRIPTION
---------------------------------------------------------------------------------------------
-
-The rmr_get_const function is a convenience function for
+
+
+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.
+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_NOENDPT" "2"
}
-
-
-RETURN VALUE
---------------------------------------------------------------------------------------------
-
+
+
+RETURN VALUE
+------------
+
On success, a pointer to a string containing the JSON
defining constant and value pairs. On failure a nil pointer
is returned.
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+
+
+SEE ALSO
+--------
+
rmr(7)
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_get_meid
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
char* rmr_get_meid( rmr_mbuf_t* mbuf, unsigned char* dest )
-
-
-DESCRIPTION
---------------------------------------------------------------------------------------------
-
-The rmr_get_meid function will copy the managed entity ID
+
+
+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,
+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
---------------------------------------------------------------------------------------------
-
+
+
+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.
-
-ERRORS
---------------------------------------------------------------------------------------------
-
-If an error occurs, the value of the global variable errno
-will be set to one of the following with the indicated
-meaning.
-
-
-
-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
---------------------------------------------------------------------------------------------
-
+
+
+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().
+
+
+
+
+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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_get_rcvfd
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
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
+
+
+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().
-
-RETURN VALUE
---------------------------------------------------------------------------------------------
-
-The rmr_get_rcvfd function returns a file descriptor greater
-or equal to 0 on success and -1 on error.
-
-ERRORS
---------------------------------------------------------------------------------------------
-
+
+
+RETURN VALUE
+------------
+
+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.
-
-EINVAL
-
- The use of this function is invalid in this environment.
-
-
-EXAMPLE
---------------------------------------------------------------------------------------------
-
+ .. 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 <stdio.h>
#include <stdlib.h>
#include <sys/epoll.h>
#include <rmr/rmr.h>
+
int main() {
int rcv_fd; // pollable fd
void* mrc; //msg router context
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
// do something with msg
}
}
+
// check for other ready fds....
}
}
}
-
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+
+
+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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_get_src
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
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.
+
+
+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.
-
-RETURN VALUE
---------------------------------------------------------------------------------------------
-
+
+
+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.
-
-ERRORS
---------------------------------------------------------------------------------------------
-
-If an error occurs, the value of the global variable errno
-will be set to one of the following with the indicated
-meaning.
-
-
-
-EINVAL
-
- The message, or an internal portion of the message, was
- corrupted or the pointer was invalid.
-
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+
+
+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.
+
+
+
+
+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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_get_srcip
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
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.
+
+
+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
that the buffer supplied is large enough, and to protect
against future RMR enhancements which might increase the
address buffer size requirement.
-
-RETURN VALUE
---------------------------------------------------------------------------------------------
-
+
+
+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.
-
-ERRORS
---------------------------------------------------------------------------------------------
-
-If an error occurs, the value of the global variable errno
-will be set to one of the following with the indicated
-meaning.
-
-
-
-EINVAL
-
- The message, or an internal portion of the message, was
- corrupted or the pointer was invalid.
-
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+
+
+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.
+
+
+
+
+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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_get_trace
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
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).
-
-RETURN VALUE
---------------------------------------------------------------------------------------------
-
+
+
+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).
+
+
+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.
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+
+
+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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_get_trlen
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
int rmr_get_trlen( rmr_mbuf_t* msg );
-
-
-DESCRIPTION
---------------------------------------------------------------------------------------------
-
+
+
+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.
-
-RETURN VALUE
---------------------------------------------------------------------------------------------
-
+
+
+RETURN VALUE
+------------
+
The number of bytes allocated for trace information in the
given message.
-
-ERRORS
---------------------------------------------------------------------------------------------
-
-
-
-INVAL
-
- Parameter(s) passed to the function were not valid.
-
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+
+
+ERRORS
+------
+
+
+ .. 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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_get_xact
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
char* rmr_get_xact( rmr_mbuf_t* mbuf, unsigned char* dest )
-
-
-DESCRIPTION
---------------------------------------------------------------------------------------------
-
-The rmr_get_xact function will copy the transaction field
+
+
+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).
-
-RETURN VALUE
---------------------------------------------------------------------------------------------
-
+``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.
-
-ERRORS
---------------------------------------------------------------------------------------------
-
-If an error occurs, the value of the global variable errno
-will be set to one of the following with the indicated
-meaning.
-
-
-
-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
---------------------------------------------------------------------------------------------
-
+
+
+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().
+
+
+
+
+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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_init
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
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.
+
+
+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
footprint.
*Flags* allows for selection of some RMR options at the time
-of initialisation. These are set by ORing RMRFL constants
+of initialisation. These are set by ORing ``RMRFL`` constants
from the RMR header file. Currently the following flags are
supported:
-
-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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+ .. 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
+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
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
+-----------
+
+As a part of the initialisation process ``rmr_init`` reads
environment variables to configure itself. The following
variables are used if found.
-
-RMR_ASYNC_CONN
-
- Allows the async connection mode to be turned off (by
- setting the value to 0). When set to 1, or missing from
- the environment, RMR will invoke the connection interface
- in the transport mechanism using the non-blocking (async)
- 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:
-
-
-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.
-
-ERRORS
---------------------------------------------------------------------------------------------
-
+ .. 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.
+
+
+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.
-
-ENOMEM
-
- Unable to allocate memory.
-
-
-EXAMPLE
---------------------------------------------------------------------------------------------
-
+ .. 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 );
-
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+
+
+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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_init_trace
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
void* rmr_init_trace( void* ctx )
-
-
-DESCRIPTION
---------------------------------------------------------------------------------------------
-
-The rmr_init_trace function establishes the default trace
+
+
+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.
+``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().
+``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
---------------------------------------------------------------------------------------------
-
+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.
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+
+
+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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_mt_call
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
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.
+
+
+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
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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+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
+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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+Retries
+-------
+
The send operations in RMR will retry *soft* send failures
until one of three conditions occurs:
-
-1.
-
- The message is sent without error
-
-
-2.
-
- The underlying transport reports a *hard* failure
-
-
-3.
-
- The maximum number of retry loops has been attempted
+ &item The message is sent without error
+
+ &item The underlying transport reports a *hard* failure
+
+ &item The maximum number of retry loops has been attempted
A retry loop consists of approximately 1000 send attempts
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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+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
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
+
+
+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
+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
---------------------------------------------------------------------------------------------
-
+
+
+ERRORS
+------
+
These values are reflected in the state field of the returned
message.
-
-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.
+ .. 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
successful.
-
-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.
+ .. 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
-
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+
+
+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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_mt_rcv
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
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.
+
+
+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
*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
---------------------------------------------------------------------------------------------
-
+
+
+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
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
---------------------------------------------------------------------------------------------
-
+
+
+ERRORS
+------
+
The *state* field in the message buffer will be set to one of
the following values:
-
-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.
+ .. 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:
-
-
-
-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
---------------------------------------------------------------------------------------------
-
+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;
printf( "receive timeout (nil)\\n" );
}
-
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+
+
+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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_payload_size
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
int rmr_payload_size( rmr_mbuf_t* msg );
-
-
-DESCRIPTION
---------------------------------------------------------------------------------------------
-
+
+
+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.
-
-RETURN VALUE
---------------------------------------------------------------------------------------------
-
+
+
+RETURN VALUE
+------------
+
The number of bytes available in the payload.
-
-ERRORS
---------------------------------------------------------------------------------------------
-
-
-
-INVAL
-
- Parameter(s) passed to the function were not valid.
-
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+
+
+ERRORS
+------
+
+
+ .. 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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_rcv_msg
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
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.
-
-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.
-
-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
+
+
+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.
+
+
+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.
+
+
+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:
-
-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
+ .. 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:
-
-
-
-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
---------------------------------------------------------------------------------------------
-
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+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
+-------
+
+
+
+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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_ready
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
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.
-
-RETURN VALUE
---------------------------------------------------------------------------------------------
-
+
+
+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.
+
+
+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.
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+
+
+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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_realloc_payload
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
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
+
+
+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.
-
-Cloning The Message Buffer
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+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.
-
-Message Buffer Metadata
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+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.
-
-RETURN VALUE
---------------------------------------------------------------------------------------------
-
-The rmr_realloc_payload function returns a pointer to the
+
+
+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
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
---------------------------------------------------------------------------------------------
-
+
+
+ERRORS
+------
+
These value of *errno* will reflect the error condition if a
nil pointer is returned:
-
-ENOMEM
-
- Memory allocation of the new payload failed.
-
-
-EINVAL
-
- The pointer passed in was nil, or refrenced an invalid
- message, or the required length was not valid.
-
-
-EXAMPLE
---------------------------------------------------------------------------------------------
-
+ .. 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
::
-
+
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 ) {
// populate and send ack message
}
}
+
-
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+
+
+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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_rts_msg
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
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
+
+
+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.
-
-Retries
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+as ``rmr_send_msg.``
+
+
+Retries
+-------
+
The send operations in RMR will retry *soft* send failures
until one of three conditions occurs:
-
-1.
-
- The message is sent without error
-
-
-2.
-
- The underlying transport reports a *hard* failure
-
-
-3.
-
- The maximum number of retry loops has been attempted
+ &item The message is sent without error
+
+ &item The underlying transport reports a *hard* failure
+
+ &item The maximum number of retry loops has been attempted
A retry loop consists of approximately 1000 send attempts
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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+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
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
---------------------------------------------------------------------------------------------
-
+
+
+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
by this function, the *rmr_realloc_payload()* function must
be used to extend the payload to a size suitable for the
response.
-
-RETURN VALUE
---------------------------------------------------------------------------------------------
-
+
+
+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.
+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
+``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.
+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
+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
---------------------------------------------------------------------------------------------
-
+
+
+ERRORS
+------
+
The following values may be passed back in the *state* field
of the returned message buffer.
-
-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.
-
-
-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
---------------------------------------------------------------------------------------------
-
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+ .. 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
+-------
+
+
+
+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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_send_msg
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
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
+
+
+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.)
-
-Retries
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+Retries
+-------
+
The send operations in RMR will retry *soft* send failures
until one of three conditions occurs:
-
-1.
-
- The message is sent without error
-
-
-2.
-
- The underlying transport reports a *hard* failure
-
-
-3.
-
- The maximum number of retry loops has been attempted
+ &item The message is sent without error
+
+ &item The underlying transport reports a *hard* failure
+
+ &item The maximum number of retry loops has been attempted
A retry loop consists of approximately 1000 send attempts
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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+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
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
---------------------------------------------------------------------------------------------
-
+
+
+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.
+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
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
+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.
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
---------------------------------------------------------------------------------------------
-
+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.
-
-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.
-
-
-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.
+ .. 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 OK;
+
-
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+
+
+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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_set_fack
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
void rmr_set_fack( void* vctx );
+
-
-
-DESCRIPTION
---------------------------------------------------------------------------------------------
-
-The rmr_set_fack function enables *fast TCP acknowledgements*
-if the underlying transport library supports it. This might
-be useful for applications which must send messages at a
-maximum rate.
-
-RETURN VALUE
---------------------------------------------------------------------------------------------
-
+
+
+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.
+
+
+RETURN VALUE
+------------
+
There is no return value.
-
-ERRORS
---------------------------------------------------------------------------------------------
-
+
+
+ERRORS
+------
+
This function does not generate any errors.
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+
+
+SEE ALSO
+--------
+
rmr_init(3),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_set_stimeout
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
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
+
+
+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
loop; a small, 1 mu-sec, sleep is executed between loop sets
if the *rloops* value is greater than 1.
-
-Disabling Retries
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+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
RMR send operations will attempt a send operation only
**once,** returning immediately to the caller with the state
of that single attempt.
-
-RETURN VALUE
---------------------------------------------------------------------------------------------
-
+
+
+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.
-
-ERRORS
---------------------------------------------------------------------------------------------
-
+
+
+ERRORS
+------
+
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.
+
+
+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
}
+
-
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+
+
+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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_set_trace
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
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.
-
-RETURN VALUE
---------------------------------------------------------------------------------------------
-
-The rmr_set_trace function returns the number of bytes
+
+
+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.
+
+
+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.
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+
+
+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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_set_vlevel
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
#include <rmr/rmr_logging.h>
+
void rmr_set_vlevel( int new_level )
-
-
-DESCRIPTION
---------------------------------------------------------------------------------------------
-
-The rmr_set_vlevel allows the user programme to set the
+
+
+DESCRIPTION
+-----------
+
+The ``rmr_set_vlevel`` allows the user programme to set the
verbosity level which is used to determine the messages RMR
-writes to standard error. The new_vlevel value must be one of
-the following constants which have the indicated meanings:
-
-
-RMR_VL_OFF
-
- Turns off all message writing. This includes the stats and
- debugging messages generated by the route collector thread
- which are normally affected only by the externally managed
- verbose level file (and related environment variable).
-
-
-RMR_VL_CRIT
-
- Write only messages of critical importance. From the point
- of view of RMR, when a critical proper behaviour of the
- library cannot be expected or guaranteed.
-
-RMR_VL_ERR
-
- Include error messages in the output. An error is an event
- from which RMR has no means to recover. Continued proper
- execution is likely except where the affected connection
- and/or component mentioned in the error is concerned.
-
-RMR_VL_WARN
-
- Include warning messages in the output. A warning
- indicates an event which is not considered to be normal,
- but is expected and continued acceptable behaviour of the
- system is assured.
-
-RMR_VL_INFO
-
- Include informational messagees in the output.
- Informational messages include some diagnostic information
- which explain the activities of RMR.
-
-RMR_VL_DEBUG
-
- Include all debugging messages in the output. Debugging
- must have also been enabled during the build as a
- precaution to accidentally enabling this level of output
- as it can grossly affect performance.
+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
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
---------------------------------------------------------------------------------------------
-
+
+
+SEE ALSO
+--------
+
rmr_init(3)
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_str2meid
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
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
+
+
+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.)
-
-RETURN VALUE
---------------------------------------------------------------------------------------------
-
+``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.
-
-ERRORS
---------------------------------------------------------------------------------------------
-
+
+
+ERRORS
+------
+
If the return value is not RMR_OK, then it will be set to one
of the values below.
-
-
-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
---------------------------------------------------------------------------------------------
-
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+ .. 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
+-------
+
+
+
+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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_str2xact
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
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
+
+
+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.)
-
-
-RETURN VALUE
---------------------------------------------------------------------------------------------
-
+``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.
-
-ERRORS
---------------------------------------------------------------------------------------------
-
-If the return value is not RMR_OK, then it will be set to
-one of the values below.
-
-
-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
---------------------------------------------------------------------------------------------
-
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+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.
+
+
+
+
+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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
RMR support functions
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
#include <rmr/ring_inline.h>
+
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
---------------------------------------------------------------------------------------------
-
+
+
+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
+``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
+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
+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_mk_ring`` function creates a buffer ring with
+*size* entries.
-The rmr_ring_free function accepts a pointer to a ring
+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
+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 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
+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
caller should use the system stat function call to make that
determination.
-The rmr_has_str function returns 1 if *buf* contains the
+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.
+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_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_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
+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
+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:
-
-
-INVAL
-
- Parameter(s) passed to the function were not valid.
-
-
-EXAMPLE
---------------------------------------------------------------------------------------------
-
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+
+
+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.
+
+
+
+
+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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_torcv_msg
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
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*
+
+
+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
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.
-
-ERRORS
---------------------------------------------------------------------------------------------
-
+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.
+
+
+ERRORS
+------
+
The *state* field in the message buffer will be one of the
following:
-
-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 intialise, the poll
- mechansim, 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.
-
-
-
-
-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
---------------------------------------------------------------------------------------------
-
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+ .. 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
+-------
+
+
+
+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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_trace_ref
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
int rmr_trace_ref( rmr_mbuf_t* mbuf, int* sizeptr )
-
-
-DESCRIPTION
---------------------------------------------------------------------------------------------
-
-The rmr_trace_ref function returns a pointer to the trace
+
+
+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.
-
-RETURN VALUE
---------------------------------------------------------------------------------------------
-
+
+
+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.
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+
+
+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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_tralloc_msg
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
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
+
+
+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
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.
+is described in ``rmr.h,`` and is illustrated below.
::
-
+
typedef struct {
int state;
int mtype;
} rmr_mbuf_t;
-
-
-
-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.
-
-ERRORS
---------------------------------------------------------------------------------------------
-
-
-
-ENOMEM
-
- Unable to allocate memory.
-
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+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.
+
+
+ERRORS
+------
+
+
+ .. 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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_wh_call
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
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
+
+
+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.
+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
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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+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:
-
-1.
-
- The message is sent without error
-
-
-2.
-
- The underlying transport reports a *hard* failure
-
-
-3.
-
- The maximum number of retry loops has been attempted
+ &item The message is sent without error
+
+ &item The underlying transport reports a *hard* failure
+
+ &item The maximum number of retry loops has been attempted
A retry loop consists of approximately 1000 send attempts
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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+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
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
---------------------------------------------------------------------------------------------
-
+
+
+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.
+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
+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
---------------------------------------------------------------------------------------------
-
+
+
+ERRORS
+------
+
The following values may be passed back in the *state* field
of the returned message buffer.
-
-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
---------------------------------------------------------------------------------------------
-
+ .. 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.
+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 <rmr/rmr.h> // system headers omitted for clarity
+
int main() {
rmr_whid_t whid = -1; // wormhole id for sending
void* mrc; //msg router context
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
}
}
}
+
sleep( 5 );
}
}
-
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+
+
+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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_wh_close
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
void rmr_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.
+
+
+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.
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+
+
+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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_wh_open
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
void* 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
+
+
+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.
+function), and that the ID returned by ``rmr_wh_open`` be
+passed to the ``rmr_wh_send_msg`` function.
*Target* is the *name* or *IP-address* combination of the
-processess that the wormhole should be connected to. *Vctx*
-is the RMR void context pointer that was returned by the
-rmr_init function.
-
-When invoked, this function immediatly attempts to connect to
-the target process. If the connection cannot be established,
-an error is returned to the caller, and no direct messages
-can be sent to the target. Once a wormhole is connected, the
-underlying transport mechanism (e.g. NNG) will provide
-reconnects should the connection be lost, however the
+processes that the wormhole should be connected to. *Vctx* is
+the RMR void context pointer that was returned by the
+``rmr_init`` function.
+
+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 esablished and that the ID is valid.
-
-ERRORS
---------------------------------------------------------------------------------------------
-
+
+
+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.
+
+
+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.
-
-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
---------------------------------------------------------------------------------------------
-
+ .. 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 ) ) {
strerror( errno ) );
}
-
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+
+
+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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_wh_send_msg
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
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
+
+
+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
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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+Retries
+-------
+
The send operations in RMR will retry *soft* send failures
until one of three conditions occurs:
-
-1.
-
- The message is sent without error
-
-
-2.
-
- The underlying transport reports a *hard* failure
-
-
-3.
-
- The maximum number of retry loops has been attempted
+ &item The message is sent without error
+
+ &item The underlying transport reports a *hard* failure
+
+ &item The maximum number of retry loops has been attempted
A retry loop consists of approximately 1000 send attempts
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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+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
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
---------------------------------------------------------------------------------------------
-
+
+
+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.
+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
+``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.
+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
+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
---------------------------------------------------------------------------------------------
-
+
+
+ERRORS
+------
+
The following values may be passed back in the *state* field
of the returned message buffer.
-
-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.
-
-
-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
---------------------------------------------------------------------------------------------
-
+ .. 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.
+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 <rmr/rmr.h> // system headers omitted for clarity
+
int main() {
rmr_whid_t whid = -1; // wormhole id for sending
void* mrc; //msg router context
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
sbuf = rmr_wh_send_msg( mrc, whid, sbuf );
}
}
+
sleep( 5 );
}
}
-
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+
+
+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),
-
-
.. 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
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_wh_state
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
int rmr_wh_state( void* vctx, rmr_whid_t whid )
-
-
-DESCRIPTION
---------------------------------------------------------------------------------------------
-
-The rmr_wh_state function will return the current state of
-the connection associated with the given wormhole (whid). The
-return value indicates whether the connection is open
+
+
+DESCRIPTION
+-----------
+
+The ``rmr_wh_state`` function will return the current state
+of the connection associated with the given wormhole (whid).
+The return value indicates whether the connection is open
(RMR_OK), or closed (any other return value).
When using some transport mechanisms (e.g. NNG), it may not
be possible for RMR to know the actual state and the
connection may always be reported as "open."
-
-RETURN
---------------------------------------------------------------------------------------------
-
+
+
+RETURN
+------
+
The following values are potential return values.
-
-RMR_OK
-
- The wormhole ID is valid and the connection is "open."
-
-
-RMR_ERR_WHID
-
- THe wormhole ID passed into the function was not valid.
-
-
-RMR_ERR_NOENDPT
-
- The wormhole is not open (not connected).
-
-
-RMR_ERR_BADARG
-
- The context passed to the function was nil or invalid.
-
-
-RMR_ERR_NOWHOPEN
-
- Wormholes have not been initialised (no wormhole open call
- has been made).
-
-
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+ .. 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)
--- /dev/null
+.. 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.
+
+
+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.
+
+
+::
+
+ 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.
+
+
+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:
+
+
+::
+
+ rte | <msg-type>[,<sender-endpoint>] | <endpoint-group>[;<endpoint-group>;...]
+ mse | <msg-type>[,<sender-endpoint>] | <sub-id> | <endpoint-group>[;<endpoint-group>;...]
+
+
+Where:
+
+
+ .. list-table::
+ :widths: 25,70
+ :header-rows: 0
+ :class: borderless
+
+ * - **mse, rte**
+ -
+ is the table entry type
+
+ * - **<msg-type>**
+ -
+ is the integer message type
+
+ * - **<sender-endpoint>**
+ -
+ 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.
+
+ * - **<sub-id>**
+ -
+ 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.
+
+ * - **<endpoint-group>**
+ -
+ is one or more, comma separated, endpoint descriptions.
+
+
+space 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 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.
+
+
+::
+
+ 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.
+
+
+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.
+
+
+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).
+
+
+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).
+
+
+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.
+
+
+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.
+
+
+Table Request
+-------------
+
+During initialisation, RMR will establish 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 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 "<id-missing>." 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.
+
+
+Providing A Static Table
+========================
+
+For testing, or possibly bootstrapping purposes, a static
+route table can be supplied. During initialisation, RMR will
+check the ``RMR_SEED_RT`` environment variable. If it exists,
+and references a file, RMR will open and read the file
+expecting to find a static route table. This route table is
+used until an update is received from a *Route Manager*.
+Normally, when the RMR initialisation function is invoked, a
+listener is started to receive route table information from a
+route manager process. During testing it is often useful to
+supply a static table which is available should no route
+management process exist, or to provide a seed table to use
+before the first table is delivered. The environment variable
+``RMR_SEED_RT`` can be set to provide the RMR initialisation
+function with the name of the static table to use. If a
+static table is provided, it will be loaded only once, and
+will be overlaid if a dynamically delivered table is
+received.
+
+
+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.
+
+
+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 | <table-id>
+ mme_ar | <owner-endpoint> | <meid> [<meid>...]
+ mme_del | <meid> [<meid>...]
+ meid_map | end | <count> [| <md5sum> ]
+
+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 <owner-endpoint> 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 <count> is the number of add/replace and
+delete records which were sent; if RMR does not match the
+<count> 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 <md5sum> 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.
+
+
+
+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
+ *message 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.
+
+ * - **Messgae 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 *message 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. &Term 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.
+
+
+
-
-
.. 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.
-
============================================================================================
-RIC Message Router -- RMR
+User's Guide
============================================================================================
--------------------------------------------------------------------------------------------
-User's Manual
+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.
+
+
+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.
-Purpose
---------------------------------------------------------------------------------------------
+
+
+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.
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
---------------------------------------------------------------------------------------------
-
+
+
+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
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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+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
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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+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
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
---------------------------------------------------------------------------------------------
-
+
+
+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
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
-============================================================================================
-
+
+
+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.
-
-Initialisation
---------------------------------------------------------------------------------------------
-
-The RMR function 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.
+
+
+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
an environment variable as this value is likely determined by
the mechanism which is starting and configuring the
application.
-
-The RMR Context
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+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.
-
-Wait For Ready
---------------------------------------------------------------------------------------------
-
+
+
+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 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
---------------------------------------------------------------------------------------------
-
+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 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)
+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
+-------------------
+
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.
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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+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
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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+Sender Information
+------------------
+
The source, or sender information, is indirectly available to
-the application via the and functions. The former returns a
-string containing hostname:port, while the string ip:port is
-returned by the latter.
-
-Transaction ID
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+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
-function is used to send a message.
-
-Trace Information
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+``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.
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 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
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 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.
+
+
+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 or to be
-sent or returned to the sender.
-
-Populating the Message Buffer
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+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.
-
-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
- function.
-
-
-trace data
-
- Optionally, the application may add trace information to
- the message buffer.
-
-
-
-Sending a Message Buffer
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+ .. 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
-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.)
+``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
+``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
+``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
-============================================================================================
-
+
+
+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.
-
-The Call Function
---------------------------------------------------------------------------------------------
-
-The RMR function 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, 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. Similarly,
+
+
+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 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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+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 that the application
-must send a message and guarantee that RMR routes it to an
-exact destination. To enable this, RMR provides the 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
-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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+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
-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 function[2].
+``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 calls.
+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
-
-Wormholes
---------------------------------------------------------------------------------------------
-
+``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
functions which provide wormhole communications:
-
-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
-============================================================================================
-
+ .. 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
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
---------------------------------------------------------------------------------------------
-
+
+
+Failure Notification
+--------------------
+
When a soft failure is reported, the returned message buffer
-returned by the RMR function will be RMR_ERR_RETRY. These
+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.
-
+* 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
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
---------------------------------------------------------------------------------------------
-
+
+
+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.
-
-RMR Retry Modes
---------------------------------------------------------------------------------------------
-
+
+
+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
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 with a value of 0; this can be done once immediately
-after is invoked.
+``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
immediately, or dropping the send attempt all together. As
stated before, only the application can determine how to best
handle send failures.
-
-Other 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. and a brief
-description of their meaning.
-
-
-
-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
+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
-============================================================================================
-
+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
the container management system. The following paragraphs
briefly discuss these.
-
-TCP Ports
---------------------------------------------------------------------------------------------
-
+
+
+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
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
---------------------------------------------------------------------------------------------
-
+
+
+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.
-
-Environment Variables
---------------------------------------------------------------------------------------------
-
+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
recognises:
-
-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
---------------------------------------------------------------------------------------------
-
+ .. 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:
-
-[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.
-
-
-
-_____________________________________________________________
-
-[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.
-
-
-
-[2] There is additional overhead to support multi-threaded
-call as a special listener thread must be used in order to
-deliver responses to the proper application thread.
-
-
-
-
-
-
-Appendix A -- Quick Reference
-============================================================================================
-
+ .. 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.
+
+
+
+
+
+
+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
-
-Appendix B -- Message Buffer Details
-============================================================================================
-
+
+
+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
+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
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 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.
+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
- int len; // length of data in the payload (send or received)
- unsigned char* payload; // transported data
- 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)
- unsigned char* id; // if we need an ID in the message separate from the xaction id
- int flags; // various MFL_ (private) flags as needed
- int alloc_len; // the length of the allocated space (hdr+payload)
- void* ring; // ring this buffer should be queued back to
- 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
---------------------------------------------------------------------------------------------
+
+ typedef struct {
+ int state; // state of processing
+ int mtype; // message type
+ int len; // length of data in the payload (send or received)
+ unsigned char* payload; // transported data
+ 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)
+ unsigned char* id; // if we need an ID in the message separate from the xaction id
+ int flags; // various MFL_ (private) flags as needed
+ int alloc_len; // the length of the allocated space (hdr+payload)
+ void* ring; // ring this buffer should be queued back to
+ 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.
+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
---------------------------------------------------------------------------------------------
-
+``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
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
---------------------------------------------------------------------------------------------
-
+
+
+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 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
-============================================================================================
-
+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 this document are RMR
-specific. The following definitions are the meanings of terms
-used within this document and should help the reader to
-understand the intent of meaning.
-
-
-
-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 *message 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.
-
-
-Messgae 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 *message 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. &Term 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
+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
+ *message 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.
+
+ * - **Messgae 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 *message 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. &Term 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.
-
-Sender Sample
---------------------------------------------------------------------------------------------
-
+
+
+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 function is used to send the next
-message. It does not illustrate error and/or retry handling.
+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.
::
-
- mrc = rmr_init( listen_port, MAX_BUF_SZ, RMRFL_NOFLAGS );
- rmr_set_stimeout( mrc, rmr_retries );
- while( ! rmr_ready( mrc ) ) {
- sleep( 1 );
- }
- sbuf = rmr_alloc_msg( mrc, 256 ); // 1st send buffer
- while( TRUE ) {
- sbuf->len = gen_status( (status_msg *) sbuf->payload );
- sbuf->mtype = STATUS_MSG;
- sbuf->sub_id = RMR_VOID_SUBID; // subscription not used
- sbuf = rmr_send_msg( mrc, sbuf );
- sleep( delay_sec );
- }
- rmr_close( mrc );
-
-
-
-Receiver Sample
---------------------------------------------------------------------------------------------
+
+ #include <unistd.h>
+ #include <errno.h>
+ #include <string.h>
+ #include <stdio.h>
+ #include <stdlib.h>
+ #include <sys/epoll.h>
+ #include <time.h>
+
+ #include <rmr/rmr.h>
+
+ int main( int argc, char** argv ) {
+ void* mrc; // msg router context
+ struct epoll_event events[1]; // list of events to give to epoll
+ struct epoll_event epe; // event definition for event to listen to
+ int ep_fd = -1; // epoll's file des (given to epoll_wait)
+ int rcv_fd; // file des for epoll checks
+ int nready; // number of events ready for receive
+ rmr_mbuf_t* sbuf; // send buffer
+ rmr_mbuf_t* rbuf; // received buffer
+ int count = 0;
+ int rcvd_count = 0;
+ char* listen_port = "43086";
+ 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];
+ }
+ if( argc > 2 ) {
+ delay = atoi( argv[2] );
+ }
+ if( argc > 3 ) {
+ mtype = atoi( argv[3] );
+ }
+
+ fprintf( stderr, "<DEMO> listen port: %s; mtype: %d; delay: %d\\n",
+ listen_port, mtype, delay );
+
+ if( (mrc = rmr_init( listen_port, 1400, RMRFL_NONE )) == NULL ) {
+ fprintf( stderr, "<DEMO> 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, "<DEMO> unable to set up polling fd\\n" );
+ exit( 1 );
+ }
+ if( (ep_fd = epoll_create1( 0 )) < 0 ) {
+ fprintf( stderr, "[FAIL] unable to create epoll fd: %d\\n", errno );
+ exit( 1 );
+ }
+ 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, "<DEMO> 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;
+ sbuf = rmr_send_msg( mrc, sbuf ); // send & get next buf to fill in
+ while( sbuf->state == RMR_ERR_RETRY ) { // soft failure (device busy?) retry
+ 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
+ errno = 0;
+ rbuf = rmr_rcv_msg( mrc, rbuf ); // receive and ignore; just count
+ if( rbuf ) {
+ rcvd_count++;
+ }
+ }
+ }
+
+ if( (count % stats_freq) == 0 ) { // occasional stats out to tty
+ fprintf( stderr, "<DEMO> 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
::
-
- rmr_mbuf_t* rbuf = NULL;
- void* mrc = rmr_init( listen_port, MAX_BUF_SZ, RMRFL_NOFLAGS );
- while( TRUE ) {
- rbuf = rmr_rcv_msg( mrc, rbuf ); // reuse buffer on all but first loop
- if( rbuf == NULL || rbuf->state != RMR_OK ) {
- break;
- }
- fprintf( stdout, "mtype=%d sid=%d pay=%s\\n",
- rbuf->mtype, rbuf->sub_id, rbuf->payload );
- sleep( delay_sec );
- }
- fprintf( stderr, "receive error\\n" );
- rmr_close( mrc );
-
-
-
-Receive and Send Sample
---------------------------------------------------------------------------------------------
+
+ #include <unistd.h>
+ #include <errno.h>
+ #include <stdio.h>
+ #include <stdlib.h>
+ #include <time.h>
+
+ #include <rmr/rmr.h>
+
+
+ int main( int argc, char** argv ) {
+ void* mrc; // msg router context
+ long long total = 0;
+ rmr_mbuf_t* msg = NULL; // message received
+ int stat_freq = 10; // write stats after reciving this many messages
+ int i;
+ char* listen_port = "4560"; // default to what has become the standard RMR port
+ long long count = 0;
+ long long bad = 0;
+ long long empty = 0;
+
+ if( argc > 1 ) {
+ listen_port = argv[1];
+ }
+ if( argc > 2 ) {
+ stat_freq = atoi( argv[2] );
+ }
+ fprintf( stderr, "<DEMO> listening on port: %s\\n", listen_port );
+ fprintf( stderr, "<DEMO> 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, "<DEMO> ABORT: unable to initialise RMr\\n" );
+ exit( 1 );
+ }
+
+ while( ! rmr_ready( mrc ) ) { // wait for RMR to get a route table
+ fprintf( stderr, "<DEMO> waiting for ready\\n" );
+ sleep( 3 );
+ }
+ fprintf( stderr, "<DEMO> 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
+ } else {
+ bad++;
+ }
+ } else {
+ empty++;
+ }
+
+ if( (count % stat_freq) == 0 ) {
+ fprintf( stderr, "<DEMO> 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
::
-
- 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 );
+ 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 );
+
// :vim ts=4 sw=4 noet:
/*
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
- http://www.apache.org/licenses/LICENSE-2.0
+ http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
*/
/*
- Mnemonic: rmr_rcvr.c
- Abstract: This is a very simple receiver that does nothing but listen
- for messages and write stats every so often to the tty.
+ Mnemonic: rmr_rcvr.c
+ Abstract: This is a very simple receiver that does nothing but listen
+ for messages and write stats every so often to the tty.
- Define these environment variables to have some control:
- RMR_SEED_RT -- path to the static routing table
- RMR_RTG_SVC -- host:port of the route table generator
+ Define these environment variables to have some control:
+ RMR_SEED_RT -- path to the static routing table
+ RMR_RTG_SVC -- host:port of the route table generator
- Parms: Two positional parameters are recognised on the command line:
- [port [stats-freq]]
+ Parms: Two positional parameters are recognised on the command line:
+ [port [stats-freq]]
- where port is the port number to listen on and the stats frequency
- is the number of messages received which causes stats to be
- generated. If not supplied the listen port default is 4560
- and the stats frequency is every 10 messages.
+ where port is the port number to listen on and the stats frequency
+ is the number of messages received which causes stats to be
+ generated. If not supplied the listen port default is 4560
+ and the stats frequency is every 10 messages.
- Date: 1 April 2019
- Author: E. Scott Daniels
+ Date: 1 April 2019
+ Author: E. Scott Daniels
+
+ CAUTION: This example is now being pulled directly into the user documentation.
+ Because of this some altered line lengths and/or parameter list breaks
+ which seem strage have been applied to ensure that it formats nicely.
+ All code following the 'start_example' tag below is included.
*/
+// start_example
#include <unistd.h>
#include <errno.h>
int main( int argc, char** argv ) {
- void* mrc; // msg router context
- long long total = 0;
- rmr_mbuf_t* msg = NULL; // message received
- int stat_freq = 10; // write stats after reciving this many messages
- int i;
- char* listen_port = "4560"; // default to what has become the standard RMR port
- long long count = 0;
- long long bad = 0;
- long long empty = 0;
-
- if( argc > 1 ) {
- listen_port = argv[1];
- }
- if( argc > 2 ) {
- stat_freq = atoi( argv[2] );
- }
- fprintf( stderr, "<DEMO> listening on port: %s\n", listen_port );
- fprintf( stderr, "<DEMO> stats will be reported every %d messages\n", stat_freq );
-
- mrc = rmr_init( listen_port, RMR_MAX_RCV_BYTES, RMRFL_NONE ); // start your engines!
- if( mrc == NULL ) {
- fprintf( stderr, "<DEMO> ABORT: unable to initialise RMr\n" );
- exit( 1 );
- }
-
- while( ! rmr_ready( mrc ) ) { // wait for RMr to load a route table
- fprintf( stderr, "<DEMO> waiting for ready\n" );
- sleep( 3 );
- }
- fprintf( stderr, "<DEMO> rmr now shows ready\n" );
-
- while( 1 ) { // forever; ctl-c, kill -15, etc to end
- msg = rmr_rcv_msg( mrc, msg ); // block until one arrives
-
- if( msg ) {
- if( msg->state == RMR_OK ) {
- count++; // messages received for stats output
- } else {
- bad++;
- }
- } else {
- empty++;
- }
-
- if( (count % stat_freq) == 0 ) {
- fprintf( stderr, "<DEMO> total msg received: %lld errors: %lld empty: %lld\n", count, bad, empty );
- }
-
- }
+ void* mrc; // msg router context
+ long long total = 0;
+ rmr_mbuf_t* msg = NULL; // message received
+ int stat_freq = 10; // write stats after reciving this many messages
+ int i;
+ char* listen_port = "4560"; // default to what has become the standard RMR port
+ long long count = 0;
+ long long bad = 0;
+ long long empty = 0;
+
+ if( argc > 1 ) {
+ listen_port = argv[1];
+ }
+ if( argc > 2 ) {
+ stat_freq = atoi( argv[2] );
+ }
+ fprintf( stderr, "<DEMO> listening on port: %s\n", listen_port );
+ fprintf( stderr, "<DEMO> 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, "<DEMO> ABORT: unable to initialise RMr\n" );
+ exit( 1 );
+ }
+
+ while( ! rmr_ready( mrc ) ) { // wait for RMR to get a route table
+ fprintf( stderr, "<DEMO> waiting for ready\n" );
+ sleep( 3 );
+ }
+ fprintf( stderr, "<DEMO> 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
+ } else {
+ bad++;
+ }
+ } else {
+ empty++;
+ }
+
+ if( (count % stat_freq) == 0 ) {
+ fprintf( stderr, "<DEMO> total received: %lld; errors: %lld; empty: %lld\n",
+ count, bad, empty );
+ }
+ }
}
// :vim ts=4 sw=4 noet:
/*
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ Copyright (c) 2019-2020 Nokia
+ Copyright (c) 2018-2020 AT&T Intellectual Property.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
[listen_port [delay [stats-freq] [msg-type]]]]
Defaults:
- listen_port 43086
+ listen_port 43086
delay (mu-sec) 1000000 (1 sec)
stats-freq 10
msg-type 0
Date: 1 April 2019
+
+ CAUTION: This example is now being pulled directly into the user documentation.
+ Because of this some altered line lengths and/or parameter list breaks
+ which seem strage have been applied to ensure that it formats nicely.
+ All code following the 'start_example' tag below is included.
*/
+// start_example
#include <unistd.h>
#include <errno.h>
#include <rmr/rmr.h>
int main( int argc, char** argv ) {
- void* mrc; //msg router context
- struct epoll_event events[1]; // list of events to give to epoll
- struct epoll_event epe; // event definition for event to listen to
- int ep_fd = -1; // epoll's file des (given to epoll_wait)
- int rcv_fd; // file des that NNG tickles -- give this to epoll to listen on
- int nready; // number of events ready for receive
- rmr_mbuf_t* sbuf; // send buffer
- rmr_mbuf_t* rbuf; // received buffer
+ void* mrc; // msg router context
+ struct epoll_event events[1]; // list of events to give to epoll
+ struct epoll_event epe; // event definition for event to listen to
+ int ep_fd = -1; // epoll's file des (given to epoll_wait)
+ int rcv_fd; // file des for epoll checks
+ int nready; // number of events ready for receive
+ rmr_mbuf_t* sbuf; // send buffer
+ rmr_mbuf_t* rbuf; // received buffer
int count = 0;
int rcvd_count = 0;
char* listen_port = "43086";
- int delay = 1000000; // mu-sec delay between messages
+ int delay = 1000000; // mu-sec delay between messages
int mtype = 0;
int stats_freq = 100;
- if( argc > 1 ) {
+ if( argc > 1 ) { // simplistic arg picking
listen_port = argv[1];
}
if( argc > 2 ) {
mtype = atoi( argv[3] );
}
- fprintf( stderr, "<DEMO> listen port: %s; mtype: %d; delay: %d\n", listen_port, mtype, delay );
+ fprintf( stderr, "<DEMO> listen port: %s; mtype: %d; delay: %d\n",
+ listen_port, mtype, delay );
if( (mrc = rmr_init( listen_port, 1400, RMRFL_NONE )) == NULL ) {
- fprintf( stderr, "<DEMO> unable to initialise RMr\n" );
+ fprintf( stderr, "<DEMO> unable to initialise RMR\n" );
exit( 1 );
}
- rcv_fd = rmr_get_rcvfd( mrc ); // set up epoll things, start by getting the FD from MRr
+ rcv_fd = rmr_get_rcvfd( mrc ); // set up epoll things, start by getting the FD from RMR
if( rcv_fd < 0 ) {
fprintf( stderr, "<DEMO> unable to set up polling fd\n" );
exit( 1 );
exit( 1 );
}
- sbuf = rmr_alloc_msg( mrc, 256 ); // alloc first send buffer; subsequent buffers allcoated on send
+ 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 a route table before we can send; wait til RMr say it has one
- sleep( 1 );
+ while( ! rmr_ready( mrc ) ) { // must have route table
+ sleep( 1 ); // wait til we get one
}
fprintf( stderr, "<DEMO> 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
+
+ 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; // our receiver likely wants a nice acsii-z string
+ sbuf->len = strlen( sbuf->payload ) + 1; // send full ascii-z string
sbuf->state = 0;
- sbuf = rmr_send_msg( mrc, sbuf ); // send it (send returns an empty payload on success, or the original payload on fail/retry)
+ sbuf = rmr_send_msg( mrc, sbuf ); // send & get next buf to fill in
while( sbuf->state == RMR_ERR_RETRY ) { // soft failure (device busy?) retry
- sbuf = rmr_send_msg( mrc, sbuf ); // retry send until it's good (simple test; real programmes should do better)
+ sbuf = rmr_send_msg( mrc, sbuf ); // w/ simple spin that doesn't give up
}
count++;
- while( (nready = epoll_wait( ep_fd, events, 1, 0 )) > 0 ) { // if something ready to receive (non-blocking check)
- if( events[0].data.fd == rcv_fd ) { // we only are waiting on 1 thing, so [0] is ok
+ // 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
errno = 0;
- rbuf = rmr_rcv_msg( mrc, rbuf );
+ rbuf = rmr_rcv_msg( mrc, rbuf ); // receive and ignore; just count
if( rbuf ) {
rcvd_count++;
}
}
}
- if( (count % stats_freq) == 0 ) {
+ if( (count % stats_freq) == 0 ) { // occasional stats out to tty
fprintf( stderr, "<DEMO> sent %d received %d\n", count, rcvd_count );
}
Code Review / ric-plt / lib / rmr.git / commitdiff