SourcePro® API Reference Guide

 
Loading...
Searching...
No Matches
RWTPCValBufferBaseGuardedPrioritized< Type, GuardAndPriorityDecorator > Class Template Reference

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

#include <rw/itc/RWTPCValBufferBaseGuardedPrioritized.h>

Inheritance diagram for RWTPCValBufferBaseGuardedPrioritized< Type, GuardAndPriorityDecorator >:
RWTPCValBufferBaseGuarded< Type, GuardAndPriorityDecorator > RWTPCValBufferBasePrioritized< Type, GuardAndPriorityDecorator > RWTPCValBufferBaseDecorated< Type, GuardAndPriorityDecorator > RWTPCValBufferBaseDecorated< Type, GuardAndPriorityDecorator > RWTPCValBufferBase< GuardAndPriorityDecorator > RWTPCValBufferBase< GuardAndPriorityDecorator > RWPCBufferBase RWPCBufferBase RWTMonitor< RWMutexLock > RWTMonitor< RWMutexLock >

Public Member Functions

virtual ~RWTPCValBufferBaseGuardedPrioritized (void)
 
bool tryWrite (const Type &value)
 
bool tryWrite (const Type &value, const RWTFunctor< bool()> &guard)
 
bool tryWrite (long priority, const Type &value)
 
bool tryWrite (long priority, const Type &value, const RWTFunctor< bool()> &guard)
 
void write (const Type &value)
 
void write (const Type &value, const RWTFunctor< bool()> &guard)
 
RWWaitStatus write (const Type &value, const RWTFunctor< bool()> &guard, unsigned long milliseconds)
 
RWWaitStatus write (const Type &value, unsigned long milliseconds)
 
void write (long priority, const Type &value)
 
void write (long priority, const Type &value, const RWTFunctor< bool()> &guard)
 
RWWaitStatus write (long priority, const Type &value, const RWTFunctor< bool()> &guard, unsigned long milliseconds)
 
RWWaitStatus write (long priority, const Type &value, unsigned long milliseconds)
 
- Public Member Functions inherited from RWTPCValBufferBaseGuarded< Type, GuardAndPriorityDecorator >
virtual ~RWTPCValBufferBaseGuarded (void)
 
RWWaitStatus peek (Type &result, unsigned long milliseconds)
 
Type peek (void)
 
RWWaitStatus read (Type &result, unsigned long milliseconds)
 
Type read (void)
 
bool tryPeek (Type &value)
 
bool tryRead (Type &value)
 
bool tryWrite (const Type &value, const RWTFunctor< bool()> &guard)
 
void write (const Type &value, const RWTFunctor< bool()> &guard)
 
RWWaitStatus write (const Type &value, const RWTFunctor< bool()> &guard, unsigned long milliseconds)
 
- Public Member Functions inherited from RWTPCValBufferBaseDecorated< Type, GuardAndPriorityDecorator >
virtual ~RWTPCValBufferBaseDecorated (void)
 
RWWaitStatus peek (Type &result, unsigned long milliseconds)
 
Type peek (void)
 
RWWaitStatus read (Type &result, unsigned long milliseconds)
 
Type read (void)
 
bool tryPeek (Type &result)
 
bool tryRead (Type &result)
 
bool tryWrite (const Type &value)
 
void write (const Type &value)
 
RWWaitStatus write (const Type &value, unsigned long milliseconds)
 
- Public Member Functions inherited from RWTPCValBufferBasePrioritized< Type, GuardAndPriorityDecorator >
virtual ~RWTPCValBufferBasePrioritized (void)
 
bool tryWrite (long priority, const Type &value)
 
void write (long priority, const Type &value)
 
RWWaitStatus write (long priority, const Type &value, unsigned long milliseconds)
 

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 RWTPCValBufferBase< GuardAndPriorityDecorator >
virtual ~RWTPCValBufferBase (void)
 
RWWaitStatus peek (GuardAndPriorityDecorator &result, unsigned long milliseconds)
 
GuardAndPriorityDecorator peek (void)
 
RWWaitStatus read (GuardAndPriorityDecorator &result, unsigned long milliseconds)
 
GuardAndPriorityDecorator read (void)
 
bool tryPeek (GuardAndPriorityDecorator &result)
 
bool tryRead (GuardAndPriorityDecorator &result)
 
bool tryWrite (const GuardAndPriorityDecorator &value)
 
void write (const GuardAndPriorityDecorator &value)
 
RWWaitStatus write (const GuardAndPriorityDecorator &value, unsigned long milliseconds)
 
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)
 
- 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
 
RWMutexLockmutex (void)
 
RWTMonitor< RWMutexLock > & operator= (const RWTMonitor< RWMutexLock > &)
 
void release (void)
 
bool tryAcquire (void)
 

Detailed Description

template<class Type, class GuardAndPriorityDecorator>
class RWTPCValBufferBaseGuardedPrioritized< Type, GuardAndPriorityDecorator >

RWTPCValBufferBaseGuardedPrioritized is the base class for the family of classes that provides buffered producer-consumer synchronization semantics for exchanging guarded and 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. These additional data items, or decorations, include a guard functor instance and a priority value. The guard functor is used during read operations to determine whether the associated value is currently eligible for retrieval from the buffer. The priority value 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 GuardAndPriorityDecorator identifies the class that is used to encapsulate the data value, guard functor, and priority value as a single object for storage in the internal buffer. The decorator class used by subclasses to instantiate this class is intended for the Threads Module's internal use, and is not documented as part of the public interface.

Constructor & Destructor Documentation

◆ ~RWTPCValBufferBaseGuardedPrioritized()

template<class Type , class GuardAndPriorityDecorator >
virtual RWTPCValBufferBaseGuardedPrioritized< Type, GuardAndPriorityDecorator >::~RWTPCValBufferBaseGuardedPrioritized ( void )
virtual

Virtual destructor.

Member Function Documentation

◆ tryWrite() [1/4]

template<class Type , class GuardAndPriorityDecorator >
bool RWTPCValBufferBaseGuardedPrioritized< Type, GuardAndPriorityDecorator >::tryWrite ( const Type & value)
inline

This function provides the same capabilities and behavior as tryWrite(long,const Type&,const RWTFunctor<bool()>&) except that this function attaches an empty guard functor instance and a priority value of zero to each value.

◆ tryWrite() [2/4]

template<class Type , class GuardAndPriorityDecorator >
bool RWTPCValBufferBaseGuardedPrioritized< Type, GuardAndPriorityDecorator >::tryWrite ( const Type & value,
const RWTFunctor< bool()> & guard )
inline

This function provides the same capabilities and behavior as tryWrite(long,const Type&,const RWTFunctor<bool()>&) except that this function attaches a priority value of zero to each value.

◆ tryWrite() [3/4]

template<class Type , class GuardAndPriorityDecorator >
bool RWTPCValBufferBaseGuardedPrioritized< Type, GuardAndPriorityDecorator >::tryWrite ( long priority,
const Type & value )
inline

This function provides the same capabilities and behavior as tryWrite(long,const Type&,const RWTFunctor<bool()>&) except that this function attaches an empty guard functor instance a priority value of zero to each value.

◆ tryWrite() [4/4]

template<class Type , class GuardAndPriorityDecorator >
bool RWTPCValBufferBaseGuardedPrioritized< Type, GuardAndPriorityDecorator >::tryWrite ( long priority,
const Type & value,
const RWTFunctor< bool()> & guard )

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 an 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 three parameters:

  • The parameter priority is a long that is used to determine the insertion point of the value within the buffer. A value with a greater priority value is positioned to be read before a value of lower priority. Values of equal priority are positioned 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 guard is a reference to an RWTFunctor<bool()> functor instance that will be 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.

◆ write() [1/8]

template<class Type , class GuardAndPriorityDecorator >
void RWTPCValBufferBaseGuardedPrioritized< Type, GuardAndPriorityDecorator >::write ( const Type & value)
inline

This function provides the same capabilities and behavior as write(long,const Type&,const RWTFunctor<bool()>&) except that this function attaches an empty guard functor instance and a priority value of zero to each value.

◆ write() [2/8]

template<class Type , class GuardAndPriorityDecorator >
void RWTPCValBufferBaseGuardedPrioritized< Type, GuardAndPriorityDecorator >::write ( const Type & value,
const RWTFunctor< bool()> & guard )
inline

This function provides the same capabilities and behavior as write(long,const Type&,const RWTFunctor<bool()>&) except that this function attaches a priority value of zero to each value.

◆ write() [3/8]

template<class Type , class GuardAndPriorityDecorator >
RWWaitStatus RWTPCValBufferBaseGuardedPrioritized< Type, GuardAndPriorityDecorator >::write ( const Type & value,
const RWTFunctor< bool()> & guard,
unsigned long milliseconds )
inline

This function provides the same capabilities and behavior as write(long,const Type&,const RWTFunctor<bool()>&,unsigned long) except that this function attaches a priority value of zero to each value.

◆ write() [4/8]

template<class Type , class GuardAndPriorityDecorator >
RWWaitStatus RWTPCValBufferBaseGuardedPrioritized< Type, GuardAndPriorityDecorator >::write ( const Type & value,
unsigned long milliseconds )
inline

This function provides the same capabilities and behavior as write(long,const Type&,const RWTFunctor<bool()>&,unsigned long) except that this function attaches an empty guard functor instance and a priority value of zero to each value.

◆ write() [5/8]

template<class Type , class GuardAndPriorityDecorator >
void RWTPCValBufferBaseGuardedPrioritized< Type, GuardAndPriorityDecorator >::write ( long priority,
const Type & value )
inline

This function provides the same capabilities and behavior as write(long,const Type&,const RWTFunctor<bool()>&) except that this function attaches an empty guard functor instance to each value.

◆ write() [6/8]

template<class Type , class GuardAndPriorityDecorator >
void RWTPCValBufferBaseGuardedPrioritized< Type, GuardAndPriorityDecorator >::write ( long priority,
const Type & value,
const RWTFunctor< bool()> & guard )

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, the function immediately returns by throwing an RWTHRClosedException.

Calling this function on an 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.

This function takes three parameters.

  • The parameter priority is a long that is used to determine the insertion point of the value within the buffer. A value with a greater priority value is positioned to be read before a value of lower priority. Values of equal priority are positioned 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 guard is a reference to an RWTFunctor<bool()> functor instance that will be 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.

◆ write() [7/8]

template<class Type , class GuardAndPriorityDecorator >
RWWaitStatus RWTPCValBufferBaseGuardedPrioritized< Type, GuardAndPriorityDecorator >::write ( long priority,
const Type & value,
const RWTFunctor< bool()> & guard,
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 an 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, it cannot guarantee that the thread is actually scheduled for execution at the end of the timeout period. It cannot prevent the on-full callback functor from indirectly blocking the caller for an indefinite period of time.

This function takes four parameters:

  • The parameter priority is a long that is used to determine the insertion point of the value within the buffer. A value with a greater priority value is positioned to be read before a value of lower priority. Values of equal priority are positioned 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 guard is a reference to an RWTFunctor<bool()> functor instance that will be 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, since such access results in deadlock.
  • The parameter milliseconds is an unsigned long value that specifies the maximum number of milliseconds to wait for the operation to complete.

◆ write() [8/8]

template<class Type , class GuardAndPriorityDecorator >
RWWaitStatus RWTPCValBufferBaseGuardedPrioritized< Type, GuardAndPriorityDecorator >::write ( long priority,
const Type & value,
unsigned long milliseconds )
inline

This function provides the same capabilities and behavior as write(long,const Type&,const RWTFunctor<bool()>&,unsigned long) except that this function attaches an empty guard functor instance to each value.

Copyright © 2024 Rogue Wave Software, Inc., a Perforce company. All Rights Reserved.