F´ Flight Software - C/C++ Documentation  devel
A framework for building embedded system applications to NASA flight quality standards.
Task.hpp
Go to the documentation of this file.
1 // ======================================================================
2 // \title Os/Task.hpp
3 // \brief common function definitions for Os::Task
4 // ======================================================================
5 #ifndef Os_Task_hpp_
6 #define Os_Task_hpp_
7 
8 #include <FpConfig.hpp>
11 #include <Os/Os.hpp>
12 #include <Os/TaskString.hpp>
13 #include <Os/Mutex.hpp>
14 
15 #include <Fw/Deprecate.hpp>
16 #include <limits>
17 
18 namespace Os {
19 
20  // Forward declarations
21  class TaskRegistry;
22 
24  class TaskHandle {};
25 
26  class TaskInterface {
27  public:
28  static constexpr FwSizeType TASK_DEFAULT = std::numeric_limits<FwSizeType>::max();
29  enum Status {
41  };
42 
46  };
47 
48  enum State {
55  UNKNOWN
56  };
57 
59  typedef void (*taskRoutine)(void* ptr);
60 
61  class Arguments {
62  public:
75  Arguments(const Fw::StringBase& name, const taskRoutine routine,
76  void* const routine_argument = nullptr,
77  const FwSizeType priority = TASK_DEFAULT,
78  const FwSizeType stackSize = TASK_DEFAULT,
79  const FwSizeType cpuAffinity = TASK_DEFAULT,
80  const PlatformUIntType identifier = static_cast<PlatformUIntType>(TASK_DEFAULT));
81 
82  public:
90  };
91 
93  TaskInterface() = default;
94 
96  virtual ~TaskInterface() = default;
97 
99  TaskInterface(const TaskInterface& other) = delete;
100 
102  TaskInterface& operator=(const TaskInterface& other) = delete;
103 
104  // =================
105  // Implementation functions (static) to be supplied by the linker
106  // =================
107 
127  static TaskInterface* getDelegate(TaskHandleStorage& aligned_placement_new_memory);
128 
129  // =================
130  // Implementation functions (instance) to be supplied by the Os::TaskInterface children
131  // =================
132 
134  virtual void onStart() = 0;
135 
142  virtual Status join() = 0;
143 
151  virtual void suspend(SuspensionType suspensionType) = 0;
152 
157  virtual void resume() = 0;
158 
166  virtual Status _delay(Fw::TimeInterval interval) = 0;
167 
178  virtual bool isCooperative();
179 
182  virtual TaskHandle* getHandle() = 0;
183 
190  virtual Status start(const Arguments& arguments) = 0;
191  };
192 
196  class Task final : public TaskInterface {
197  public:
200  public:
201  explicit TaskRoutineWrapper(Task& self);
202 
208  static void run(void* task_pointer);
209 
211  void invoke();
212 
215  void* m_user_argument = nullptr;
216  };
217 
220 
222  Task();
223 
225  ~Task() final;
226 
228  Task(const Task& other) = delete;
229 
231  Task& operator=(const Task& other) = delete;
232 
237  void suspend();
238 
245  State getState();
246 
261  DEPRECATED(Status start(const Fw::StringBase &name, const taskRoutine routine, void* const arg = nullptr,
262  const ParamType priority = TASK_DEFAULT,
263  const ParamType stackSize = TASK_DEFAULT,
264  const ParamType cpuAffinity = TASK_DEFAULT,
265  const ParamType identifier = TASK_DEFAULT), "Switch to Task::start(Arguments&)");
266 
272  //
277  Status start(const Arguments& arguments) override;
278 
280  void onStart() override;
281 
283  //~
286  void invokeRoutine();
287 
295  DEPRECATED(Status join(void** value_ptr), "Please switch to argument free join.");
296 
303  Status join() override;
304 
312  void suspend(SuspensionType suspensionType) override;
313 
318  void resume() override;
319 
327  Status _delay(Fw::TimeInterval interval) override;
328 
331  bool isCooperative() override;
332 
335 
338  TaskHandle* getHandle() override;
339 
341  static void init();
342 
345  static FwSizeType getNumTasks();
346 
349  static void registerTaskRegistry(TaskRegistry* registry);
350 
353  static Task& getSingleton();
354 
362  static Status delay(Fw::TimeInterval interval);
363 
364  PRIVATE:
365  static TaskRegistry* s_taskRegistry;
366  static FwSizeType s_numTasks;
367  static Mutex s_taskMutex;
368 
369  TaskString m_name;
370  TaskInterface::State m_state = Task::NOT_STARTED;
371  Mutex m_lock;
372  TaskRoutineWrapper m_wrapper;
373  FwSizeType m_priority = 0; // Storage of priority
374 
375  bool m_registered = false;
376 
377  // This section is used to store the implementation-defined file handle. To Os::File and fprime, this type is
378  // opaque and thus normal allocation cannot be done. Instead, we allow the implementor to store then handle in
379  // the byte-array here and set `handle` to that address for storage.
380  //
381  alignas(FW_HANDLE_ALIGNMENT) TaskHandleStorage m_handle_storage;
382  TaskInterface& m_delegate;
383  };
384 
385  class TaskRegistry {
386  public:
388  TaskRegistry() = default;
390  virtual ~TaskRegistry() = default;
394  virtual void addTask(Task* task) = 0;
395 
399  virtual void removeTask(Task* task) = 0;
400  };
401 }
402 
403 #endif
unsigned int PlatformUIntType
#define FW_HANDLE_ALIGNMENT
Alignment of handle storage.
Definition: FpConfig.h:440
PlatformSizeType FwSizeType
Definition: FpConfig.h:35
C++-compatible configuration header for fprime configuration.
U8 TaskHandleStorage[FW_TASK_HANDLE_MAX_SIZE]
Definition: Os.hpp:14
Wrapper for task routine that ensures onStart() is called once the task actually begins.
Definition: Task.hpp:199
void invoke()
invoke the run method with "self" as argument
Definition: Task.cpp:48
static void run(void *task_pointer)
run the task routine wrapper
Definition: Task.cpp:27
void * m_user_argument
Argument to user function.
Definition: Task.hpp:215
TaskRoutineWrapper(Task &self)
Definition: Task.cpp:25
Task & m_task
Reference to owning task.
Definition: Task.hpp:213
taskRoutine m_user_function
User function to run once started.
Definition: Task.hpp:214
Task handle representation.
Definition: Task.hpp:24
static FwSizeType getNumTasks()
get the current number of tasks
Definition: Task.cpp:179
bool isCooperative() override
determine if the task is cooperative multitasking (implementation specific)
Definition: Task.cpp:164
static Status delay(Fw::TimeInterval interval)
delay the current task
Definition: Task.cpp:191
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&)")
start this task
Task()
default constructor
Definition: Task.cpp:60
TaskHandle * getHandle() override
return the underlying task handle (implementation specific)
Definition: Task.cpp:174
State getState()
get the task's state
Definition: Task.cpp:74
FwSizeType getPriority()
get the task priority
Definition: Task.cpp:169
FwSizeType ParamType
backwards-compatible parameter type
Definition: Task.hpp:219
static Task & getSingleton()
get a reference to singleton
Definition: Task.cpp:200
static void init()
initialize singleton
Definition: Task.cpp:195
void resume() override
resume a suspended task
Definition: Task.cpp:159
void onStart() override
perform delegate's required task start actions
Definition: Task.cpp:125
Status _delay(Fw::TimeInterval interval) override
delay the current task
Definition: Task.cpp:186
void invokeRoutine()
invoke the task's routine
Definition: Task.cpp:130
void suspend()
suspend the current task
Definition: Task.cpp:70
static void registerTaskRegistry(TaskRegistry *registry)
register a task registry to track Threads
Definition: Task.cpp:205
Status start(const Arguments &arguments) override
start the task
Definition: Task.cpp:82
~Task() final
default virtual destructor
Definition: Task.cpp:62
Status join() override
block until the task has ended
Definition: Task.cpp:134
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))
construct a set of arguments to start a task
Definition: Task.cpp:10
const Os::TaskString m_name
Definition: Task.hpp:83
FwSizeType m_cpuAffinity
Definition: Task.hpp:88
PlatformUIntType m_identifier
Definition: Task.hpp:89
virtual TaskHandle * getHandle()=0
return the underlying task handle (implementation specific)
virtual Status start(const Arguments &arguments)=0
start the task
TaskInterface(const TaskInterface &other)=delete
copy constructor is forbidden
virtual void suspend(SuspensionType suspensionType)=0
suspend the task given the suspension type
virtual Status join()=0
block until the task has ended
virtual void resume()=0
resume a suspended task
TaskInterface()=default
default constructor
virtual Status _delay(Fw::TimeInterval interval)=0
delay the currently scheduled task using the given architecture
static TaskInterface * getDelegate(TaskHandleStorage &aligned_placement_new_memory)
provide a pointer to a task delegate object
Definition: DefaultTask.cpp:11
static constexpr FwSizeType TASK_DEFAULT
Definition: Task.hpp:28
@ SUSPENDED_INTENTIONALLY
Definition: Task.hpp:52
@ SUSPENDED_UNINTENTIONALLY
Definition: Task.hpp:53
virtual ~TaskInterface()=default
default virtual destructor
void(* taskRoutine)(void *ptr)
Prototype for task routine started in task context.
Definition: Task.hpp:59
TaskInterface & operator=(const TaskInterface &other)=delete
assignment operator is forbidden
virtual void onStart()=0
perform required task start actions
@ INVALID_STATE
Task is in an invalid state for the operation.
Definition: Task.hpp:40
@ OP_OK
message sent/received okay
Definition: Task.hpp:30
@ UNKNOWN_ERROR
unexpected error return value
Definition: Task.hpp:34
@ ERROR_PERMISSION
permissions error setting-up tasks
Definition: Task.hpp:39
@ INVALID_PARAMS
started task with invalid parameters
Definition: Task.hpp:32
@ ERROR_RESOURCES
unable to allocate more tasks
Definition: Task.hpp:38
@ DELAY_ERROR
error trying to delay the task
Definition: Task.hpp:36
@ INVALID_STACK
started with invalid stack size
Definition: Task.hpp:33
@ INVALID_HANDLE
Task handle invalid.
Definition: Task.hpp:31
@ INVALID_AFFINITY
unable to set the task affinity
Definition: Task.hpp:35
@ JOIN_ERROR
error trying to join the task
Definition: Task.hpp:37
virtual bool isCooperative()
determine if the task requires cooperative multitasking
Definition: Task.cpp:56
TaskRegistry()=default
default task registry constructor
virtual void addTask(Task *task)=0
add supplied task to the registry
virtual void removeTask(Task *task)=0
remove supplied task to the registry
virtual ~TaskRegistry()=default
default task registry constructor
A class to represent a time interval holding two U32 seconds and microseconds values.