SourcePro C++ 12.0
SourcePro® C++ API Reference Guide
SourcePro C++
Documentation Home
SourcePro C++ 12.0 |
SourcePro® C++ API Reference Guide |
SourcePro C++ Documentation Home |
Base class that provides buffered producer-consumer synchronization semantics for exchanging guarded values between cooperating threads. More...
#include <rw/itc/RWTPCValBufferBaseGuarded.h>
Public Member Functions | |
| void | write (const Type &value) |
| bool | tryWrite (const Type &value) |
| RWWaitStatus | write (const Type &value, unsigned long milliseconds) |
| Type | peek (void) |
| Type | read (void) |
| RWWaitStatus | read (Type &result, unsigned long milliseconds) |
| RWWaitStatus | peek (Type &result, unsigned long milliseconds) |
| bool | tryPeek (Type &value) |
| bool | tryRead (Type &value) |
| void | write (const Type &value, const RWTFunctorR0< bool > &guard) |
| bool | tryWrite (const Type &value, const RWTFunctorR0< bool > &guard) |
| RWWaitStatus | write (const Type &value, const RWTFunctorR0< bool > &guard, unsigned long milliseconds) |
| virtual | ~RWTPCValBufferBaseGuarded (void) |
RWTPCValBufferBaseGuarded<Type,GuardDecorator> is the base class for the family of classes that provides buffered producer-consumer synchronization semantics for exchanging guarded 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 guard functor that is used during read operations to determine whether the associated value is currently eligible for retrieval from the buffer. The template parameter GuardDecorator identifies the class that is used to encapsulate the value, guard function, 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 RWTPCValBufferBaseGuarded< Type, GuardDecorator >::~RWTPCValBufferBaseGuarded | ( | void | ) | [virtual] |
Virtual destructor.
| RWWaitStatus RWTPCValBufferBaseGuarded< Type, GuardDecorator >::peek | ( | Type & | result, | |
| unsigned long | milliseconds | |||
| ) | [inline] |
Traverses the buffer, in an order that is determined by the implementation supplied in derived classes, until it finds a value whose guard functor is undefined or evaluates to true. At this point the function copies the value into the instance passed as a reference, and returns RW_THR_COMPLETED to indicate that the read succeeded. If the buffer is open and there are no values whose guard functors evaluate to true, or if the buffer is empty, this function blocks the calling thread until another value is inserted into the buffer, or until the buffer is closed, or until the specified amount of time passes. If no value becomes available within the specified amount of time, the function returns with a value of RW_THR_TIMEOUT. If the buffer is closed, and is empty or contains no readable entries, this function immediately returns by throwing an RWTHRClosedException.
Each time a new value is written into the buffer, one waiting reader thread is unblocked to give it a chance to re-evaluate the contents of the buffer, including the new entry. Since a write operation only unblocks a single waiting reader thread, any other threads that are waiting to peek or read remain blocked even if the most recent transfer produces a change in program state that would cause one or more guard functors to evaluate to true. This means that developers should use a single thread to read from a guarded buffer; additional threads could potentially be stuck waiting for write operations even when there are entries eligible for reading.
If the buffer is closed while a thread is blocked within this function, that thread is unblocked, after which, this function re-evaluates the guard functors one last time. If it finds a value whose functor evaluates to true, it returns that value, otherwise it returns by throwing an RWTHRClosedException.
While this function guarantees that it will wait for a period of time equal to or greater than the specified number of milliseconds, it cannot guarantee that the thread will actually be scheduled for execution at the end of the time-out period, and cannot prevent the individual guard functors from blocking the caller for indefinite periods of time.
Reimplemented from RWTPCValBufferBaseDecorated< Type, GuardDecorator >.
| Type RWTPCValBufferBaseGuarded< Type, GuardDecorator >::peek | ( | void | ) | [inline] |
Traverses the buffer, in an order that is determined by the implementation supplied in derived classes, until it finds a value whose guard functor is undefined or evaluates to true, at which point the function copies the value and returns it. If the buffer is open and there are no values whose guard functors evaluate to true, or if the buffer is empty, this function blocks the calling thread until another value is inserted into the buffer, or until the buffer is closed. If the buffer is closed, and is empty or contains no readable entries, this function immediately returns by throwing an RWTHRClosedException.
Each time a new value is written into the buffer, one waiting reader thread is unblocked to give it a chance to re-evaluate the contents of the buffer, including the new entry. Since a write operation only unblocks a single waiting reader thread, any other threads that are waiting to peek or read remain blocked even if the most recent transfer produces a change in program state that would cause one or more guard functors to evaluate to true. This means that developers should use a single thread to read from a guarded buffer; additional threads could potentially be stuck waiting for write operations even when there are entries eligible for reading.
If the buffer is closed while a thread is blocked within this function, that thread is unblocked, after which this function re-evaluates the guard functors one last time. If it finds a value whose functor evaluates to true, it returns that value, otherwise it returns by throwing an RWTHRClosedException.
Reimplemented from RWTPCValBufferBaseDecorated< Type, GuardDecorator >.
| RWWaitStatus RWTPCValBufferBaseGuarded< Type, GuardDecorator >::read | ( | Type & | result, | |
| unsigned long | milliseconds | |||
| ) | [inline] |
Traverses the buffer, in an order that is determined by the implementation supplied in derived classes, until it finds a value whose guard functor is undefined or evaluates to true. At this point the function removes the value and copies it into the instance passed as a reference, and returns RW_THR_COMPLETED to indicate that the read succeeded. If the buffer is open and there are no values whose guard functors evaluate to true, or if the buffer is empty, this function blocks the calling thread until another value is inserted into the buffer, or until the buffer is closed, or until the specified amount of time passes. If no value becomes available within the specified amount of time, the function returns with a value of RW_THR_TIMEOUT. If the buffer is closed, and is empty or contains no readable entries, this function immediately returns by throwing an RWTHRClosedException.
Each time a new value is written into the buffer, one waiting reader thread is unblocked to give it a chance to re-evaluate the contents of the buffer, including the new entry. Since a write operation only unblocks a single waiting reader thread, any other threads that are waiting to peek or read remain blocked even if the most recent transfer produces a change in program state that would cause one or more guard functors to evaluate to true. This means that developers should use a single thread to read from a guarded buffer; additional threads could potentially be stuck waiting for write operations even when there are entries eligible for reading.
If the buffer is closed while a thread is blocked within this function, that thread is unblocked, after which, this function re-evaluates the guard functors one last time. If it finds a value whose functor evaluates to true, it returns that value, otherwise it returns by throwing an RWTHRClosedException.
While this function guarantees that it will wait for a period of time equal to or greater than the specified number of milliseconds, it cannot guarantee that the thread will actually be scheduled for execution at the end of the time-out period, and cannot prevent the individual guard functors from blocking the caller for indefinite periods of time.
Reimplemented from RWTPCValBufferBaseDecorated< Type, GuardDecorator >.
| Type RWTPCValBufferBaseGuarded< Type, GuardDecorator >::read | ( | void | ) | [inline] |
Traverses the buffer, in an order that is determined by the implementation supplied in derived classes, until it finds a value whose guard functor is undefined or evaluates to true, at which point the function removes the value and returns it. If the buffer is open and there are no values whose guard functors evaluate to true, or if the buffer is empty, this function blocks the calling thread until another value is inserted into the buffer, or until the buffer is closed. If the buffer is closed, and is empty or contains no readable entries, this function immediately returns by throwing an RWTHRClosedException.
Each time a new value is written into the buffer, one waiting reader thread is unblocked to give it a chance to re-evaluate the contents of the buffer, including the new entry. Since a write operation only unblocks a single waiting reader thread, any other threads that are waiting to peek or read remain blocked even if the most recent transfer produces a change in program state that would cause one or more guard functors to evaluate to true. This means that developers should use a single thread to read from a guarded buffer; additional threads could potentially be stuck waiting for write operations even when there are entries eligible for reading.
If the buffer is closed while a thread is blocked within this function, that thread is unblocked, after which this function re-evaluates the guard functors one last time. If it finds a value whose functor evaluates to true, it returns that value, otherwise it returns by throwing an RWTHRClosedException.
Reimplemented from RWTPCValBufferBaseDecorated< Type, GuardDecorator >.
| bool RWTPCValBufferBaseGuarded< Type, GuardDecorator >::tryPeek | ( | Type & | value | ) | [inline] |
Traverses the buffer, in an order that is determined by the implementation supplied in derived classes, until it finds a value whose guard functor is undefined or evaluates to true. At this point, the function copies the value into the instance passed as a reference, and returns true to indicate that the read succeeded. If the buffer is open and there are no values whose guard functors evaluate to true, or if the buffer is empty, this function immediately returns false to indicate that the read was unsuccessful. If the buffer is closed, and is empty or contains no readable values, this function immediately returns by throwing an RWTHRClosedException.
While these functions do not directly block the caller if the buffer is empty or contains no readable values, they cannot prevent the individual guard functors from indirectly blocking the caller.
Reimplemented from RWTPCValBufferBaseDecorated< Type, GuardDecorator >.
| bool RWTPCValBufferBaseGuarded< Type, GuardDecorator >::tryRead | ( | Type & | value | ) | [inline] |
Traverses the buffer, in an order that is determined by the implementation supplied in derived classes, until it finds a value whose guard functor is undefined or evaluates to true. At this point, the function removes the value and copies it into the instance passed as a reference, and returns true to indicate that the read succeeded. If the buffer is open and there are no values whose guard functors evaluate to true, or if the buffer is empty, this function immediately returns false to indicate that the read was unsuccessful. If the buffer is closed, and is empty or contains no readable values, this function immediately returns by throwing an RWTHRClosedException.
While these functions do not directly block the caller if the buffer is empty or contains no readable values, they cannot prevent the individual guard functors from indirectly blocking the caller.
Reimplemented from RWTPCValBufferBaseDecorated< Type, GuardDecorator >.
| bool RWTPCValBufferBaseGuarded< Type, GuardDecorator >::tryWrite | ( | const Type & | value, | |
| const RWTFunctorR0< bool > & | guard | |||
| ) |
Inserts a guarded value into the buffer at a position that is 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 has been registered. The on-full callback functor is guaranteed to execute only within a writer thread. Calling this function on a full buffer results in the invocation of an on-full callback functor under either of these scenarios:
Repeated attempts to write to a full buffer does not result in repeated invocations of the callback functor. Once the full buffer is read from, however, it resets the callback trigger. If the buffer again becomes full, the first thread to attempt to write to it causes 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 guard is a reference to an RWTFunctorR0<bool> functor instance that is invoked during read() and peek() operations to determine whether the associated value is currently eligible for reading. An empty functor handle indicates that the entry is always eligible for reading. The functor must not attempt to access the buffer instance, as such access results in deadlock.
Reimplemented in RWTPCValBufferBaseGuardedPrioritized< Type, GuardAndPriorityDecorator >, and RWTPCValBufferBaseGuardedPrioritized< Type, RWTGuardAndPriorityDecorator< Type > >.
| bool RWTPCValBufferBaseGuarded< Type, GuardDecorator >::tryWrite | ( | const Type & | value | ) | [inline] |
Inserts a decorated value into the buffer at a position that is 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. The value is decorated using the defaults defined 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 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 has been registered. The on-full callback functor is guaranteed to execute only within a writer thread. Calling this function on a full buffer results in the invocation of an on-full callback functor under either of these scenarios:
Repeated attempts to write to a full buffer does not result in repeated invocations of the callback functor. Once the full buffer is read from, however, it resets the callback trigger. If the buffer again becomes full, the first thread to attempt to write to it causes another invocation of the on-full callback.
While this function guarantees not to block the caller if the buffer is full, this function cannot prevent the on-full callback functor, if executed, from indirectly blocking the caller.
This function takes the parameter value, which is a const reference to an instance of the type used to instantiate this template class.
Reimplemented from RWTPCValBufferBaseDecorated< Type, GuardDecorator >.
Reimplemented in RWTPCValBufferBaseGuardedPrioritized< Type, GuardAndPriorityDecorator >, and RWTPCValBufferBaseGuardedPrioritized< Type, RWTGuardAndPriorityDecorator< Type > >.
| RWWaitStatus RWTPCValBufferBaseGuarded< Type, GuardDecorator >::write | ( | const Type & | value, | |
| const RWTFunctorR0< bool > & | guard, | |||
| unsigned long | milliseconds | |||
| ) |
Inserts a guarded value into the buffer at a position that is 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 has passed. 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, 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 has been registered. The on-full callback functor is guaranteed to execute only within a writer thread. Calling this function on a full buffer results in the invocation of an on-full callback functor under either of these scenarios:
Repeated attempts to write to a full buffer does not result in repeated invocations of the callback functor. Once the full buffer is read from, however, it resets the callback trigger. If the buffer again becomes full, the first thread to attempt to write to it causes 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:
const reference to an instance of the type used to instantiate this template class.unsigned long value that specifies the maximum number of milliseconds to wait for the operation to complete. Reimplemented in RWTPCValBufferBaseGuardedPrioritized< Type, GuardAndPriorityDecorator >, and RWTPCValBufferBaseGuardedPrioritized< Type, RWTGuardAndPriorityDecorator< Type > >.
| void RWTPCValBufferBaseGuarded< Type, GuardDecorator >::write | ( | const Type & | value, | |
| const RWTFunctorR0< bool > & | guard | |||
| ) |
Inserts a guarded value into the buffer at a position that is 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, 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 has been registered. The on-full callback functor is guaranteed to execute only within a writer thread. Calling this function on a full buffer results in the invocation of an on-full callback functor under either of these scenarios:
Repeated attempts to write to a full buffer does not result in repeated invocations of the callback functor. Once the full buffer is read from, however, it resets the callback trigger. If the buffer again becomes full, the first thread to attempt to write to it causes 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 guard is a reference to an RWTFunctorR0<bool> functor instance that is invoked during read() and peek() operations to determine whether the associated value is currently eligible for reading. An empty functor handle indicates that the entry is always eligible for reading. The functor must not attempt to access the buffer instance as such access results in deadlock.
Reimplemented in RWTPCValBufferBaseGuardedPrioritized< Type, GuardAndPriorityDecorator >, and RWTPCValBufferBaseGuardedPrioritized< Type, RWTGuardAndPriorityDecorator< Type > >.
| RWWaitStatus RWTPCValBufferBaseGuarded< Type, GuardDecorator >::write | ( | const Type & | value, | |
| unsigned long | milliseconds | |||
| ) | [inline] |
Inserts a decorated value into the buffer at a position that is determined by the implementation supplied in derived classes. The value is decorated using the defaults defined 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 a value of 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 has 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 has been registered. The on-full callback functor is guaranteed to execute only within a writer thread. Calling this function on a full buffer results in the invocation of an on-full callback functor under either of these scenarios:
Repeated attempts to write to a full buffer does not result in repeated invocations of the callback functor. Once the full buffer is read from, however, it resets the callback trigger. If the buffer again becomes full, the first thread to attempt to write to it causes another invocation of the on-full callback.
While this function guarantees to wait, if necessary, for a 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, if executed, from indirectly blocking the caller for an indefinite period of time.
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 milliseconds is an unsigned long value that specifies the maximum number of milliseconds to wait for the operation to complete.
Reimplemented from RWTPCValBufferBaseDecorated< Type, GuardDecorator >.
Reimplemented in RWTPCValBufferBaseGuardedPrioritized< Type, GuardAndPriorityDecorator >, and RWTPCValBufferBaseGuardedPrioritized< Type, RWTGuardAndPriorityDecorator< Type > >.
| void RWTPCValBufferBaseGuarded< Type, GuardDecorator >::write | ( | const Type & | value | ) | [inline] |
Inserts a decorated value into the buffer at a position that is determined by the implementation supplied in derived classes. The value is decorated using the defaults defined 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 yet 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, 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 has been registered. The on-full callback functor is guaranteed to execute only within a writer thread. Calling this function on a full buffer results in the invocation of an on-full callback functor under either of these scenarios:
Repeated attempts to write to a full buffer does not result in repeated invocations of the callback functor. Once the full buffer is read from, however, it resets the callback trigger. If the buffer again becomes full, the first thread to attempt to write to it causes another invocation of the on-full callback.
Reimplemented from RWTPCValBufferBaseDecorated< Type, GuardDecorator >.
Reimplemented in RWTPCValBufferBaseGuardedPrioritized< Type, GuardAndPriorityDecorator >, and RWTPCValBufferBaseGuardedPrioritized< Type, RWTGuardAndPriorityDecorator< Type > >.
© 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.