// 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;    }