+
.. 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.
.. Do NOT make changes directly to .rst or .md files.
+
RMR User's Guide
============================================================================================
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 0, then the default size supplied on
-the *rmr_init* call will be used. The *ctx* parameter is the
-void context pointer that was returned by the *rmr_init*
-function.
+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
+may impose a limit.
+
+The *ctx* parameter is the void context pointer that was
+returned by the *rmr_init* function.
The pointer to the message buffer returned is a structure
which has some user application visible fields; the structure
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.
When the threshold number of messages have been queued
without receiving a response message, control is returned to
-the user application and a NULL pointer is returned to
+the user application and a nil pointer is returned to
indicate that no message was received to process. Currently
the threshold is fixed at 20 messages, though in future
versions of the library this might be extended to be a
parameter which the user application may set.
Retries
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The send operations in RMR will retry *soft* send failures
until one of three conditions occurs:
(set to 0), or to increase the number of retry loops.
Transport Level Blocking
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The underlying transport mechanism used to send messages is
configured in *non-blocking* mode. This means that if a
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 NULL pointer
+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.
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; // private message (payload)
+ msg_t* pm; // application struct for payload
// get a send buffer and reference the payload
- mbuf = rmr_alloc_msg( mr, RMR_MAX_RCV_BYTES );
+ 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() );
rmr_ring_free(3)
+NAME
+--------------------------------------------------------------------------------------------
+
+rmr_get_const
+
+SYNOPSIS
+--------------------------------------------------------------------------------------------
+
+
+::
+
+ #include <rmr/rmr.h>
+ unsigned char* rmr_get_const();
+
+
+
+DESCRIPTION
+--------------------------------------------------------------------------------------------
+
+The rmr_get_const function is a convenience function for
+wrappers which do not have the ability to "compile in" RMR
+constants. The function will build a nil terminated string
+containing JSON which defines the RMR constants that C and Go
+applications have at compile time via the rmr.h header file.
+
+All values are represented as strings and the JSON format is
+illustrated in the following (partial) example:
+
+
+::
+
+ {
+ "RMR_MAX_XID": "32",
+ "RMR_OK": "0",
+ "RMR_ERR_BADARG", "1",
+ "RMR_ERR_NOENDPT" "2"
+ }
+
+
+
+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
+--------------------------------------------------------------------------------------------
+
+rmr(7)
+
+
NAME
--------------------------------------------------------------------------------------------
rmr_mbuf_t* msg = NULL;
int nready;
int i;
- mrc = rmr_init( "43086", RMR_MAX_RCV_BYTES, RMRFL_NONE );
+ 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;
::
#include <rmr/rmr.h>
- void* rmr_init( char* proto_port, int max_msg_size, int flags );
+ void* rmr_init( char* proto_port, int norm_msg_size, int flags );
library to send messages.
*Port* is used to listen for connection requests from other
-RMR based applications. The *max_msg_size* parameter is used
-to allocate receive buffers and is the maximum message size
-which the application expects to receive. This value is the
-sum of **both** the maximum payload size **and** the maximum
-trace data size. This value is also used as the default
-message size when allocating message buffers. Messages
-arriving which are longer than the given maximum will be
-dropped without notification to the application. A warning is
-written to standard error for the first message which is too
-large on each connection.
+RMR based applications. The *norm_msg_size* parameter is used
+to allocate receive buffers and should be set to what the
+user application expects to be a size which will hold the
+vast majority of expected messages. When computing the size,
+the application should consider the usual payload size
+**and** the maximum trace data size that will be used. This
+value is also used as the default message size when
+allocating message buffers (when a zero size is given to
+rmr_alloc_msg(); see the rmr_alloc_msg() manual page).
+Messages arriving which are longer than the given normal size
+will cause RMR to allocate a new buffer which is large enough
+for the arriving message.
+
+Starting with version 3.8.0 RMR no longer places a maximum
+buffer size for received messages. The underlying system
+memory manager might impose such a limit and the attempt to
+allocate a buffer larger than that limit will likely result
+in an application abort. Other than the potential performance
+impact from extra memory allocation and release, there is no
+penality to the user programme for specifyning a normal
+buffer size which is usually smaller than received buffers.
+Similarly, the only penality to the application for over
+specifying the normal buffer size might be a larger memory
+footprint.
*Flags* allows for selection of some RMr options at the time
of initialisation. These are set by ORing RMRFL constants
Multi-threaded Calling
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The support for an application to issue a *blocking call* by
the rmr_call() function was limited such that only user
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
not adjust the transaction ID.
Retries
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The send operations in RMR will retry *soft* send failures
until one of three conditions occurs:
(set to 0), or to increase the number of retry loops.
Transport Level Blocking
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The underlying transport mechanism used to send messages is
configured in *non-blocking* mode. This means that if a
int retries_left = 5; // max retries on dev not available
static rmr_mbuf_t* mbuf = NULL; // response msg
- msg_t* pm; // private message (payload)
+ msg_t* pm; // appl message struct (payload)
// get a send buffer and reference the payload
- mbuf = rmr_alloc_msg( mr, RMR_MAX_RCV_BYTES );
+ 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 );
mbuf->state != RMR_OK ) {
usleep( retry_delay );
}
-
if( mbuf == NULL || mbuf->state != RMR_OK ) {
rmr_free_msg( mbuf ); // safe if nil
return NULL;
The function returns a pointer to the rmr_mbuf_t structure
which references the message information (state, length,
-payload), or a NULL pointer in the case of an extreme error.
+payload), or a nil pointer in the case of an extreme error.
ERRORS
--------------------------------------------------------------------------------------------
there is no additional memory allocation and copying.
Cloning The Message Buffer
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This function can also be used to generate a separate copy of
the original message, with the desired payload size, without
the cloned message **only** if the *copy* parameter is true.
Message Buffer Metadata
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The metadata in the original message buffer (message type,
subscription ID, and payload length) will be preserved if the
as rmr_send_msg.
Retries
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The send operations in RMR will retry *soft* send failures
until one of three conditions occurs:
(set to 0), or to increase the number of retry loops.
Transport Level Blocking
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The underlying transport mechanism used to send messages is
configured in *non-blocking* mode. This means that if a
retransmission of the message, or take other action depending
on the setting of errno as described below.
-In the event of extreme failure, a NULL pointer is returned.
+In the event of extreme failure, a nil pointer is returned.
In this case the value of errno might be of some use, for
documentation, but there will be little that the user
application can do other than to move on.
EFAULT
The message referenced by the message buffer is corrupt
- (NULL pointer or bad internal length).
+ (nil pointer or bad internal length).
EBADF
library.)
Retries
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The send operations in RMR will retry *soft* send failures
until one of three conditions occurs:
(set to 0), or to increase the number of retry loops.
Transport Level Blocking
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The underlying transport mechanism used to send messages is
configured in *non-blocking* mode. This means that if a
*errno* may also be set to reflect a more detailed failure
reason if it is known.
-In the event of extreme failure, a NULL pointer is returned.
+In the event of extreme failure, a nil pointer is returned.
In this case the value of errno might be of some use, for
documentation, but there will be little that the user
application can do other than to move on.
EFAULT
The message referenced by the message buffer is corrupt
- (NULL pointer or bad internal length).
+ (nil pointer or bad internal length).
EBADF
Disabling Retries
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
By default, the send operations will execute with an *rloop*
setting of 1; each send operation will attempt to resend the
The function returns a pointer to the rmr_mbuf_t structure
which references the message information (state, length,
-payload), or a NULL pointer in the case of an extreme error.
+payload), or a nil pointer in the case of an extreme error.
ERRORS
--------------------------------------------------------------------------------------------
Go's goroutines) is possible.
Retries
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The send operations in RMR will retry *soft* send failures
until one of three conditions occurs:
(set to 0), or to increase the number of retry loops.
Transport Level Blocking
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The underlying transport mechanism used to send messages is
configured in *non-blocking* mode. This means that if a
int i;
rmr_mbuf_t* sbuf; // send buffer
int count = 0;
- mrc = rmr_init( "43086", RMR_MAX_RCV_BYTES, RMRFL_NONE );
+ 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 );
*rmr_rcv_msg()* can be passed to this function.
Retries
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The send operations in RMR will retry *soft* send failures
until one of three conditions occurs:
(set to 0), or to increase the number of retry loops.
Transport Level Blocking
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The underlying transport mechanism used to send messages is
configured in *non-blocking* mode. This means that if a
retransmission of the message, or take other action depending
on the setting of errno as described below.
-In the event of extreme failure, a NULL pointer is returned.
+In the event of extreme failure, a nil pointer is returned.
In this case the value of errno might be of some use, for
documentation, but there will be little that the user
application can do other than to move on.
EFAULT
The message referenced by the message buffer is corrupt
- (NULL pointer or bad internal length).
+ (nil pointer or bad internal length).
EBADF
int i;
rmr_mbuf_t* sbuf; // send buffer
int count = 0;
- mrc = rmr_init( "43086", RMR_MAX_RCV_BYTES, RMRFL_NONE );
+ 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 );
Code Review / ric-plt / lib / rmr.git / blobdiff