DSSX_Ordered
DSSX_Ordered
dssx
1998 12-06
CLASS
DSSX_Ordered - A DSS extended construct analogous to a stream
SYNOPSIS
This class provides a stream-like construct using DSS.
Byte blocks are sent to and received from a DSS_Ordered instance on a
first in first out (FIFO) basis.
DSSX_Ordered may also be configured to 'bundle' byte blocks (in local heap)
into larger messages before outing. This may be done to improve throughput in
high volume scenarios.
In order to do this an instance of DSSX_Ordered manages three bundle buffers
in local memory store. These three buffers are the out buffer, the in
buffer, and the read buffer.
The out buffer is used to build up a bundle of byte blocks until the byte
threshold is exceeded. The byte threshold is dynamicly configurable through
SetThreshold(). When the threshold is exceeded the bundle is sent (written
to the space).
Both the in and read buffers are used to obtain byte blocks that have been
sent. The In() function consumes byte blocks, or more precisely consumes
bundles. If the receive buffer is empty when In() is called the receive
buffer is filled by removing the next byte block bundle.
The Read() function does not consume bundles. When the read buffer is filled,
the corresponding bundle is simply read and still exists in the space.
PARENTS
CONSTRUCTOR
DSSX_Ordered(DSSX_Connection *connection, GPL_CharPtr &spacename, GPL_CharPtr &name, DSS_ChunkConfig *config)
Construct a DSSX_Ordered using connection in space spacename
named name. The config
argument is used to configure the actual DSS chunks that DSSX_Ordered is
implemented with.
MEMBER FUNCTIONS
long Out(char *buffer, unsigned long len)
Send byte block buffer of length len. If buffer
is set to NULL the out buffer will be flushed even if it is below the set
threshold. Return TRUE if flushed, FALSE otherwise.
long Out(GPL_Message *message)
A GPL_Message variant of Out().
Return TRUE if flushed, FALSE otherwise.
char *In(unsigned long *len)
Consume the next byte block to be received and return a pointer to the buffer.
The length of the buffer is return in len.
The space for the buffer is internally allocated and it is the caller's
responsibility to free the space when done.
void In(GPL_Message *message)
A GPL_Message variant of In().
char *Read(unsigned long *len)
Read the next byte block to be received and return a pointer to the buffer.
The length of the buffer is return in len.
The space for the buffer is internally allocated and it is the caller's
responsibility to free the space when done.
void Read(GPL_Message *message)
A GPL_Message variant of Read().
void SetThresholdSize(unsigned long thresh)
Set the threshold size to threshold.
If a Send() causes the out buffer to grow larger than this threshold, the
buffer is sent. The default setting for the threshold is 0 which will cause
every byte block to be sent immediately.
unsigned long GetThreshold()
Return the current threshold setting.
void SetMemoryLimit(unsigned long mlimit)
Set the memory limit for the DSSX_Ordered to mlimit. If the memory limit
is non-zero the DSSX_Ordered will check the space used before adding every
chunk to the space. If writing the chunk would put the memory used above
mlimit then DSSX_Ordered will wait until there is room before
writing. If mlimit is non-zero DSSX_Ordered will adjust the accounting
of memory used upon every In(). Note that every DSSX_Ordered class instance
created before a DSSX_Ordered::SetMemoryLimit() is called must call
SetMemoryLimit() in order to activate the accounting mechanism. However, any
DSSX_Ordered constructed after SetMemoryLimit() is called will automatically
activate the mechanism.
unsigned long GetMemoryLimit()
Return the current memory limit setting.
unsigned long GetBundleSize(long buffer_id)
Return the current byte size of the bundle buffer specified by
buffer_id. Valid values for buffer_id are:
| DSSX_ORDERED_OUT |
The out bundle
|
| DSSX_ORDERED_IN |
The in bundle
|
| DSSX_ORDERED_READ |
The read bundle
|
unsigned long GetBundleCount(long buffer_id)
Return the current number of byte blocks in the bundle specified by
buffer_id. Valid values for buffer_id are the same
as for GetBundleSize().
unsigned long GetIndex(long buffer_id)
Return the current index/count of the underlying DSS chunk corresponding to
the specified bundle.
void Invalidate()
Invalidate all of the DSS chunks used to implement the DSSX_Ordered. Any
member function (except the destructor) have undefined behavior after this
function is called.
void SetPause(long pause)
Set the pause per loop in milliseconds of the poll
based implementations of In() and Read().
If the pause is set less than 0 then a wait based implementation is used.
Otherwise the poll based implementation is used.
The default pause setting is DSSX_SPINPAUSE milliseconds.
Note that use of the GetIndex() member function will potentially cause deadlock
if the wait based implementation of In() or Read() is used.
long GetPause()
Return the current loop pause setting for In() and Read().
void SetBlocking(GPL_Boolean blocking)
Set the blocking mode to blocking. If blocking mode is set to TRUE (which
is the default) then all In() ans Read() calls will block until
data is available. If blocking mode is FALSE AND the poll based
implementation of In() and Read() is used (see SetPause()) then
In() ans Read() will return NULL if no data is available.
GPL_Boolean GetBlocking(void)
Return the current blocking mode.