# -DBUILD_DOC=1 Man pages generated
# -DPRESERVE_PTYPE=1 Do not change the processor type when naming deb packages
# -DPACK_EXTERNALS=1 Include external libraries used to build in the run-time package
+# (This makes some stand-alone unit testing of bindings possible, it
+# is not meant to be used for production package generation.)
# -DSKIP_EXTERNALS=1 Do not use Nano/NNG submodules when building; uee installed packages
# -DMAN_PREFIX=<path> Supply a path where man pages are installed (default: /usr/share/man)
set( major_version "1" ) # should be automatically populated from git tag later, but until CI process sets a tag we use this
set( minor_version "0" )
-set( patch_level "39" )
+set( patch_level "40" )
set( install_root "${CMAKE_INSTALL_PREFIX}" )
set( install_lib "lib" )
message( "+++ installing nano/nng with: ${nano_major}.${nano_minor} | ${nng_major}.${nng_minor}" )
else()
if( PACK_EXTERNALS )
+ # This makes some stand-alone unit testing possible for bindings and transport layer testing;
+ # it is not meant for production packages.
+ #
unset( SKIP_EXTERNALS CACHE ) # must remove so as not to trap user into a never ending failure
unset( PACK_EXTERNALS CACHE )
message( FATAL_ERROR "ERROR: PACK_EXTERNALS can be set only if SKIP_EXTERNALS is unset (=0, or not supplied on command line)" )
rmr_mt_rcv.3
rmr_get_srcip.3
rmr_trace_ref.3
+ rmr_set_stimeout.3
)
# initialise lists of files we generated
# 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.
+ # that tfm likes to insert even if indention is 0. We also generate postscript
+ # and rts output which are left in the build directory for the developer to
+ # use as needed.
#
foreach( nm IN LISTS man_names )
set( out ${CMAKE_BINARY_DIR}/${nm} )
add_custom_command(
OUTPUT ${out}.gz
DEPENDS ${in}
- COMMAND bash -c "export LIB=${CMAKE_SOURCE_DIR}/doc/src; ${tfm} ${in} stdout | sed 's/^ //' | gzip >${out}.gz; ${pfm} ${in} ${out}.ps"
+ COMMAND bash -c "export OUTPUT_RST=0; export LIB=${CMAKE_SOURCE_DIR}/doc/src; \
+ ${tfm} ${in} stdout | sed 's/^ //' | gzip >${out}.gz; \
+ export OUTPUT_RST=1; ${tfm} ${in} ${out}.rst; \
+ ${pfm} ${in} ${out}.ps"
WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
COMMENT "Building manpage ${out}"
VERBATIM
--- /dev/null
+.if false
+==================================================================================
+ Copyright (c) 2019 Nokia
+ Copyright (c) 2018-2019 AT&T Intellectual Property.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ 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: retry.im
+ Abstract: Common text for all send operation functions. This should be imbedded by any
+ function which will ultimately use the internal send_msg funciton which
+ governs retries in this manner.
+ Date: 16 July 2019
+.fi
+
+&h3(Retries)
+The send operations in RMr will retry &ital(soft) send failures until one of three
+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
+
+ &di(3.) The maximum number of retry loops has been attempted
+ &end_dlist
+&uindent
+
+&space
+A retry loop consists of approximately 1000 send attemps &bold( without) any intervening
+calls to &ital( sleep() ) or &ital( usleep(). )
+The number of retry loops defaults to 1, thus a maximum of 1000 send attempts is performed
+before returning to the user application.
+This value can be set at any point after RMr initialisation using the &ital( rmr_set_stimeout() )
+function allowing the user application to completely disable retires (set to 0), or to
+increase the number of retry loops.
+
+&h3(Transport Level Blocking)
+The underlying transport mechanism used to send messages is configured in &ital(non-blocking)
+mode.
+This means that if a message cannot be sent immediately the transport mechanism will &bold(not)
+pause with the assumption that the inability to send will clear quickly (within a few milliseconds).
+This means that when the retry loop is completely disabled (set to 0), that the failure to
+accept a message for sending by the underlying mechanisms (software or hardware) will be
+reported immediately to the user application.
+
+&space
+It should be noted that depending on the underlying transport mechanism being used, it is
+extremly possible that during normal operations that retry conditions are very likely to
+happen.
+These are completely out of RMr's control, and there is nothing that RMr can do to avoid or midigate
+these other than by allowing RMr to retry the send operation, and even then it is possible
+(e.g. during connection reattempts), that a single retry loop is not enough to guarentee a
+successful send.
+
Currently the threshold is fixed at 20 messages, though in future versions of the library
this might be extended to be a parameter which the user application may set.
+.** pull in common retry text
+.im &{lib}/man/retry.im
+
&h2(RETURN VALUE)
The &cw(rmr_call) function returns a pointer to a message buffer with the state set to reflect
the overall state of call processing (see Errors below).
rmr_ready(3),
rmr_fib(3),
rmr_has_str(3),
+rmr_set_stimeout(3),
rmr_tokenise(3),
rmr_mk_ring(3),
rmr_ring_free(3)
&space
Messages which are received while waiting for the response are queued on a &ital(normal)
receive queue and will be delivered to the user application with the next invocation
-of &itaL( rmr_mt_rcv() ) or &ital( rmr_rvv_msg().)
+of &ital( rmr_mt_rcv() ) or &ital( rmr_rvv_msg().)
by RMR, and are returned to the user application when &cw(rmr_rcv_msg) is
invoked.
These messages are returned in th order received, one per call to &cw(rmr_rcv_msg.)
&space
NOTE: Currently the multi-threaded functions are supported only when the NNG
transport mechanism is being used. It will not be possible to link a programme
-using the nanomsg version of the library when references to this function are
+using the Nanomsg version of the library when references to this function are
present.
&h3(The Transaction ID)
the application uses the &ital( rmr_rts_msg() ) function and does not adjust the
transaction ID.
+.** pull in common retry text
+.im &{lib}/man/retry.im
&h2(RETURN VALUE)
The &cw(rmr_mt_call) function returns a pointer to a message buffer with the state set to reflect
rmr_ready(3),
rmr_fib(3),
rmr_has_str(3),
+rmr_set_stimeout(3),
rmr_tokenise(3),
rmr_mk_ring(3),
rmr_ring_free(3)
Other than this small difference, the behaviour is exactly the same as
&cw(rmr_send_msg.)
+.** pull in common retry text
+.im &{lib}/man/retry.im
+
&h2(RETURN VALUE)
On success, a new message buffer, with an empty payload, is returned for the application
to use for the next send.
rmr_ready(3),
rmr_fib(3),
rmr_has_str(3),
+rmr_set_stimeout(3),
rmr_tokenise(3),
rmr_mk_ring(3),
rmr_ring_free(3)
responsibility of the library.)
+.** pull in common retry text
+.im &{lib}/man/retry.im
+
+
&h2(RETURN VALUE)
On success, a new message buffer, with an empty payload, is returned for the application
to use for the next send.
&cw(RMR_OK.)
&space
-If the state in the returned buffer is anything other than &cw(UT_OK,) the user application
-may need to attempt a retransmission of the message, or take other action depending on the
-setting of &cw(errno) as described below.
+When the message cannot be successfully sent this function will return the unsent (original)
+message buffer with the state set to indicate the reason for failure.
+The value of &ital( errno ) may also be set to reflect a more detailed failure reason if it
+is known.
&space
In the event of extreme failure, a NULL pointer is returned. In this case the value of
&space
&beg_dlist(.75i : ^&bold_font )
+&di(RMR_RETRY) The message could not be sent, but the underlying transport mechanism
+ indicates that the failure is temporary. If the send operation is tried again
+ it might be successful.
+&di(RMR_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.
--- /dev/null
+.if false
+==================================================================================
+ Copyright (c) 2019 Nokia
+ Copyright (c) 2018-2019 AT&T Intellectual Property.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ 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 rmr_set_stimeout.xfm
+ Abstract The manual page for the rmr_set_stimeout function.
+ Author E. Scott Daniels
+ Date 28 January 2019
+.fi
+
+.** if formatting with tfm, the roff.im will cause roff output to be generated
+.** if formatting with pfm, then pretty postscript will be generated
+.gv e LIB lib
+.if pfm
+ .im &{lib}/generic_ps.im
+.ei
+ .gv e OUTPUT_RST use_rst
+ .if .ev &use_rst 1 =
+ .im &{lib}/rst.im
+ .ei
+ .im &{lib}/roff.im
+ .fi
+.fi
+
+&line_len(6i)
+
+&h1(RMR Library Functions)
+&h2(NAME)
+ rmr_set_stimeout
+
+&h2(SYNOPSIS )
+&indent
+&ex_start
+#include <rmr/rmr.h>
+
+rmr_mbuf_t* rmr_set_stimeout( void* vctx, int rloops );
+
+&ex_end
+&uindent
+
+&h2(DESCRIPTION)
+The &cw(rmr_set_stimeout) function sets the configuration for how RMr will retry
+message send operations which complete with either a &ital( timeout ) or &ital( again )
+completion value. (Send operations include all of the possible message send
+functions: &ital( rmr_send_msg(), rmr_call(), rmr_rts_msg() ) and &ital( rmr_wh_send_msg(). )
+The &ital( rloops ) parameter sets the maximum number of retry loops
+that will be attempted before giving up and returning the unsuccessful state to the user
+application.
+Each retry loop is approximately 1000 attempts, and RMr does &bold( not ) invoke any sleep
+function between retries in the loop; a small, 1 mu-sec, sleep is executed between loop
+sets if the &ital( rloops ) value is greater than 1.
+
+.sp
+&h3(Disabling Retries)
+By default, the send operations will execute with an &ital( rloop ) setting of 1; each send
+operation will attempt to resend the message approximately 1000 times before giving up.
+If the user application does not want to have send operations retry when the underlying
+transport mechanism indicates &ital( timeout ) or &ital( again, ) the application should
+invoke this function and pass a value of 0 (zero) for &ital( rloops. )
+With this setting, all RMr send operations will attempt a send operation only &bold( once, )
+returning immediately to the caller with the state of that single attempt.
+
+
+&h2(RETURN VALUE)
+This function returns a -1 to indicate that the &ital( rloops ) value could not be set, and
+the value &ital( RMR_OK ) to indicate success.
+
+
+&h2(ERRORS)
+Currently errno is &bold( not ) set by this function; the only cause of a failure is an
+invalid context ( .sm &ital( vctx ) .sm ) pointer.
+
+&h2(EXAMPLE)
+The following is a simple example of how the &cw(rmr_set_stimeout) function is called.
+
+&space
+&ex_start
+ #define NO_FLAGS 0
+
+ char* port = "43086"; // port for message router listen
+ int max_size = 4096; // max message size for default allocations
+ void* mr_context; // message router context
+
+ mr_context = rmr_init( port, max_size, NO_FLAGS );
+ if( mr_context != NULL ) {
+ rmr_set_stimeout( mr_context, 0 ); // turn off retries
+ }
+
+&ex_end
+
+
+&h2(SEE ALSO )
+.ju off
+rmr_alloc_msg(3),
+rmr_call(3),
+rmr_free_msg(3),
+rmr_init(3),
+rmr_payload_size(3),
+rmr_rcv_msg(3),
+rmr_rcv_specific(3),
+rmr_rts_msg(3),
+rmr_ready(3),
+rmr_mk_ring(3),
+rmr_ring_free(3),
+rmr_send_msg(3),
+rmr_torcv_rcv(3),
+rmr_wh_send_msg(3)
+.ju on
+
+
+.qu
+
to a process at the other end of a wormhole which was created with &ital(rmr_wh-open().)
When sending message via wormholes, the normal RMr routing based on message type is
ignored, and the caller may leave the message type unspecified in the message buffer
-(unless it is needed by the reeciving process).
+(unless it is needed by the receiving process).
.sp
The message buffer (msg) used to send is the same format as used for regular RMr
send and reply to sender operations, thus any buffer allocated by these means, or
calls to &ital(rmr_rcv_msg()) can be passed to this function.
+.** pull in common retry text
+.im &{lib}/man/retry.im
&h2(RETURN VALUE)
On success, a new message buffer, with an empty payload, is returned for the application
rmr_tokenise(3),
rmr_mk_ring(3),
rmr_ring_free(3),
+rmr_set_stimeout(3),
rmr_wh_open(3),
rmr_wh_close(3)
.ju on
See the `examples` directory.
# Compiling rmr (if not already done on your system)
-(Note, you may or may not need sudo in your final command, depending on permissions to `/usr/local`. I need it)
+(Note, you may or may not need sudo in your final command, depending on permissions to `/usr/local`. The pack externals option to CMake is needed only if the NNG libary is not already installed on the system, and you do not wish to manually install it.)
git clone https://gerrit.oran-osc.org/r/ric-plt/lib/rmr
cd rmr
- mkdir .build; cd .build; cmake ..; sudo make install
+ mkdir .build; cd .build; cmake .. -DPACK_EXTERNALS=1; sudo make install
Code Review / ric-plt / lib / rmr.git / commitdiff