RWPCBufferBase
Module: Threads Package: Interthread Communication
RWPCBufferBaseRWTMonitor<RWMutexLock>
Local Index
Members
Header File
#include <rw/itc/RWPCBufferBase.h>
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 some user-specified maximum capacity.
The maximum capacity of a buffer may be limited by using 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. Any attempt to close a buffer that is already closed, or to open a buffer that is already open, is 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.
Public Destructor
virtual ~RWPCBufferBase();
Virtual destructor.
Public Member Functions
bool canRead() const;
true indicates that the calling thread may read a value from the buffer without blocking, provided no other threads manage to 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 manages to write a readable value into the buffer before the caller's attempt to read.
Indicates whether or not the buffer contains any entries that may be read. This function returns a bool value that indicates whether or not a value may be read from the buffer:
bool canWrite() const;
true indicates that the calling thread may write a value to the buffer without blocking, provided no other threads manage to 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 manages to remove one or more readable values from the buffer, or increase the maximum capacity of the buffer before the caller's attempt to write.
Indicates whether or not the buffer is open and has enough room in which to write another entry. This function returns a bool value that indicates whether or not a value may be written to the buffer:
void close();
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 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.
size_t entries() const;
Returns a size_t value representing the number of entries currently contained in the buffer.
void flush();
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.
size_t getCapacity() 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.
RWFunctor0 getCloseCallback() const;
Returns the current on-close callback functor instance, if any. This is an RWFunctor0 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.
RWFunctor0 getEmptyCallback() const;
Returns the current on-empty callback functor instance, if any. This is an RWFunctor0 handle instance that identifies the functor that is invoked when the buffer enters the empty state.
RWFunctor0 getFullCallback() const;
Returns the current on-full callback functor instance, if any. This is an RWFunctor0 handle instance that identifies the functor to be invoked when the buffer enters the full state.
RWFunctor0 getOpenCallback() const;
Returns the current on-open callback functor instance, if any. This is an RWFunctor0 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.
bool isOpen() const;
true indicates that the buffer is open.
false indicates that the buffer is closed.
Indicates whether the buffer is currently open for reading and writing. Returns a bool value where:
void open();
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.
size_t 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.
void setCloseCallback(const RWFunctor0& 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 RWFunctor0 handle reference that identifies the functor to be invoked when the buffer is changed from the opened to the closed state.
void setEmptyCallback(const RWFunctor0& 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 RWFunctor0 handle reference that identifies the functor to be invoked when the buffer enters the empty state.
void setFullCallback(const RWFunctor0& 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 RWFunctor0 handle reference that identifies the functor to be invoked when the buffer enters the full state.
void setOpenCallback(const RWFunctor0& 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 RWFunctor0 handle reference that identifies the functor to be invoked when the buffer is changed from the closed to the open state.
See Also
RWTPCPtrQueue<Type>, RWTPCPtrStack<Type>, RWTPCValQueue<Type>, RWTPCValStack<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.