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/Mutex.hpp>
#include <Os/Os.hpp>
#include <Os/TaskString.hpp>

#include <Fw/Deprecate.hpp>
#include <limits>

// Forward declare for UTs
namespace Os {
namespace Test {
namespace Task {
struct Tester;
}
}  // namespace Test
}  // namespace Os

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 FwTaskIdType identifier = static_cast<FwTaskIdType>(TASK_DEFAULT));

      public:
        const Os::TaskString m_name;
        taskRoutine m_routine;
        void* m_routine_argument;
        FwTaskPriorityType m_priority;
        FwSizeType m_stackSize;
        FwSizeType m_cpuAffinity;
        FwTaskIdType 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 {
    friend struct Os::Test::Task::Tester;

  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;
};
}  // namespace Os

#endif