queue.h

00001 /* mbed Queue Library
00002  * Copyright (c) 2010 William Basser ( wbasser [at] gmail [dot] com )
00003  *
00004  * Permission is hereby granted, free of charge, to any person obtaining a copy
00005  * of this software and associated documentation files (the "Software"), to deal
00006  * in the Software without restriction, including without limitation the rights
00007  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
00008  * copies of the Software, and to permit persons to whom the Software is
00009  * furnished to do so, subject to the following conditions:
00010  *
00011  * The above copyright notice and this permission notice shall be included in
00012  * all copies or substantial portions of the Software.
00013  *
00014  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00015  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00016  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00017  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00018  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00019  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
00020  * THE SOFTWARE.
00021  */
00022 
00023 #ifndef MBED_QUEUE_H
00024 #define MBED_QUEUE_H
00025 
00026 #include "mbed.h"
00027 
00028 /** queue modle
00029  *
00030  * Example:
00031  * @code
00032  *
00033  * #include "mbed.h"
00034  *
00035  * // include the queue library
00036  * #include "queue.h"
00037  *
00038  * Serial myPc( USBTX, USBRX );
00039  * Queue myQueue( 1, 5 );
00040  *
00041  * int main() 
00042  * {
00043  *    unsigned char   nTemp;
00044  *   
00045  *    // display the number of items in the queue
00046  *    myPc.printf( "Items in queue: %d\r", myQueue.GetNumberOfItems( ));
00047  *    
00048  *    // add item to queue
00049  *    nTemp = 5;
00050  *    myQueue.Put( &nTemp );
00051  *    nTemp = 6;
00052  *    myQueue.Put( &nTemp );
00053  *    nTemp = 7;
00054  *    myQueue.Put( &nTemp );
00055  *    
00056  *    // display the number of items in the queue
00057  *    myPc.printf( "Items in queue: %d\r", myQueue.GetNumberOfItems( ));
00058  *    
00059  *    // peek at item at the top of the queue
00060  *    myQueue.Peek( &nTemp );
00061  *    myPc.printf( "Peek: %d\r", nTemp );
00062  *    
00063  *    // get an item from queue
00064  *    myQueue.Get( &nTemp );
00065  *    myPc.printf( "Item 0 = %d\r", nTemp );
00066  *    myQueue.Get( &nTemp );
00067  *    myPc.printf( "Item 1 = %d\r", nTemp );
00068  *    
00069  *    // queue should be empty
00070  *    if ( !myQueue.Get( &nTemp ))
00071  *    {
00072  *        // queue is empty
00073  *        myPc.printf( "Queue empty!\r" );
00074  *    }
00075  * }
00076  *
00077  * @endcode
00078  */
00079 
00080 class Queue {
00081 public:
00082     /** Create a Queue object
00083      *
00084      * @param iSize size of the object in queue
00085      * @param iCount number of items in the queue
00086      */
00087     Queue( int iSize, int iCount );
00088 
00089     /** destruction
00090      *
00091      */
00092     virtual ~Queue( void );
00093 
00094     /** Add item to queue
00095      *
00096      * @param pvItem item to add
00097      * @returns true if item added, false if queue full
00098      */
00099     bool Put( void* pvItem );
00100 
00101     /** get an item from the queue in an IRQ handler
00102      *
00103      * @param pvItem pointer to the tiem to retrieve
00104      * @returns true if item fetched, false if queue is empty
00105      */
00106     bool GetIrq( void* pvItem );
00107     
00108     /** Add item to queue from an IRQ handler
00109      *
00110      * @param pvItem item to add
00111      * @returns true if item added, false if queue full
00112      */
00113     bool PutIrq( void* pvItem );
00114 
00115     /** get an item from the queue
00116      *
00117      * @param pvItem pointer to the tiem to retrieve
00118      * @returns true if item fetched, false if queue is empty
00119      */
00120     bool Get( void* pvItem );
00121     
00122     /** get the number of items in the queue
00123      * 
00124      * @returns the number of items in the queue
00125      */
00126     int GetNumberOfItems( void );
00127     
00128     /** peek at the entry at the top of the queue
00129      * 
00130      * @returns the entry at the top of the queue
00131      */
00132     bool Peek( void* pvItem );    
00133 
00134     /** flush the queue
00135      *
00136      */
00137     void Flush( void );
00138 
00139 
00140 protected:
00141     int              m_iSize;        // size of each item in queue
00142     int              m_iCount;        // number of items in the queue
00143     unsigned char*   m_pnHead;        // pointer to the head of the queue
00144     unsigned char*   m_pnTail;        // pointer to the tail of the queue
00145     unsigned char*   m_pnRdIndex;    // read index
00146     unsigned char*   m_pnWrIndex;    // write index
00147     int              m_iLclCount;    // number of items in queue
00148 };
00149 #endif