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 <Fw/FPrimeBasicTypes.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();
        static constexpr FwTaskPriorityType TASK_PRIORITY_DEFAULT = std::numeric_limits<FwTaskPriorityType>::max();
            enum Status {
                OP_OK, 
                INVALID_HANDLE, 
                INVALID_PARAMS, 
                INVALID_STACK, 
                UNKNOWN_ERROR, 
                INVALID_AFFINITY, 
                DELAY_ERROR, 
                JOIN_ERROR, 
                ERROR_RESOURCES, 
                ERROR_PERMISSION, 
                NOT_SUPPORTED,     
                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 FwTaskPriorityType priority = TASK_PRIORITY_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;
                FwTaskPriorityType 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 FwTaskPriorityType priority = TASK_PRIORITY_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;

        FwTaskPriorityType 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; 
        FwTaskPriorityType 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