RWTPCValBufferBasePrioritized<Type,PriorityDecorator>

Module:  Threads   Package:  Interthread Communication

RWTPCValBufferBasePrioritized<Type,PriorityDecorator>  
   (virtual) RWTPCValBufferBaseDecorated<Type,PriorityDecorator>

• Local Index
• Header File
• Description
• Public Destructor
• Inherited Functions
• Public Member Functions
• See Also

Members

RWTPCValBufferBasePrioritized()

tryWrite()

write()

#include <rw/itc/RWTPCValBufferBasePrioritized.h>

RWTPCValBufferBasePrioritized is the base class for the family of classes that provide producer-consumer synchronization semantics for exchanging prioritized values between cooperating threads.

In the producer-consumer synchronization model, reader threads (consumers) are blocked while a buffer is empty, and writer threads (producers) are blocked while a buffer is full. A buffer is considered full when the number of unread entries equals or exceeds some user-specified maximum capacity.

The write operations provided by this class and its subclasses bind additional data items to each value prior to storing that value in an internal buffer. One of these additional data items, or decorations, is a priority value that is used during write operations to determine a value's insertion point within the buffer, such that the set of unread values will be retrieved in priority order when eventually read from the buffer. The template parameter PriorityDecorator identifies the class that is used to encapsulate both the data value, priority value, and any other decorations as a single object for storage in the internal buffer. The decorator classes used by subclasses to instantiate this class are intended for the module's internal use, and are not documented as part of the public interface.

virtual
~RWTPCValBufferBasePrioritized();

Virtual destructor.

The following superclass functions have been redeclared or redefined to allow them to be overloaded within in this class:

bool         tryWrite(const Type& value);
void         write(const Type& value);
RWWaitStatus write(const Type& value, unsigned long milliseconds);

These functions provide the same capabilities and behavior as their counterparts in this class, except that these functions attach a priority value of zero to each value.

bool 
tryWrite(long priority, const Type& value);

Inserts a value with the specified priority into the buffer at a position determined by the implementation supplied in derived classes, but only if the value may be written immediately; in other words, only if there is sufficient free capacity.

If the buffer is open and has sufficient capacity to hold another value, this function inserts the value, and returns a value of true to indicate that the write succeeded. If the buffer is open and full, this function immediately returns a value of false to indicate that the write was unsuccessful. If the buffer is closed, this function immediately returns by throwing an RWTHRClosedException.

Calling this function on a full buffer may result in the invocation of the on-full callback functor, if a valid one was registered. The on-full callback functor is guaranteed to execute only within a writer thread. Calling this function on a full buffer will result in the invocation of an on-full callback functor under either of these scenarios:

• The calling thread is waiting on an full buffer when an on-full callback is registered.

• The calling thread is the first to attempt writing to a full buffer in which an on-full callback was previously registered.

Repeated attempts to write to a full buffer will not result in repeated invocations of the callback functor. Once the full buffer is read from, however, it resets the callback trigger; should the buffer again become full, the first thread to attempt to write will cause another invocation of the on-full callback.

While this function guarantees not to block the caller if the buffer is full, it cannot prevent the on-full callback functor, if executed, from indirectly blocking the caller.

This function takes two parameters. The parameter value is a const reference to an instance of the type used to instantiate this template class. The parameter priority is a long that is used to determine the insertion point of the value with the buffer. A value with a greater priority value will be positioned to be read before a value of lower priority. Values of equal priority will be positioned as determined by the implementation supplied in derived classes.

void 
write(long priority, const Type& value);

Inserts a value with the specified priority into the buffer at a position determined by the implementation supplied in derived classes.

If the buffer is open and has sufficient capacity to hold another value, this function inserts the value. If the buffer is open and full, this function blocks the calling thread until the buffer is no longer full (because another thread or threads have read values or have changed the maximum capacity), or until the buffer is closed.

If the buffer is closed while the calling thread is blocked and waiting within this function for room to write, the calling thread is unblocked and the function returns by throwing an RWTHRClosedException. If the buffer is already closed when this function is called, it immediately returns by throwing an RWTHRClosedException.

Calling this function on a full buffer may result in the invocation of the on-full callback functor, if a valid one was registered. The on-full callback functor is guaranteed to execute only within a writer thread. Calling this function on a full buffer will result in the invocation of an on-full callback functor under either of these scenarios:

• The calling thread is waiting on an full buffer when an on-full callback is registered.

• The calling thread is the first to attempt writing to a full buffer in which an on-full callback was previously registered.

Repeated attempts to write to a full buffer will not result in repeated invocations of the callback functor. Once the full buffer is read from, however, it resets the callback trigger; should the buffer again become full, the first thread to attempt to write will cause another invocation of the on-full callback.

This function takes two parameters. The parameter value is a const reference to an instance of the type used to instantiate this template class. The parameter priority is a long that is used to determine the insertion point of the value with the buffer. A value with a greater priority value will be positioned so it will be read before a value of lower priority, and for values of equal priority, in a position determined by the implementation supplied in derived classes.

RWWaitStatus 
write(long priority, const Type& value, 
      unsigned long milliseconds);

Inserts a value with the specified priority into the buffer at a position determined by the implementation supplied in derived classes.

If the buffer is open and has sufficient capacity to hold another value, this function inserts the value and returns RW_THR_COMPLETED to indicate that the write succeeded. If the buffer is open and full, this function blocks the calling thread until the buffer is no longer full (because another thread or threads have read values or have changed the maximum capacity), or until the buffer is closed, or until the specified amount of time passes. If sufficient space does not become available within the specified amount of time, the function returns a value of RW_THR_TIMEOUT.

If the buffer is closed while the calling thread is blocked and waiting within this function for room to write, the calling thread is unblocked and the function returns by throwing an RWTHRClosedException. If the buffer is already closed when this function is called, the function immediately returns by throwing an RWTHRClosedException.

Calling this function on a full buffer may result in the invocation of the on-full callback functor, if a valid one was registered. The on-full callback functor is guaranteed to execute only within a writer thread. Calling this function on a full buffer will result in the invocation of an on-full callback functor under either of these scenarios:

• The calling thread is waiting on an full buffer when an on-full callback is registered.

• The calling thread is the first to attempt writing to a full buffer in which an on-full callback was previously registered.

Repeated attempts to write to a full buffer will not result in repeated invocations of the callback functor. Once the full buffer is read from, however, it resets the callback trigger; should the buffer again become full, the first thread to attempt to write will cause another invocation of the on-full callback.

While this function guarantees to wait, if necessary, for a period time equal to or greater than the specified number of milliseconds, it cannot guarantee that the thread is actually scheduled for execution at the end of the time-out period. It cannot prevent the on-full callback functor from indirectly blocking the caller for an indefinite period of time.

This function takes three parameters:

• The parameter priority is a long that is used to determine the insertion point of the value with the buffer. A value with a greater priority value will be positioned to be read before a value of lower priority. Values of equal priority will be positioned to be read as determined by the implementation supplied in derived classes.

• The parameter value is a const reference to an instance of the type used to instantiate this template class.

• The parameter milliseconds is an unsigned long value that specifies the maximum number of milliseconds to wait for the operation to complete.

RWTPCValBufferBaseDecorated<Type,Decorator>,RWTPCValQueuePrioritized<Type>, RWTPCValStackPrioritized<Type>,RWTPCValBufferBaseGuardedPrioritized<...>

© Copyright Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.