RWPCBufferBase Class Reference

Base class for the family of classes that provide buffered producer-consumer synchronization semantics for exchanging data between cooperating threads. More...

#include <rw/itc/RWPCBufferBase.h>

Inheritance diagram for RWPCBufferBase:

Public Member Functions
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

RWPCBufferBase is the base class for the family of classes that provide buffered producer-consumer synchronization semantics for exchanging data 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 a specified maximum capacity.

Limit the maximum capacity of a buffer through either a constructor argument or the setCapacity() function. A maximum capacity value of zero results in a buffer that imposes no limit on the number of unread entries that may be inserted.

This class provides functions for opening and closing a buffer instance. By default, buffer instances are constructed in the open state. Any number of threads may read from, or write to, the buffer while the buffer is in the open state. Once closed, any entries that remain in the buffer may be safely read from the buffer, but any attempts to read from the buffer once it is empty, or any attempts to write to the buffer while it is closed, result in an exception being thrown.

A closed buffer may be reopened at any time. Attempts to close a buffer that is already closed, or to open a buffer that is already open, are ignored.

Single functors may be registered and invoked as callback objects for the following buffer events:

• on-empty A thread calls a read or peek function and finds that it is the first reader to discover that the buffer is empty.
• on-full A thread calls a write function and finds that it is the first writer to discover that the buffer is full.
• on-close A thread closes an open buffer.
• on-open A thread opens a closed buffer.

The public functions of this class are internally synchronized, and instances of this class are safe for use in the presence of multiple threads.

Constructor & Destructor Documentation

~RWPCBufferBase()

virtual RWPCBufferBase::~RWPCBufferBase ( void )

virtual

Virtual destructor.

Member Function Documentation

canRead()

bool RWPCBufferBase::canRead

(

void

)

const

Indicates whether or not the buffer contains any entries that may be read. Returns a bool value where:

• true indicates that the calling thread may read a value from the buffer without blocking, provided no other threads empty the buffer before the caller's attempt to read.
• false indicates that there are currently no values that may be read from the buffer. If the calling thread attempts to read from the buffer, it is blocked unless another thread writes a readable value into the buffer before the caller's attempt to read.

canWrite()

bool RWPCBufferBase::canWrite

(

void

)

const

Indicates whether or not the buffer is open and has enough room in which to write another entry. Returns a bool value where:

• true indicates that the calling thread may write a value to the buffer without blocking, provided no other threads fill the buffer or decrease the maximum capacity of the buffer before the caller's attempt to write.
• false indicates that the number of entries already equals or exceeds the maximum capacity of the buffer. Any attempt to write to the buffer blocks the writer thread, unless another thread removes one or more readable values from the buffer, or increases the maximum capacity of the buffer before the caller's attempt to write.

close()

void RWPCBufferBase::close

(

void

)

Closes the buffer to prohibit future data transfers. Any attempt to write to a closed buffer, or to read from a closed buffer that is already empty, produces an exception. Any entries already stored within the buffer at the time of its closing may still be read from without producing an exception.

If the buffer is empty and there are threads waiting to peek or to read from the buffer, this function unblocks these threads, and each thread exits its peek or read function with an exception. If the buffer is full and there are threads waiting to write to the buffer, this function unblocks these threads and each exits its write function with an exception.

entries()

size_t RWPCBufferBase::entries

(

void

)

const

Returns a size_t value representing the number of entries currently contained in the buffer.

flush()

void RWPCBufferBase::flush

(

void

)

Removes all entries currently stored in the buffer. If the buffer is full and there are threads waiting to write to the buffer, this function signals these threads that they may now attempt to write.

getCapacity()

size_t RWPCBufferBase::getCapacity

(

void

)

const

Returns a size_t value representing the current maximum capacity of the buffer. A value of zero indicates that the buffer has no capacity limit.

getCloseCallback()

RWTFunctor< void()> RWPCBufferBase::getCloseCallback

(

void

)

const

Returns the current on-close callback functor instance, if any. This is an RWTFunctor<void()> handle instance that identifies the functor to be invoked when the buffer is changed from the open to the closed state. The initial value of this callback-functor is an empty handle instance.

getEmptyCallback()

RWTFunctor< void()> RWPCBufferBase::getEmptyCallback

(

void

)

const

Returns the current on-empty callback functor instance, if any. This is an RWTFunctor<void()> handle instance identifying the functor that is invoked when the buffer enters the empty state.

getFullCallback()

RWTFunctor< void()> RWPCBufferBase::getFullCallback

(

void

)

const

Returns the current on-full callback functor instance, if any. This is an RWTFunctor<void()> handle instance that identifies the functor to be invoked when the buffer enters the full state.

getOpenCallback()

RWTFunctor< void()> RWPCBufferBase::getOpenCallback

(

void

)

const

Returns the current on-open callback functor instance, if any. This is an RWTFunctor<void()> handle instance that identifies the functor to be invoked when the buffer is changed from the closed to the opened state. The initial value of this callback-functor is an empty handle instance.

isOpen()

bool RWPCBufferBase::isOpen

(

void

)

const

Indicates whether the buffer is currently open for reading and writing. Returns a bool value where:

• true indicates that the buffer is open.
• false indicates that the buffer is closed.

open()

void RWPCBufferBase::open

(

void

)

Opens the buffer to allow data transfers. If this function is called on a buffer that is closed, the on-open callback functor is invoked within the calling thread.

setCapacity()

size_t RWPCBufferBase::setCapacity

(

size_t

maxCapacity

)

Sets the maximum capacity of the buffer. The parameter maxCapacity is a size_t value that specifies the maximum number of unread entries allowed to accumulate within the buffer. Once the number of entries equals or exceeds this number, any thread attempting to write an additional entry is blocked until an entry is removed by a read operation, or until the capacity is increased. A value of zero indicates that the buffer has no capacity limit, and that all write operations should complete without blocking. This function returns a size_t value representing the maximum capacity that existed at the time it was called.

setCloseCallback()

void RWPCBufferBase::setCloseCallback

(

const RWTFunctor< void()> &

onCloseCallback

)

Replaces the callback-functor, if any, to be invoked within the first thread to call close() on the open buffer instance. Subsequent calls to close() without any intervening calls to open() will not result in the invocation of the functor.

The functor instance passed as an argument to this function replaces any previously registered functor instance.

The parameter onCloseCallback is an RWTFunctor<void()> handle reference that identifies the functor to be invoked when the buffer is changed from the open to the closed state.

setEmptyCallback()

void RWPCBufferBase::setEmptyCallback

(

const RWTFunctor< void()> &

onEmptyCallback

)

Registers a callback-functor that is invoked by the first thread that attempts a read or peek operation after the last buffer entry is read, or by a thread that was already waiting within a read or peek operation at the time the callback was registered. Once a callback-functor is invoked by a reader thread, it is not invoked again until there is at least one intervening write operation to take the buffer out of the empty state.

The functor instance passed as an argument to this function replaces any previously registered functor instance.

The parameter onEmptyCallback is an RWTFunctor<void()> handle reference that identifies the functor to be invoked when the buffer enters the empty state.

setFullCallback()

void RWPCBufferBase::setFullCallback

(

const RWTFunctor< void()> &

onFullCallback

)

Registers a callback-functor to be invoked by the first thread that attempts a write operation after the buffer reaches its maximum capacity, or by a thread that was already waiting within a write operation at the time the callback was registered. Once a callback-functor is invoked by a writer thread, it is not invoked again until there is at least one intervening read operation to take the buffer out of the full state.

The functor instance passed as an argument to this function replaces any previously registered functor instance.

The parameter onFullCallback is an RWTFunctor<void()> handle reference that identifies the functor to be invoked when the buffer enters the full state.

setOpenCallback()

void RWPCBufferBase::setOpenCallback

(

const RWTFunctor< void()> &

onOpenCallback

)

Replaces the callback-functor, if any, to be invoked within the first thread to call open() on the closed buffer instance. Subsequent calls to open() without any intervening calls to close() will not result in the invocation of the functor.

The functor instance passed as an argument to this function replaces any previously registered functor instance.

The parameter onOpenCallback is an RWTFunctor<void()> handle reference that identifies the functor to be invoked when the buffer is changed from the closed to the open state.