Task.hpp

Go to the documentation of this file.

// ======================================================================
// \title Os/Task.hpp
// \brief common function definitions for Os::Task
// ======================================================================
#ifndef Os_Task_hpp_
#define Os_Task_hpp_
 
#include <FpConfig.hpp>
#include <Fw/Time/TimeInterval.hpp>
#include <Fw/Types/Serializable.hpp>
#include <Os/Os.hpp>
#include <Os/TaskString.hpp>
#include <Os/Mutex.hpp>
 
#include <Fw/Deprecate.hpp>
#include <limits>
 
namespace Os {
 
    // Forward declarations
    class TaskRegistry;
 
    class TaskHandle {};
 
    class TaskInterface {
        public:
        static constexpr FwSizeType TASK_DEFAULT = std::numeric_limits<FwSizeType>::max();
            enum Status {
                OP_OK, 
                INVALID_HANDLE, 
                INVALID_PARAMS, 
                INVALID_STACK, 
                UNKNOWN_ERROR, 
                INVALID_AFFINITY, 
                DELAY_ERROR, 
                JOIN_ERROR, 
                ERROR_RESOURCES, 
                ERROR_PERMISSION, 
                INVALID_STATE, 
            };
 
            enum SuspensionType {
                INTENTIONAL,
                UNINTENTIONAL
            };
 
            enum State {
                NOT_STARTED,
                STARTING,
                RUNNING,
                SUSPENDED_INTENTIONALLY,
                SUSPENDED_UNINTENTIONALLY,
                EXITED,
                UNKNOWN
            };
 
            typedef void (*taskRoutine)(void* ptr);
 
            class Arguments {
              public:
                Arguments(const Fw::StringBase& name, const taskRoutine routine,
                          void* const routine_argument = nullptr,
                          const FwSizeType priority = TASK_DEFAULT,
                          const FwSizeType stackSize = TASK_DEFAULT,
                          const FwSizeType cpuAffinity = TASK_DEFAULT,
                          const PlatformUIntType identifier = static_cast<PlatformUIntType>(TASK_DEFAULT));
 
              public:
                const Os::TaskString m_name;
                taskRoutine m_routine;
                void* m_routine_argument;
                FwSizeType m_priority;
                FwSizeType m_stackSize;
                FwSizeType m_cpuAffinity;
                PlatformUIntType m_identifier;
            };
 
            TaskInterface() = default;
 
            virtual ~TaskInterface() = default;
 
            TaskInterface(const TaskInterface& other) = delete;
 
            TaskInterface& operator=(const TaskInterface& other) = delete;
 
            // =================
            // Implementation functions (static) to be supplied by the linker
            // =================
 
            static TaskInterface* getDelegate(TaskHandleStorage& aligned_placement_new_memory);
 
            // =================
            // Implementation functions (instance) to be supplied by the Os::TaskInterface children
            // =================
 
            virtual void onStart() = 0;
 
            virtual Status join() = 0;
 
            virtual void suspend(SuspensionType suspensionType) = 0;
 
            virtual void resume() = 0;
 
            virtual Status _delay(Fw::TimeInterval interval) = 0;
 
            virtual bool isCooperative();
 
            virtual TaskHandle* getHandle() = 0;
 
            virtual Status start(const Arguments& arguments) = 0;
    };
 
    class Task final : public TaskInterface {
      public:
        class TaskRoutineWrapper {
          public:
            explicit TaskRoutineWrapper(Task& self);
 
            static void run(void* task_pointer);
 
            void invoke();
 
            Task& m_task; 
            taskRoutine m_user_function = nullptr; 
            void* m_user_argument = nullptr; 
        };
 
        typedef FwSizeType ParamType;
 
        Task();
 
        ~Task() final;
 
        Task(const Task& other) = delete;
 
        Task& operator=(const Task& other) = delete;
 
        void suspend();
 
        State getState();
 
        DEPRECATED(Status start(const Fw::StringBase &name, const taskRoutine routine, void* const arg = nullptr,
                                const ParamType priority = TASK_DEFAULT,
                                const ParamType stackSize = TASK_DEFAULT,
                                const ParamType cpuAffinity = TASK_DEFAULT,
                                const ParamType identifier = TASK_DEFAULT), "Switch to Task::start(Arguments&)");
 
        //
        Status start(const Arguments& arguments) override;
 
        void onStart() override;
 
        //~
        void invokeRoutine();
 
        DEPRECATED(Status join(void** value_ptr), "Please switch to argument free join.");
 
        Status join() override; 
 
        void suspend(SuspensionType suspensionType) override;
 
        void resume() override;
 
        Status _delay(Fw::TimeInterval interval) override;
 
        bool isCooperative() override;
 
        FwSizeType getPriority();
 
        TaskHandle* getHandle() override;
 
        static void init();
 
        static FwSizeType getNumTasks();
 
        static void registerTaskRegistry(TaskRegistry* registry);
 
        static Task& getSingleton();
 
        static Status delay(Fw::TimeInterval interval);
 
      PRIVATE:
        static TaskRegistry* s_taskRegistry; 
        static FwSizeType s_numTasks; 
        static Mutex s_taskMutex; 
 
        TaskString m_name; 
        TaskInterface::State m_state = Task::NOT_STARTED;
        Mutex m_lock; 
        TaskRoutineWrapper m_wrapper; 
        FwSizeType m_priority = 0; // Storage of priority
 
        bool m_registered = false; 
 
        // This section is used to store the implementation-defined file handle. To Os::File and fprime, this type is
        // opaque and thus normal allocation cannot be done. Instead, we allow the implementor to store then handle in
        // the byte-array here and set `handle` to that address for storage.
        //
        alignas(FW_HANDLE_ALIGNMENT) TaskHandleStorage m_handle_storage; 
        TaskInterface& m_delegate; 
    };
 
    class TaskRegistry {
        public:
            TaskRegistry() = default;
            virtual ~TaskRegistry() = default;
            virtual void addTask(Task* task) = 0; 
 
            virtual void removeTask(Task* task) = 0;
    };
}
 
#endif