CBufferQueue -- Templated class for safe inter-thread messaging.


    #include <CBufferQueue.h>
    template<class T>

        class CBufferQueue : public CGaurdedObject        
  CBufferQueue(size_t wakeLevel=0)
          throws ;
  void queue(T object);
          T get()
          throws ;
          bool getnow(T& object)
          throws ;
          std::list<T> getall()
          throws ;
          void setWakeThreshold(size_t level)
          throws ;
          void wait()
          throws ;
          void wake()
          throws ;


CBufferQueue is a templated class that provides a thread safe queue. Thread-safeness allows any number of threads to be producers and any number of threads to be consumers.

Thread-safeness is accomplished by deriving this class from the CGuardedObject and sprinkling an appropriate set of Enter and Leave calls. Blocking and waking is accomplished by means of a condition variable.


CBufferQueue(size_t wakeLevel=0) throws ;

Constructs the buffer queue. The wakeLevel parameter determines the depth of the queue above which threads waiting on a get will be woken. A wakeLevel of 0, the default, will wake for every queue insertion. The default is normally correct unless you have some specialized application.

void queue(T object);

Adds an object to the queue. The type T is the templated type of the class. For example if the CBufferQueue was declared as CBufferQueue<int> q the object must be an int.

T get() throws ;

Returns the least recently queued item. If the queue is emtpy the thread will block until there are more than the queue's wakelevel items in the queue (see the constructor documentation) at which time the oldest element will be returned.

bool getnow(T& object) throws ;

Attempts to get the oldest element from the queue. If there are elements in the queue, the function returns true and the object parameter is set to contain that element. If there are no elements in the queue, the function returns false and the value of object is not defined.

std::list<T> getall() throws ;

Returns a list that contains all of the elements that are now in the queue. This method never blocks. If the queue is empty, the returned value will be an empty list.

void setWakeThreshold(size_t level) throws ;

Changes the queeu wake level. For a discussion of the meaning of the queue wake level see the description of the constructor above.

void wait() throws ;

Waits for the next wake-up on the queue. While this is a public interface, normal applications don't need to explicitly call this entry as the get method automatically calls it.

void wake() throws ;

Wakes queue waiters. The only reason for a normal application to invoke this is if the wake level is relatively large and the application knows that there will not be any elements queued for some long time (e.g. when the application is almost finished), then wake can force queue waiters to wake up and process the elements that are present in the queue.