&ex_start
#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 );
&ex_end
&uindent
&space
&ital(Port) is used to listen for connection requests from other RMR based applications.
-The &ital(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 &bold(both) the maximum payload size &bold(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.
+The &ital(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 &bold(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.
&space
-&ital(Flags) allows for selection of some RMr options at the time of initialisation.
-These are set by ORing &cw(RMRFL) constants from the RMr header file. Currently the
+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.
+
+&space
+&ital(Flags) allows for selection of some RMR options at the time of initialisation.
+These are set by ORing &cw(RMRFL) constants from the RMR header file. Currently the
following flags are supported:
&half_space
&half_space
&ditem(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.
+ by the route table generator application if it is based on RMR.
&half_space
&ditem(RMRFL_MTCALL)
&space
Multi-threaded call support requires the user application to specifically enable it
-when RMr is initialised.
+when RMR is initialised.
This is necessary because a second, dedicated, receiver thread must be started, and
requires all messages to be examined and queued by this thread.
-The additional overhead is minimal, queuing information is all in the RMr message
+The additional overhead is minimal, queuing information is all in the RMR message
header, but as an additional process is necessary the user application must "opt in"
to this approach.
.im &{lib}/man/env_var_list.im
&h2(RETURN VALUE)
-The &cw(rmr_init) function returns a void pointer (a contex if you will) that is passed
+The &cw(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 &cw(rmr_init) is unable to properly initialise the environment, NULL is returned and
errno is set to an appropriate value.
Code Review / ric-plt / lib / rmr.git / blobdiff