QueueCPP.h

/**
 * @file QueueCPP.h
 * @brief FreeRTOS Queue Wrapper
 *
 * This file contains a set of lightweight wrappers for queues using FreeRTOS
 * 
 * @copyright (c) 2007-2024 Richard Damon
 * @author Richard Damon <richard.damon@gmail.com>
 * @parblock
 * MIT License:
 * 
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 * 
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 *
 * It is requested (but not required by license) that any bugs found or 
 * improvements made be shared, preferably to the author.
 * @endparblock
 * 
 * @ingroup FreeRTOSCpp
 */
#ifndef QUEUECPP_H
#define QUEUECPP_H

#include "FreeRTOScpp.h"
#include "queue.h"

#if FREERTOSCPP_USE_NAMESPACE
namespace FreeRTOScpp {
#endif

//#include <type_traits>
/**
 * @brief Base Queue Wrapper
 *
 * This Base Class provides the Type Independent functionality for a Queue
 * @ingroup FreeRTOSCpp
 */

class QueueBase {
protected:
	/**
	 * @brief Constructor
	 *
	 * Effectively Abstract class so protected base.
	 * @param handle_ The queueHandle for the queue/
	 */
	QueueBase(QueueHandle_t handle_) : queueHandle(handle_) {};
public:
	  /**
	   * @brief Destructor.
	   */
	virtual ~QueueBase() {
	    vQueueDelete(queueHandle);
	  }

	  /**
	   * @brief Get number of items in the Queue.
	   * @return The number of item in the Queue.
	   */
	  unsigned waiting() const {
	    return uxQueueMessagesWaiting(queueHandle);
	  }

	  /**
	   * @brief Return number of spaces available in Queue
	   * @return the number of spaces available in the Queue.
	   */
	  unsigned available() const {
		  return uxQueueSpacesAvailable(queueHandle);
	  }

	  /**
	   * @brief Reset the Queue.
	   * Resets the Queue to an empty state.
	   */
	  void reset() {
		  xQueueReset(queueHandle);
	  }

	  /**
	   * @brief Check if Queue is Full.
	   * @return True if Queue is Full.
	   */
	  bool full() {
	    return 0 == uxQueueSpacesAvailable(queueHandle);
	  }

	  /**
	   * @brief Check if Queue is Empty
	   * @return True if Queue is Empty.
	   */
	  bool empty() {
	    return uxQueueMessagesWaiting(queueHandle) == 0;
	  }

	  /**
	   * @brief Is Queue Full.
	   * Note: Interrupt service routines should only call _ISR routines.
	   * @return True if Queue is Full.
	   */
	  bool full_ISR() {
	    return xQueueIsQueueFullFromISR(queueHandle);
	  }

	  /**
	   * @brief Is Queue Empty.
	   * Note: Interrupt service routines should only call _ISR routines.
	   * @return True if Queue is Empty.
	   */
	  bool empty_ISR() {
	    return xQueueIsQueueEmptyFromISR(queueHandle);
	  }

	  /**
	   * @brief Get number of message waiting.
	   * Note: Interrupt service routines should only call _ISR routines.
	   * @return The number of messages waiting.
	   */
	  unsigned waiting_ISR() {
	    return uxQueueMessagesWaitingFromISR(queueHandle);
	  }

protected:
	QueueHandle_t queueHandle;
private:

#if __cplusplus < 201101L
    QueueBase(QueueBase const&);      ///< We are not copyable.
    void operator =(QueueBase const&);  ///< We are not assignable.
#else
    QueueBase(QueueBase const&) = delete;      ///< We are not copyable.
    void operator =(QueueBase const&) = delete;  ///< We are not assignable.
#endif // __cplusplus

};

/**
 * @brief Typed Queue Wrapper
 *
 * This Base Class provides the Type Dependent functionality for a Queue
 * @ingroup FreeRTOSCpp
 */

template<class T> class QueueTypeBase : public QueueBase {
protected:
	QueueTypeBase(QueueHandle_t handle_) : QueueBase(handle_) {}

public:
	  /**
	   * @brief Push an item onto the Queue.
	   * Puts an item onto the Queue so it will be the next item to remove.
	   * @param item The item to put on the Queue.
	   * @param time How long to wait for room if Queue is full.
	   * @return True if successful
	   */
	bool push(T const& item, TickType_t time = portMAX_DELAY){
	    return xQueueSendToFront(queueHandle, &item, time);
	}
#if FREERTOSCPP_USE_CHRONO
    /**
     * @brief Push an item onto the Queue.
     * Puts an item onto the Queue so it will be the next item to remove.
     * @param item The item to put on the Queue.
     * @param time How long to wait for room if Queue is full.
     * @return True if successful
     */
  bool push(T const& item, Time_ms time){
      return xQueueSendToFront(queueHandle, &item, ms2ticks(time));
  }
#endif
	  /**
	   * @brief add an item at end of the Queue.
	   * Puts an item onto the Queue so it will be the last item to remove.
	   * @param item The item to put on the Queue.
	   * @param time How long to wait for room if Queue is full.
	   * @return True if successful
	   */
	  bool add(T const& item, TickType_t time = portMAX_DELAY){
	    return xQueueSendToBack(queueHandle, &item, time);
	  }
#if FREERTOSCPP_USE_CHRONO
      /**
       * @brief add an item at end of the Queue.
       * Puts an item onto the Queue so it will be the last item to remove.
       * @param item The item to put on the Queue.
       * @param time How long to wait for room if Queue is full.
       * @return True if successful
       */
      bool add(T const& item, Time_ms time){
        return xQueueSendToBack(queueHandle, &item, ms2ticks(time));
      }
#endif
	  /**
	   * @brief Get an item from the Queue.
	   * Gets the first item from the Queue
	   * @param var Variable to place the item
	   * @param time How long to wait for an item to be available.
	   * @return True if an item returned.
	   */
	  bool pop(T& var, TickType_t time = portMAX_DELAY) {
	    return xQueueReceive(queueHandle, &var, time);
	  }
#if FREERTOSCPP_USE_CHRONO
      /**
       * @brief Get an item from the Queue.
       * Gets the first item from the Queue
       * @param var Variable to place the item
       * @param time How long to wait for an item to be available.
       * @return True if an item returned.
       */
      bool pop(T& var, Time_ms time) {
        return xQueueReceive(queueHandle, &var, ms2ticks(time));
      }
#endif

	  /**
	   * @brief Look at the first item in the Queue.
	   * Gets the first item from the Queue leaving it there.
	   * @param var Variable to place the item
	   * @param time How long to wait for an item to be available.
	   * @return True if an item returned.
	   */
	  bool peek(T& var, TickType_t time = 0) {
	    return xQueuePeek(queueHandle, &var, time);
	  }
#if FREERTOSCPP_USE_CHRONO
      /**
       * @brief Look at the first item in the Queue.
       * Gets the first item from the Queue leaving it there.
       * @param var Variable to place the item
       * @param time How long to wait for an item to be available.
       * @return True if an item returned.
       */
      bool peek(T& var, Time_ms time) {
        return xQueuePeek(queueHandle, &var, ms2ticks(time));
      }
#endif

	  /**
	   * @brief Push an item onto the Queue.
	   * Puts an item onto the Queue so it will be the next item to remove.
	   *
	   * Note: Interrupt service routines should only call _ISR routines.
	   * @param item The item to put on the Queue.
	   * @param waswoken Flag variable to determine if context switch is needed.
	   * @return True if successful
	   */
	  bool push_ISR(T const& item, portBASE_TYPE& waswoken){
	    return xQueueSendToFrontFromISR(queueHandle, &item, &waswoken);
	  }

	  /**
	   * @brief add an item at end of the Queue.
	   * Puts an item onto the Queue so it will be the last item to remove.
	   *
	   * Note: Interrupt service routines should only call _ISR routines.
	   * @param item The item to put on the Queue.
	   * @param waswoken Flag variable to determine if context switch is needed.
	   * @return True if successful
	   */
	  bool add_ISR(T const& item, portBASE_TYPE& waswoken){
	    return xQueueSendToBackFromISR(queueHandle, &item, &waswoken);
	  }

	  /**
	   * @brief Get an item from the Queue.
	   * Gets the first item from the Queue
	   *
	   * Note: Interrupt service routines should only call _ISR routines.
	   * @param var Variable to place the item
	   * @param waswoken Flag variable to determine if context switch is needed.
	   * @return True if an item returned.
	   */
	  bool pop_ISR(T& var, portBASE_TYPE& waswoken) {
	    return xQueueReceiveFromISR(queueHandle, &var, &waswoken);
	  }

	  /**
	   * @brief Look at the first item in the Queue.
	   * Gets the first item from the Queue leaving it there.
	   *
	   * Note: Interrupt service routines should only call _ISR routines.
	   * @param var Variable to place the item
	   * @param waswoken Flag variable to determine if context switch is needed.
	   * @return True if an item returned.
	   */
	  bool peek_ISR(T& var, portBASE_TYPE& waswoken) {
	    return xQueuePeekFromISR(queueHandle, &var);
	  }
};

/**
 * @brief Queue Wrapper.
 *
 * Note, is a template on the type of object to place on the queue, 
 * which makes the Queue more typesafe.
 *
 * @tparam T The type of object to be placed on the queue.
 * Note also, this type needs to be trivially copyable, and preferably a POD 
 * as the FreeRTOS queue code will copy it with memcpy().
 * @tparam queuelength The number of elements to reserve space for in the queue.
 * If 0 (which is the default value) then length will be provided to the constructor dynamically.
 *
 * @todo add Overwrite operation
 * @todo add QueueSet Functionality
 * @ingroup FreeRTOSCpp
 */

template<class T, unsigned queueLength
#if( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
	= 0
#endif
	> class Queue : public QueueTypeBase<T> {
//	static_assert(::std::is_pod<T>, "Queues only work with PODs"); ///@todo need to get later version of C++ compile working
public:
	/**
	 * @brief Constructor.
	 * @param name The name to register the Queue with.
	 */
  Queue(char const* name = 0) :
	  QueueTypeBase<T>(

#if( configSUPPORT_STATIC_ALLOCATION == 1 )
	    xQueueCreateStatic(queueLength, sizeof(T), reinterpret_cast<uint8_t*>(&queueStore), &queueBuff)
#else
		xQueueCreate(queueLength, sizeof(T))
#endif
	   )
	{
#if configQUEUE_REGISTRY_SIZE > 0
    if(name)
      vQueueAddToRegistry(this->queueHandle, name);
#endif

  };
private:
#if( configSUPPORT_STATIC_ALLOCATION == 1 )
    StaticQueue_t queueBuff;
    T queueStore[queueLength];
#endif
};

#if( configSUPPORT_DYNAMIC_ALLOCATION == 1 )

template<class T> class Queue<T, 0> : public QueueTypeBase<T> {
//	static_assert(::std::is_pod<T>, "Queues only work with PODs"); ///@todo need to get later version of C++ compile working
public:
	/**
	 * @brief Constructor.
	 * @param length How many object to make room for in the Queue.
	 * @param name The name to register the Queue with.
	 */
    Queue(unsigned portBASE_TYPE length, char const* name = 0) :
    	QueueTypeBase<T>(xQueueCreate(length, sizeof(T)))
    {
#if configQUEUE_REGISTRY_SIZE > 0
        if(name)
            vQueueAddToRegistry(this->queueHandle, name);
#endif

    };

};
#endif

#if FREERTOSCPP_USE_NAMESPACE
}   // namespace FreeRTOScpp
#endif

#endif