endpoint selection, is based on the message type rather than
on traditional DNS names or IP addresses. Because the user
documentation for RMR is a collection of UNIX manpages
-(included in the development package, and avalable via the
+(included in the development package, and available via the
man command when installed), there is no separate "User's
-Guide." To prvide something for the document scrapers to
+Guide." To provide something for the document scrapers to
find, this is a collection of the RMR manual pages formatted
directly from their source which might be a bit ragged when
combined into a single markup document. Read the manual pages
--------------------------------------------------------------------------------------------
The rmr_bytes2meid function will copy up to *len* butes from
-*src* to the managed equipment ID (meid) field in the
-message. The field is a fixed length, gated by the constant
+*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.
This is a convenience function as some wrapper languages
might not have the ability to directly copy into the payload
-buffer. The bytes from * src * for the length given are
-copied to the payload. It is the caller's responsibility to
-ensure that the payload is large enough. Upon successfully
-copy, the len field in the message buffer is updated to
-reflect the number of bytes copied.
+buffer. The bytes from *src* for the length given are copied
+to the payload. It is the caller's responsibility to ensure
+that the payload is large enough. Upon successfully copy, the
+len field in the message buffer is updated to reflect the
+number of bytes copied.
There is little error checking, and no error reporting.
DESCRIPTION
--------------------------------------------------------------------------------------------
-The rmr_get_meid function will copy the managed equipment ID
+The rmr_get_meid function will copy the managed entity ID
(meid) field from the message into the *dest* buffer provided
-by the user. The buffer referenced by * dest * is assumed to
-be at least RMR_MAX_MEID bytes in length. If * dest * is
-NULL, then a buffer is allocated (the calling application is
+by the user. The buffer referenced by *dest* is assumed to be
+at least RMR_MAX_MEID bytes in length. If *dest* is NULL,
+then a buffer is allocated (the calling application is
expected to free when the buffer is no longer needed).
RETURN VALUE
--------------------------------------------------------------------------------------------
On success, a pointer to the extracted string is returned. If
-* dest * was supplied, then this is just a pointer to the
-caller's buffer. If * dest * was NULL, this is a pointer to
-the allocated buffer. If an error occurs, a nil pointer is
+*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
ENOMEM
- A nil pointer was passed for * dest, * however it was not
+ A nil pointer was passed for *dest,* however it was not
possible to allocate a buffer using malloc().
The rmr_get_xact function will copy the transaction field
from the message into the *dest* buffer provided by the user.
-The buffer referenced by * dest * is assumed to be at least
-RMR_MAX_XID bytes in length. If * dest * is NULL, then a
-buffer is allocated (the calling application is expected to
-free when the buffer is no longer needed).
+The buffer referenced by *dest* is assumed to be at least
+RMR_MAX_XID bytes in length. If *dest* is NULL, then a buffer
+is allocated (the calling application is expected to free
+when the buffer is no longer needed).
RETURN VALUE
--------------------------------------------------------------------------------------------
On success, a pointer to the extracted string is returned. If
-* dest * was supplied, then this is just a pointer to the
-caller's buffer. If * dest * was NULL, this is a pointer to
-the allocated buffer. If an error occurs, a nil pointer is
+*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
ENOMEM
- A nil pointer was passed for * dest, * however it was not
+ A nil pointer was passed for *dest,* however it was not
possible to allocate a buffer using malloc().
library to send messages.
*Port* is used to listen for connection requests from other
-RMR based applications. The value of *max_msg_size* will be
-used when allocating zero copy send buffers which must be
-allocated, possibly, prior to the application knowing the
-actual size of a specific message.
+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.
*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_MTCALL
Enable multi-threaded call support.
+
+ &ditem 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
safely use the function. Further, timeouts were message count
based and not time unit based. Multi-threaded call support
adds the ability for a user application with multiple threads
-to invoke a blocking call function with the guarentee that
+to invoke a blocking call function with the guarantee that
the correct response message is delivered to the thread. The
-additional support is implemented with the * rmr_mt_call() *
-and * rmr_mt_rcv() * function calls.
+additional support is implemented with the *rmr_mt_call()*
+and *rmr_mt_rcv()* function calls.
Multi-threaded call support requires the user application to
specifically enable it when RMr is initialised. This is
--------------------------------------------------------------------------------------------
A value of 1 is returned on success, and 0 on failure. A
-failure indicates that the RMr context (void *) passed to
-this function was not valid.
+failure indicates that the RMr context (a void pointer passed
+to this function was not valid.
SEE ALSO
--------------------------------------------------------------------------------------------
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
+that received the message. The thread invoking the
+*rmr_mt_call()* will block until a message arrives or until
*timeout* milliseconds has passed; which ever comes first.
Using a timeout value of zero (0) will cause the thread to
block without a timeout.
-The * id * supplied as the third parameter is an integer in
-the range of 2 through 255 inclusive. This is a caller
-defined "thread number" and is used to match the response
-message with the correct user application thread. If the ID
-value is not in the proper range, the attempt to make the
-call will fail.
+The *id* supplied as the third parameter is an integer in the
+range of 2 through 255 inclusive. This is a caller defined
+"thread number" and is used to match the response message
+with the correct user application thread. If the ID value is
+not in the proper range, the attempt to make the call will
+fail.
Messages which are received while waiting for the response
are queued on a *normal* receive queue and will be delivered
-to the user application with the next invocation of *
-rmr_mt_rcv() * or * rmr_rvv_msg().* by RMR, and are returned
+to the user application with the next invocation of
+*rmr_mt_rcv()* or *rmr_rvv_msg().* by RMR, and are returned
to the user application when rmr_rcv_msg is invoked. These
messages are returned in th order received, one per call to
rmr_rcv_msg.
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
+the application uses the *rmr_rts_msg()* function and does
not adjust the transaction ID.
Retries
RMR_ERR_NOTSUPP
The multi-threaded option was not enabled when RMr was
- initialised. See the man page for *rmr_init() * for
+ initialised. See the man page for *rmr_init()* for
details.
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 will be RMR_OK when the send was successful.
When the message cannot be successfully sent this function
will return the unsent (original) message buffer with the
-state set to indicate the reason for failure. The value of *
-errno * may also be set to reflect a more detailed failure
+state set to indicate the reason for failure. The value of
+*errno* may also be set to reflect a more detailed failure
reason if it is known.
In the event of extreme failure, a NULL pointer is returned.
documentation, but there will be little that the user
application can do other than to move on.
+**CAUTION:** In some cases it is extremely likely that the
+message returned by the send function does **not** reference
+the same memory structure. Thus is important for the user
+programme to capture the new pointer for future use or to be
+passed to rmr_free(). If you are experiencing either double
+free errors or segment faults in either rmr_free() or
+rmr_send_msg(), ensure that the return value from this
+function is being captured and used.
+
ERRORS
--------------------------------------------------------------------------------------------
}
// reference payload and fill in message type
pm = (msg_t*) send_msg->payload;
- send_msg->mtype = MT_ANSWER;
- msg->len = generate_data( pm ); e// something that fills the payload in
- msg = rmr_send_msg( mr, send_msg );
+ send_msg->mtype = MT_ANSWER;
+ msg->len = generate_data( pm ); // something that fills the payload in
+ msg = rmr_send_msg( mr, send_msg ); // ensure new pointer used after send
mif( ! msg ) {
m !return ERROR;
m} else {
m sif( msg->state != RMR_OK ) {
- m s m// check for eagain, and resend if needed
+ m s m// check for RMR_ERR_RETRY, and resend if needed
m s m// else return error
m s}
m}
mreturn OK;
- m r ;
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
+either a *timeout* or *again* completion value. (Send
operations include all of the possible message send
-functions: * rmr_send_msg(), rmr_call(), rmr_rts_msg() * and
-* rmr_wh_send_msg(). * The * rloops * parameter sets the
-maximum number of retry loops that will be attempted before
-giving up and returning the unsuccessful state to the user
-application. Each retry loop is approximately 1000 attempts,
-and RMr does ** not ** invoke any sleep function between
-retries in the loop; a small, 1 mu-sec, sleep is executed
-between loop sets if the * rloops * value is greater than 1.
+functions: *rmr_send_msg(), rmr_call(), rmr_rts_msg()* and
+*rmr_wh_send_msg().* The *rloops* parameter sets the maximum
+number of retry loops that will be attempted before giving up
+and returning the unsuccessful state to the user application.
+Each retry loop is approximately 1000 attempts, and RMr does
+**not** invoke any sleep function between retries in the
+loop; a small, 1 mu-sec, sleep is executed between loop sets
+if the *rloops* value is greater than 1.
Disabling Retries
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-By default, the send operations will execute with an * rloop
-* setting of 1; each send operation will attempt to resend
-the message approximately 1000 times before giving up. If the
+By default, the send operations will execute with an *rloop*
+setting of 1; each send operation will attempt to resend the
+message approximately 1000 times before giving up. If the
user application does not want to have send operations retry
-when the underlying transport mechanism indicates * timeout *
-or * again, * the application should invoke this function and
-pass a value of 0 (zero) for * rloops. * With this setting,
-all RMr send operations will attempt a send operation only **
-once, ** returning immediately to the caller with the state
+when the underlying transport mechanism indicates *timeout*
+or *again,* the application should invoke this function and
+pass a value of 0 (zero) for *rloops.* With this setting, all
+RMr send operations will attempt a send operation only
+**once,** returning immediately to the caller with the state
of that single attempt.
RETURN VALUE
--------------------------------------------------------------------------------------------
-This function returns a -1 to indicate that the * rloops *
-value could not be set, and the value * RMR_OK * to indicate
+This function returns a -1 to indicate that the *rloops*
+value could not be set, and the value *RMR_OK* to indicate
success.
ERRORS
--------------------------------------------------------------------------------------------
-Currently errno is ** not ** set by this function; the only
-cause of a failure is an invalid context (* vctx *) pointer.
+Currently errno is **not** set by this function; the only
+cause of a failure is an invalid context (*vctx*) pointer.
EXAMPLE
--------------------------------------------------------------------------------------------
--------------------------------------------------------------------------------------------
The rmr_str2meid function will copy the string pointed to by
-src to the managed equipment ID (meid) field in the given
+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
Code Review / ric-plt / lib / rmr.git / blobdiff