taskqueue.h

Go to the documentation of this file.

 
/*    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
 *    IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 *    THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 
 *    PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIB-
 *    UTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
 *    OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 
 *    SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 *    INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 
 *    CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
 *    ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
 *    THE POSSIBILITY OF SUCH DAMAGE. */
 
// This define prevents this .h file from being included more than once
#ifndef _TASKQUEUE_H_
#define _TASKQUEUE_H_
 
#include <Arduino.h>
#include "FreeRTOS.h"                       // Main header for FreeRTOS
#include "baseshare.h"
 
 
template <class dataType> class Queue : public BaseShare
{
// This protected data can only be accessed from this class or its 
// descendents
protected:
    QueueHandle_t handle;             
    TickType_t ticks_to_wait;         
    uint16_t buf_size;                
    uint16_t max_full;                
 
// Public methods can be called from anywhere in the program where there is
// a pointer or reference to an object of this class
public:
    // The constructor creates a FreeRTOS queue
    Queue (BaseType_t queue_size, const char* p_name = NULL, 
            TickType_t = portMAX_DELAY);
 
    // Put an item into the queue behind other items.
    bool put (const dataType item);
 
    // This method puts an item of data into the back of the queue from 
    // within an interrupt service routine. It must not be used within 
    // non-ISR code. 
    bool ISR_put (const dataType item);
 
    bool butt_in (const dataType item)
    {
        return ((bool)(xQueueSendToFront (handle, &item, ticks_to_wait)));
    }
 
    // This method puts an item into the front of the queue from within 
    // an ISR. It must not be used within normal, non-ISR code. 
    bool ISR_butt_in (const dataType item);
 
    bool is_empty (void)
    {
        return (uxQueueMessagesWaiting (handle) == 0);
    }
 
    bool ISR_is_empty (void)
    {
        return (uxQueueMessagesWaitingFromISR (handle) == 0);
    }
 
    void get (dataType& recv_item)
    {
        // If xQueueReceive doesn't return pdTrue, nothing was found in the
        // queue, so no changes are made to the item
        xQueueReceive (handle, &recv_item, ticks_to_wait);
    }
 
    dataType get (void)
    {
        dataType return_this;
        xQueueReceive (handle, &return_this, ticks_to_wait);
        return return_this;
    }
 
    void ISR_get (dataType& recv_item)
    {
        portBASE_TYPE task_awakened;         // Checks if context switch needed
 
        // If xQueueReceive doesn't return pdTrue, nothing was found in the
        // queue, so we won't change the data referenced in the parameter
        xQueueReceiveFromISR (handle, &recv_item, &task_awakened);
    }
 
    dataType ISR_get (void)
    {
        portBASE_TYPE task_awakened;         // Checks if context switch needed
 
        dataType return_this;
        xQueueReceiveFromISR (handle, &return_this, &task_awakened);
        return return_this;
    }
 
    void peek (dataType& recv_item)
    {
        // If xQueueReceive doesn't return pdTrue, nothing was found in the
        // queue, so don't change the item
        xQueuePeek (handle, &recv_item, ticks_to_wait);
    }
 
    dataType peek (void)
    {
        dataType recv_item;
        xQueuePeek (handle, &recv_item, ticks_to_wait);
        return recv_item;
    }
 
    void ISR_peek (dataType& recv_item)
    {
        portBASE_TYPE task_awakened;           // Checks if a task will wake up
 
        // If xQueueReceive doesn't return pdTrue, nothing was found in the 
        // queue, so the value of recv_item is not changed
        xQueuePeekFromISR (handle, &recv_item, &task_awakened);
    }
 
    dataType ISR_peek (void)
    {
        portBASE_TYPE task_awakened;           // Checks if a task will wake up
        dataType recv_item;
        xQueuePeekFromISR (handle, &recv_item, &task_awakened);
        return recv_item;
    }
 
    bool any (void)
    {
        return (uxQueueMessagesWaiting (handle) != 0);
    }
 
    void operator << (dataType new_data)
    {
        if (CHECK_IF_IN_ISR ())
        {
            ISR_put (new_data);
        }
        else
        {
            put (new_data);
        }
    }
 
    void operator >> (dataType& put_here)
    {
        if (CHECK_IF_IN_ISR ())
        {
            portBASE_TYPE task_awakened;     // Checks if context switch needed
 
             // Copy the data from the queue into the receiving variable
            xQueueReceiveFromISR (handle, &put_here, &task_awakened);
        }
        else
        {
            xQueueReceive (handle, &put_here, ticks_to_wait);
        }
    }
 
    bool ISR_any (void)
    {
        return (uxQueueMessagesWaitingFromISR (handle) != 0);
    }
 
    unsigned portBASE_TYPE available (void)
    {
        return (uxQueueMessagesWaiting (handle));
    }
 
    unsigned portBASE_TYPE ISR_available (void)
    {
        return (uxQueueMessagesWaitingFromISR (handle));
    }
 
    void print_in_list (Print& print_dev);
 
    bool usable (void)
    {
        return (bool)handle;
    }
 
    QueueHandle_t get_handle (void)
    {
        return handle;
    }
}; // class Queue 
 
 
template <class dataType>
Queue<dataType>::Queue (BaseType_t queue_size, const char* p_name, 
                        TickType_t wait_time)
    : BaseShare (p_name)
{
    // Create a FreeRTOS queue object with space for the data items
    handle = xQueueCreate (queue_size, sizeof (dataType));
 
    // Store the wait time; it will be used when writing to the queue
    ticks_to_wait = wait_time;
 
    // Save the buffer size
    buf_size = queue_size;
 
    // We haven't stored any items in the queue yet
    max_full = 0;
}
 
 
template <class dataType>
inline bool Queue<dataType>::put (const dataType item)
{
    bool return_value = (bool)(xQueueSendToBack (handle, &item, 
                                                 ticks_to_wait));
 
    // Keep track of the maximum fillage of the queue
    uint16_t fillage = uxQueueMessagesWaiting (handle);
    if (fillage > max_full)
    {
        max_full = fillage;
    }
 
    return (return_value);
}
 
 
template <class dataType>
inline bool Queue<dataType>::ISR_put (const dataType item)
{
    // This value is set true if a context switch should occur due to this data
    signed portBASE_TYPE shouldSwitch = pdFALSE;
 
    bool return_value;                      // Value returned from this method
 
    // Call the FreeRTOS function and save its return value
    return_value = (bool)(xQueueSendToBackFromISR (handle, &item, 
                                                   &shouldSwitch));
 
    // Keep track of the maximum fillage of the queue. BUG: max_full isn't
    // thread safe (but getting max_full corrupted shouldn't cause a calamity)
    uint16_t fillage = uxQueueMessagesWaitingFromISR (handle);
    if (fillage > max_full)
    {
        max_full = fillage;
    }
 
    // Return the return value saved from the call to xQueueSendToBackFromISR()
    return (return_value);
}
 
 
template <class dataType>
inline bool Queue<dataType>::ISR_butt_in (const dataType item)
{
    // This value is set true if a context switch should occur due to this data
    signed portBASE_TYPE shouldSwitch = pdFALSE;
 
    bool return_value;                        // Value returned from this method
 
    // Call the FreeRTOS function and save its return value
    return_value = (bool)(xQueueSendToFrontFromISR (handle, &item, 
                                                    &shouldSwitch));
 
    // Return the return value saved from the call to xQueueSendToBackFromISR()
    return (return_value);
}
 
 
template <class dataType>
void Queue<dataType>::print_in_list (Print& print_dev)
{
    // Print this task's name and pad it to 16 characters
    print_dev.printf ("%-16squeue\t", name);
 
    // Print the free and total number of spaces in the queue or an error
    // message if this queue can't be used (probably due to a memory error)
    if (usable ())
    {
        print_dev << max_full << '/' << buf_size << endl;
    }
    else
    {
        print_dev << "UNUSABLE" << endl;
    }
 
    // Call the next item
    if (p_next != NULL)
    {
        p_next->print_in_list (print_dev);
    }
}
 
#endif  // _TASKQUEUE_H_