TACOS/include/sta/tacos/thread.hpp

/*
 * task.hpp
 *
 *  Created on: Sep 14, 2023
 *      Author: Dario
 */

#ifndef INCLUDE_TACOS_TASK_HPP_
#define INCLUDE_TACOS_TASK_HPP_

#include <cmsis_os2.h>

#include <sta/rtos/thread.hpp>

/**
 * @defgroup tacos_thread TACOS Thread
 * @ingroup tacos
 * @brief TACOS Thread class.
 */

namespace sta
{
	namespace tacos
	{
		/**
		 * @brief A status flags for the watchdog.
		 * 
		 */
		enum class ThreadStatus
		{
			/**
			 * @brief This thread wants to be ignored by the watchdog.
			 * 
			 */
			IGNORED,

			/**
			 * @brief The thread terminated regularly. The watchdog will not try to restart this thread.
			 * 
			 */
			STOPPED,

			/**
			 * @brief The thread's status is unknown. If the watchdog encounters this status, it will try to
			 * restart the affected thread.
			 * 
			 */
			UNKNOWN,

			/**
			 * @brief The thread is running as intended. The watchdog will set this flag back to UNKNOWN.
			 * 
			 */
			RUNNING,

			/**
			 * @brief The thread is waiting and might not send a heartbeat signal in a while. The watchdog will
			 * not do anything in this case.
			 * 
			 */
			WAITING
		};

		/**
		 * @brief Abstract class for thread implementations in Tacos.
		 *
		 * @ingroup tacos_thread
		 */
		class TacosThread : public RtosThread
		{
		public:
			/**
			 * @brief Create a new thread with the given name and priority.
			 * 
			 * @param name The thread's name. This is used for debugging.
			 * @param prio The thread's priority. Generally, this should be lower than the manager and statemachine priority.
			 * @param stack_size The stack size for the task. The default is 0, i.e. the stack size specified in the FreeRTOS settings.
			 * @param cb_size The control block size for the task. The default is 0, i.e. the size specified in the FreeRTOS settings.
			 */
			TacosThread(const char* name, osPriority_t prio, uint32_t stack_size = 0, uint32_t cb_size = 0);

			virtual ~TacosThread();

			/**
			 * @brief Start the execution of this thread.
			 */
			void start();

			/**
			 * @brief Checks if this thread is currently running.
			 */
			bool isRunning();

			/**
			 * @brief Get the currently running instance.
			 * 
			 * @return The currently running instance id.
			 */
			osThreadId_t getInstance();

			/**
			 * @brief Get the name of this thread.
			 */
			const char* getName() const;

			/**
			 * @brief Compare two threads by their names.
			 */
			bool operator==(const TacosThread& other) const;

			/**
			 * @brief Compare two threads by their names.
			 */
			bool operator<(const TacosThread& other) const;

			/**
			 * @brief A function that wraps this task's functionality in a loop. This loop will run until
			 * termination is requested.
			 */
			void loop();

			/**
			 * @brief This function is executed first when this thread is started.
			 */
			virtual void init();

			/**
			 * @brief The body of the thread's loop. Has to be implemented by the user.
			 *	 	This function is called repeatedly until termination is requested.
			 */
			virtual void func() = 0;

			/**
			 * @brief This function is executed when the thread is terminated. Has to be implemented by the user.
			 * 		This function should free all ressources used by this thread.
			 */
			virtual void cleanup();

#ifdef STA_TACOS_WATCHDOG_ENABLED
		#define BLOCKING(stmt) waiting(); stmt heartbeat()

		protected:
			/**
			 * @brief 
			 * 
			 */
			void heartbeat();

			/**
			 * @brief Set the thread's status to waiting. Should be called before executing
			 * 
			 */
			void waiting();
		public:
			/**
			 * @brief Get the current status of the thread.
			 * 
			 * @return ThreadStatus 
			 */
			ThreadStatus getStatus();

			/**
			 * @brief Reset the thread's status to UNKNOWN. Should only be called by the Watchdog.
			 * 
			 */
			void resetStatus();
#endif // STA_TACOS_WATCHDOG_ENABLED

		private:
			/**
			 * @brief Static function to pass to RTOS to run as a thread. Calls the loop function implemented here.
			 */
			static void entry_point(void* arg);

		private:
			osThreadId_t instance_;
			osThreadAttr_t attribs_;
			bool running_;
#ifdef STA_TACOS_WATCHDOG_ENABLED
			ThreadStatus status_;
#endif // STA_TACOS_WATCHDOG_ENABLED
		};
	}
}


#endif /* INCLUDE_TACOS_TASK_HPP_ */