RWTPCPtrBufferBase< Type > Class Template Reference

Base class that provides buffered producer-consumer synchronization semantics for exchanging pointer values between cooperating threads. More...

#include <rw/itc/RWTPCPtrBufferBase.h>

Inheritance diagram for RWTPCPtrBufferBase< Type >:

Public Member Functions
virtual	~RWTPCPtrBufferBase (void)
RWWaitStatus	peek (Type *&value, unsigned long milliseconds)
Type *	peek (void)
RWWaitStatus	read (Type *&value, unsigned long milliseconds)
Type *	read (void)
bool	tryPeek (Type *&result)
bool	tryRead (Type *&result)
bool	tryWrite (Type *value)
void	write (Type *value)
RWWaitStatus	write (Type *value, unsigned long milliseconds)
Public Member Functions inherited from RWPCBufferBase
virtual	~RWPCBufferBase (void)
bool	canRead (void) const
bool	canWrite (void) const
void	close (void)
size_t	entries (void) const
void	flush (void)
size_t	getCapacity (void) const
RWTFunctor< void()>	getCloseCallback (void) const
RWTFunctor< void()>	getEmptyCallback (void) const
RWTFunctor< void()>	getFullCallback (void) const
RWTFunctor< void()>	getOpenCallback (void) const
bool	isOpen (void) const
void	open (void)
size_t	setCapacity (size_t maxCapacity)
void	setCloseCallback (const RWTFunctor< void()> &onCloseCallback)
void	setEmptyCallback (const RWTFunctor< void()> &onEmptyCallback)
void	setFullCallback (const RWTFunctor< void()> &onFullCallback)
void	setOpenCallback (const RWTFunctor< void()> &onOpenCallback)

Additional Inherited Members
Protected Types inherited from RWTMonitor< RWMutexLock >
typedef RWTLockGuard< RWTMonitor< RWMutexLock > >	LockGuard
typedef RWTTryLockGuard< RWTMonitor< RWMutexLock > >	TryLockGuard
typedef RWTUnlockGuard< RWTMonitor< RWMutexLock > >	UnlockGuard
Protected Member Functions inherited from RWTMonitor< RWMutexLock >
	RWTMonitor (const RWTMonitor< RWMutexLock > &second)
	RWTMonitor (RWStaticCtor)
	RWTMonitor (void)
	~RWTMonitor (void)
void	acquire (void)
bool	isAcquired (void) const
RWTMonitor< RWMutexLock > &	monitor (void) const
RWMutexLock &	mutex (void)
RWTMonitor< RWMutexLock > &	operator= (const RWTMonitor< RWMutexLock > &)
void	release (void)
bool	tryAcquire (void)

Detailed Description

template<class Type>
class RWTPCPtrBufferBase< Type >

RWTPCPtrBufferBase is the base class for the family of classes that provides buffered producer-consumer synchronization semantics for exchanging pointer 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.

Constructor & Destructor Documentation

~RWTPCPtrBufferBase()

template<class Type >

virtual RWTPCPtrBufferBase< Type >::~RWTPCPtrBufferBase ( void )

virtual

Virtual destructor.

Member Function Documentation

peek() [1/2]

template<class Type >

RWWaitStatus RWTPCPtrBufferBase< Type >::peek	(	Type *&	value,
		unsigned long	milliseconds )

Copies and returns the next available value stored in the buffer, where the availability and ordering of values is determined by the implementation supplied in derived classes.

If the buffer contains a value, this function copies that value into the instance passed as a reference, and returns a value of RW_THR_COMPLETED to indicate that the read succeeded. If the buffer is open and yet empty, this function blocks the calling thread until a value becomes available, 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 a value of RW_THR_TIMEOUT.

If the buffer is closed while the calling thread is blocked and waiting within this function for a value to become available, the calling thread is unblocked and the function returns by throwing an RWTHRClosedException. If the buffer is both empty and closed when this function is called, the function immediately returns by throwing an RWTHRClosedException.

Calling this function on an empty buffer may result in the invocation of the on-empty callback functor, if a valid one has been registered. The on-empty callback functor is guaranteed to execute only within a reader thread. Calling this function on an empty buffer results in the invocation of an on-empty callback functor under either of these scenarios:

• The calling thread is waiting on an empty buffer when an on-empty callback is registered.
• The calling thread is the first to attempt reading from an empty buffer in which an on-empty callback was previously registered.

Repeated attempts to read from an empty buffer does not result in repeated invocations of the callback functor. Once the empty buffer is written to, however, it resets the callback trigger. If the buffer again becomes empty, the first thread to attempt to read from it causes another invocation of the on-empty callback.

While this function guarantees to wait, if necessary, for a period of 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. The function cannot prevent the on-empty 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 reference to a pointer 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.

peek() [2/2]

template<class Type >

Type * RWTPCPtrBufferBase< Type >::peek

(

void

)

Copies and returns the next available value stored in the buffer, where the availability and ordering of values is determined by the implementation supplied in derived classes. The value returned is a pointer to an instance of the type used to instantiate this template class.

If the buffer contains a value, this function copies and returns that value even if the buffer is closed. If the buffer is open and empty, this function blocks the calling thread until a value becomes available or until the buffer is closed. If the buffer is closed while the calling thread is blocked and waiting within this function for a value to become available, the calling thread is unblocked and the function returns by throwing an RWTHRClosedException.

If the buffer is both empty and closed when this function is called, it immediately returns by throwing an RWTHRClosedException.

Calling this function on an empty buffer may result in the invocation of the on-empty callback functor, if a valid one has been registered. The on-empty callback functor is guaranteed to execute only within a reader thread. Calling this function on an empty buffer results in the invocation of an on-empty callback functor under either of these scenarios:

• The calling thread is waiting on an empty buffer when an on-empty callback is registered.
• The calling thread is the first to attempt reading from an empty buffer in which an on-empty callback was previously registered.

Repeated attempts to read from an empty buffer does not result in repeated invocations of the callback functor. Once the empty buffer is written to, however, it resets the callback trigger. If the buffer again becomes empty, the first thread to attempt to read from it causes another invocation of the on-empty callback.

read() [1/2]

template<class Type >

RWWaitStatus RWTPCPtrBufferBase< Type >::read	(	Type *&	value,
		unsigned long	milliseconds )

Removes and returns the next available value stored in the buffer, where the availability and ordering of values is determined by the implementation supplied in derived classes.

If the buffer contains a value, this function removes that value, copies it into the instance passed as a reference, and returns a value of RW_THR_COMPLETED to indicate that the read succeeded. If the buffer contains a value, this function removes and returns that value even if the buffer is closed. If the buffer is open and yet empty, this function blocks the calling thread until a value becomes available, 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 the value of RW_THR_TIMEOUT.

If the buffer is closed while the calling thread is blocked and waiting within this function for a value to become available, the calling thread is unblocked and the function returns by throwing an RWTHRClosedException. If the buffer is both empty and closed when this function is called, it immediately returns by throwing an RWTHRClosedException.

Calling this function on an empty buffer may result in the invocation of the on-empty callback functor, if a valid one has been registered. The on-empty callback functor is guaranteed to execute only within a reader thread. Calling this function on an empty buffer results in the invocation of an on-empty callback functor under either of these scenarios:

• The calling thread is waiting on an empty buffer when an on-empty callback is registered.
• The calling thread is the first to attempt reading from an empty buffer for which an on-empty callback was previously registered.

Repeated attempts to read from an empty buffer does not result in repeated invocations of the callback functor. Once the empty buffer is written to, however, it resets the callback trigger. If the buffer again becomes empty, the first thread to attempt to read from it causes another invocation of the on-empty callback.

While this function guarantees to wait, if necessary, for a period of 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-empty callback functor from indirectly blocking the caller for an indefinite period of time.

This function takes two parameters. The value parameter is a reference to a pointer 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.

read() [2/2]

template<class Type >

Type * RWTPCPtrBufferBase< Type >::read

(

void

)

Removes and returns the next available value stored in the buffer, where the availability and ordering of values is determined by the implementation supplied in derived classes. The value returned is a pointer to an instance of the type used to instantiate this template class.

If the buffer contains a value, this function removes and returns that value even if the buffer is closed. If the buffer is open and yet empty, this function blocks the calling thread until a value becomes available or until the buffer is closed.

If the buffer is closed while the calling thread is blocked and waiting within this function for a value to become available, the calling thread is unblocked and the function returns by throwing an RWTHRClosedException. If the buffer is both empty and closed when this function is called, the function immediately returns by throwing an RWTHRClosedException.

Calling this function on an empty buffer may result in the invocation of the on-empty callback functor, if a valid one has been registered. The on-empty callback functor is guaranteed to execute only within a reader thread. Calling this function on an empty buffer results in the invocation of an on-empty callback functor under either of these scenarios:

• The calling thread is waiting on an empty buffer when an on-empty callback is registered.
• The calling thread is the first to attempt reading from an empty buffer for which an on-empty callback was previously registered.

Repeated attempts to read from an empty buffer does not result in repeated invocations of the callback functor. Once the empty buffer is written to, however, it resets the callback trigger. If the buffer again becomes empty, the first thread to attempt to read from it causes another invocation of the on-empty callback.

tryPeek()

template<class Type >

bool RWTPCPtrBufferBase< Type >::tryPeek

(

Type *&

result

)

Copies and returns the next available value stored in the buffer, where the availability and ordering of values is determined by the implementation supplied in derived classes.

If the buffer contains a value, this function copies that value into the instance passed as a reference, and returns a value of true to indicate that the read succeeded. If the buffer is open and empty, this function immediately returns a value of false to indicate that the read was unsuccessful. If the buffer is both empty and closed, this function immediately returns by throwing an RWTHRClosedException.

Calling this function on an empty buffer may result in the invocation of the on-empty callback functor, if a valid one has been registered. The on-empty callback functor is guaranteed to execute only within a reader thread. Calling this function on an empty buffer results in the invocation of an on-empty callback functor under either of these scenarios:

• The calling thread is waiting on an empty buffer when an on-empty callback is registered.
• The calling thread is the first to attempt reading from an empty buffer in which an on-empty callback was previously registered.

Repeated attempts to read from an empty buffer does not result in repeated invocations of the callback functor. Once the empty buffer is written to, however, it resets the callback trigger. If the buffer again becomes empty, the first thread to attempt to read from it causes another invocation of the on-empty callback.

While this function guarantees not to block the caller if there are no readable entries, it cannot prevent the on-empty callback functor, if executed, from indirectly blocking the caller.

This function takes the parameter result, which is a reference to a pointer to an instance of the type used to instantiate this template class.

tryRead()

template<class Type >

bool RWTPCPtrBufferBase< Type >::tryRead

(

Type *&

result

)

Removes and returns the next available value stored in the buffer, where the availability and ordering of values is determined by the implementation supplied in derived classes.

If the buffer contains a value, this function removes that value, copies it into the instance passed as a reference, and returns a value of true to indicate that the read succeeded. If the buffer is open and yet empty, this function immediately returns a value of false to indicate that the read was unsuccessful. If the buffer is both empty and closed, this function immediately returns by throwing an RWTHRClosedException.

Calling this function on an empty buffer may result in the invocation of the on-empty callback functor, if a valid one has been registered. The on-empty callback functor is guaranteed to execute only within a reader thread. Calling this function on an empty buffer results in the invocation of an on-empty callback functor under either of these scenarios:

• The calling thread is waiting on an empty buffer when an on-empty callback is registered.
• The calling thread is the first to attempt reading from an empty buffer for which an on-empty callback was previously registered.

Repeated attempts to read from an empty buffer does not result in repeated invocations of the callback functor. Once the empty buffer is written to, however, it resets the callback trigger. If the buffer again becomes empty, the first thread to attempt to read from it causes another invocation of the on-empty callback.

While this function guarantees not to block the caller if there are no readable entries, this function cannot prevent the on-empty callback functor, if executed, from indirectly blocking the caller.

This function takes the parameter result, which is a reference to a pointer to an instance of the type used to instantiate this template class.

tryWrite()

template<class Type >

bool RWTPCPtrBufferBase< Type >::tryWrite

(

Type *

value

)

Inserts a 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:

• 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 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 the parameter value, which is a pointer to an instance of the type used to instantiate this template class.

write() [1/2]

template<class Type >

void RWTPCPtrBufferBase< Type >::write

(

Type *

value

)

Inserts a 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, 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:

• 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 for which an on-full callback was previously registered.

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 the parameter value, which is a pointer to an instance of the type used to instantiate this template class.

write() [2/2]

template<class Type >

RWWaitStatus RWTPCPtrBufferBase< Type >::write	(	Type *	value,
		unsigned long	milliseconds )

Inserts a 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 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 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, 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:

• 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 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 of time equal to or greater than the specified number of milliseconds, this function 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 pointer 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.