sharedqt.cpp

This program demonstrates using a thread safe C++ class called SharedQT<T>. This example act

// sharedQT.cc - SharedQT<T> class method templates
 
 // Copyright 1998-2010 Wind River Systems, Inc.
 
 //
 // modification history
 // --------------------
 // 02a,30mar98,pai  added Wind River coding conventions
 // 01a,24mar98,pai  written
 //
 
 //
 // DESCRIPTION
 // This class provides the following public methods:
 //
 //            -sharedEnQ
 //            -sharedDeQ
 //            -sharedEmptyQ
 //            -sharedFullQ
 //            -sharedCountQ
 //
 // This is a very basic shared queue template.  The type stored in the queue
 // and the maximum number of elements to be stored in the queue are specified
 // when the object is constructed.  For example:
 //
 //     SharedQT<int> myQ (10);
 //
 // will construct a queue which can hold up to 10 integers.  If a queue size
 // is not specified during construction, the queue will use a default size of
 // 50 items.
 //
 // This class is essentially a very thin wrapper around the QueueT<T> class.
 // As the class name implies, the intent behind the sharedQT<T> class is to
 // provide a thread safe container.  QueueT<T> does not provide a mutual
 // exclusion mechanism.  SharedQT<T> attempts to make QueueT<T> thread safe
 // by guarding calls to QueueT<T> methods with a mutex semaphore.
 //
 // It is assumed that multiple tasks will be trying to read from and write to
 // a SharedQT<T> object.  A single mutex semaphore insures that when one task
 // is in the middle of some queue operation, another task will not preempt the
 // operation at an inappropriate moment.
 //
 // SharedQT<T>::SharedQT initializes the object's mutex semaphore using
 // SEM_Q_PRIORITY and SEM_DELETE_SAFE options.  Pended task will be put on the
 // ready queue on the basis of priority, and a task which owns the semaphore
 // will be safe from unexpected deletion.  The SEM_DELETE_SAFE enables an
 // implicit taskSafe() for each semTask(), and an implicit taskUnsafe() for
 // each semGive().
 //
 // INCLUDE FILES:  sharedQT.h
 //
 
 
 
 ////////////////////////////////////////////////////////////////////////////////
 //
 // SharedQT<T>::SharedQT - construct a SharedQT<T> object
 //
 // There is but one constructor in this class.  After the base class
 // constructor is called, this constructor will initialize the mutex semaphore.
 //
 // If an argument, qs, is supplied to this constructor, the queue will be
 // constructed to hold up to 'qs' number of elements.  If no argument is
 // supplied to the constructor, the queue will, by default, allow up to 50
 // items to be stored in the queue.
 //
 // RETURNS:  N/A
 //
 
 template <class Item>
 SharedQT<Item>::SharedQT (int qs) : QueueT<Item> (qs)
     { 
     sharedQMutx = semMCreate (SEM_Q_PRIORITY | SEM_DELETE_SAFE); 
     }
 
 
 ////////////////////////////////////////////////////////////////////////////////
 //
 // SharedQT<T>::~SharedQT - destroy a shared queue object
 //
 // This destructor deletes the mutex semaphore.  The base class destructor
 // will delete all of the memory allocated for queue items.
 //
 // RETURNS:  N/A
 //
 
 template <class Item>
 SharedQT<Item>::~SharedQT ()
     {
     // It is a good idea to own a semaphore you intend to delete
 
     semTake (sharedQMutx, WAIT_FOREVER);
     
     // QueueT<T>::~QueueT is virtual; it will take care of
     // deleting memory allocated to hold items in the queue.
 
     semDelete (sharedQMutx);
     }
 
 
 ////////////////////////////////////////////////////////////////////////////////
 //
 // SharedQT<T>::sharedEnQ - add an item to a shared queue
 //
 // This method will attempt to take an internal semaphore before adding
 // an item to the queue.  The argument passed to this method should be
 // a reference to the type specified when the shared queue was constructed.
 //
 // RETURNS:  True, if the item was added to the queue.  False is returned
 //           to indicate that the item could not be added to the queue.
 //
 
 template <class Item>
 Bool SharedQT<Item>::sharedEnQ (const Item & item)
     {
     Bool status;
 
     //// GUARD ////
     semTake (sharedQMutx, WAIT_FOREVER);
     ///////////////
     
     status = enQueue (item);
 
     semGive (sharedQMutx);
     return status;
     }
 
 
 ////////////////////////////////////////////////////////////////////////////////
 //
 // SharedQT<T>::sharedDeQ - remove an item from a shared queue
 //
 // This method will remove an item from a shared queue and delete the memory
 // allocated to store the item.  The dequeued item is placed in the argument
 // for this method.  The method will not attempt to remove an item until it
 // has taken an internal semaphore.
 //
 // RETURNS:  True, if the item was dequeued.  False is returned to indicate
 //           that an item could not be dequeued.
 // 
 
 template <class Item>
 Bool SharedQT<Item>::sharedDeQ (Item & item)
     {
     Bool status;
 
     //// GUARD ////
     semTake (sharedQMutx, WAIT_FOREVER);
     ///////////////
     
     status = deQueue (item);
 
     semGive (sharedQMutx);
     return status;
     }
 
 
 ////////////////////////////////////////////////////////////////////////////////
 //
 // SharedQT<T>::sharedEmptyQ - test for an empty shared queue
 //
 // This method tests a shared queue for an empty state.
 //
 // RETURNS:  True, if the shared queue is empty.  False is returned to
 //           indicate that the queue is not empty.
 //
 
 template <class Item>
 Bool SharedQT<Item>::sharedEmptyQ () const
     {
     Bool status;
 
     //// GUARD ////
     semTake (sharedQMutx, WAIT_FOREVER);
     ///////////////
 
     status = emptyQueue ();
 
     semGive (sharedQMutx);
     return status;
     }
 
 
 ////////////////////////////////////////////////////////////////////////////////
 //
 // SharedQT<T>::sharedFullQ - test for a full shared queue
 //
 // This method tests for a full queue. 
 //
 // RETURNS:  True, if the queue is full.  False is returned to indicate that
 //           the queue is not full.
 //
 
 template <class Item>
 Bool SharedQT<Item>::sharedFullQ () const
     {
     Bool status;
 
     //// GUARD ////
     semTake (sharedQMutx, WAIT_FOREVER);
     ///////////////
 
     status = fullQueue ();
 
     semGive (sharedQMutx);
     return status;
     }
 
 
 ////////////////////////////////////////////////////////////////////////////////
 //
 // SharedQT<T>::sharedCountQ - return the number of items in a shared queue
 //
 // This method will return the number of items currently stored in a queue.
 //
 // RETURNS:  The number of elements in the queue.
 //
 
 template <class Item>
 int SharedQT<Item>::sharedCountQ () const
     {
     int sharedCount;
 
 
     //// GUARD ////
     semTake (sharedQMutx, WAIT_FOREVER);
     ///////////////
 
     sharedCount = countQueue ();
     
     semGive (sharedQMutx);
     return sharedCount;
     }