AFBR-S50 API Reference Manual  v1.6.5
AFBR-S50 Time-of-Flight Sensor SDK for Embedded Software
task_scheduler.h
Go to the documentation of this file.
1 /*************************************************************************/
38 #ifndef TASK_SCHEDULER_H
39 #define TASK_SCHEDULER_H
40 
41 /*!***************************************************************************
42  * @defgroup scheduler Task Scheduler
43  * @ingroup explorer_app
44  *
45  * @brief A simple cooperative task scheduler with prioritized tasks.
46  *
47  * @details A simple cooperative task scheduler with prioritized tasks.
48  *
49  * @addtogroup scheduler
50  * @{
51  *****************************************************************************/
52 
53 #include <stdint.h>
54 #include <stddef.h>
55 #include <stdbool.h>
56 
57 #include "task_status.h"
58 
59 /*!***************************************************************************
60  * @brief Maximum Number of tasks.
61  * @warning Maximum number is 32 due to internal data structures of size uint32.
62  * If larger number of tasks are desired, the internal data structures
63  * need to be adjusted.
64  *****************************************************************************/
65 #define SCHEDULER_MAX_TASKS 8U
66 
67 /*!***************************************************************************
68  * @brief Definition of the task priority (and unique task ID).
69  * @details Higher values mean higher urgency.
70  * Priority 0 can be used for IDLE task.
71  *****************************************************************************/
72 typedef uint8_t task_prio_t;
73 
74 /*!***************************************************************************
75  * @brief Task scheduler type definition.
76  *****************************************************************************/
77 typedef struct scheduler_t scheduler_t;
78 
79 /*!***************************************************************************
80  * @brief Task event type definition.
81  *****************************************************************************/
82 typedef void * task_event_t;
83 
84 /*!***************************************************************************
85  * @brief Task functions definition.
86  * @param e Task event pointer. An abstract pointer to an task intern data
87  * structure.
88  *****************************************************************************/
89 typedef void (*task_function_t)(task_event_t e);
90 
91 /*!***************************************************************************
92  * @brief Initializes the task scheduler.
93  * @details Resets internal data structures to a known state.
94  * @return Returns the abstract pointer to the scheduler handle object.
95  *****************************************************************************/
96 scheduler_t* Scheduler_Init(void);
97 
98 /*!***************************************************************************
99  * @brief Runs the task scheduler.
100  * @details This is the main routine for the scheduler module. It schedules all
101  * the pending tasks in order of priority in an endless loop.
102  * If an error occurs within an task, the error is logged, but not
103  * handled!
104  * @param me The instance handle of the task scheduler.
105  *****************************************************************************/
106 void Scheduler_Run(scheduler_t * const me);
107 
108 /*!***************************************************************************
109  * @brief Suspends the current task and runs another task.
110  * @details The function can be called from within a task in order to suspend
111  * the current task and run other task (to completion). The function
112  * return when the other task is finished. The function runs exactly
113  * one other task, even if more are pending. The function can be
114  * called another time to run another task. If no tasks are pending,
115  * the function does nothing.
116  * @note This function never returns!
117  * @param me The instance handle of the task scheduler.
118  *****************************************************************************/
119 void Scheduler_SwitchContext(scheduler_t * const me);
120 
121 /*!***************************************************************************
122  * @brief Adds an new task to the scheduler.
123  * @param me The instance handle of the task scheduler.
124  * @param task A pointer to the task function to be executed.
125  * @param priority The priority level for the task. Every priority level
126  * can only have one task!
127  * @param eventQ A pointer to the task event queue.
128  * @param eventQSize The size of the task event queue.
129  * @param name A descriptive name of the task.
130  * @return Returns the \link #status_t status\endlink (#STATUS_OK on success).
131  *****************************************************************************/
132 status_t Scheduler_AddTask(scheduler_t * const me,
133  task_function_t task,
134  task_prio_t priority,
135  task_event_t eventQ,
136  size_t eventQSize,
137  const char * name);
138 
139 /*!***************************************************************************
140  * @brief Posts an event to the scheduler and executes it as soon as possible
141  * @param me The instance handle of the task scheduler.
142  * @param priority The priority of the task to be executed.
143  * @param event A void* pointer to and task event parameter.
144  * @return Returns the \link #status_t status\endlink (#STATUS_OK on success).
145  *****************************************************************************/
146 status_t Scheduler_PostEvent(scheduler_t * const me,
147  task_prio_t priority,
148  task_event_t event);
149 
150 /*!***************************************************************************
151  * @brief Checks whether a specified task is pending for execution.
152  * @param me The instance handle of the task scheduler.
153  * @param priority The priority of the task to be checked.
154  * @return Returns true if the task is pending, false otherwise.
155  *****************************************************************************/
156 bool Scheduler_IsTaskPending(scheduler_t * const me,
157  task_prio_t priority);
158 
160 #endif /* TASK_SCHEDULER_H */
Scheduler_IsTaskPending
bool Scheduler_IsTaskPending(scheduler_t *const me, task_prio_t priority)
Checks whether a specified task is pending for execution.
Definition: task_scheduler.c:166
Scheduler_Init
scheduler_t * Scheduler_Init(void)
Initializes the task scheduler.
Definition: task_scheduler.c:97
Scheduler_PostEvent
status_t Scheduler_PostEvent(scheduler_t *const me, task_prio_t priority, task_event_t event)
Posts an event to the scheduler and executes it as soon as possible.
Definition: task_scheduler.c:133
Scheduler_SwitchContext
void Scheduler_SwitchContext(scheduler_t *const me)
Suspends the current task and runs another task.
Definition: task_scheduler.c:181
task_prio_t
uint8_t task_prio_t
Definition of the task priority (and unique task ID).
Definition: task_scheduler.h:72
task_event_t
void * task_event_t
Task event type definition.
Definition: task_scheduler.h:82
task_function_t
void(* task_function_t)(task_event_t e)
Task functions definition.
Definition: task_scheduler.h:89
task_status.h
This file is part of the AFBR-S50 Explorer example application.
Scheduler_AddTask
status_t Scheduler_AddTask(scheduler_t *const me, task_function_t task, task_prio_t priority, task_event_t eventQ, size_t eventQSize, const char *name)
Adds an new task to the scheduler.
Definition: task_scheduler.c:105
status_t
int32_t status_t
Type used for all status and error return values.
Definition: argus_status.h:70
Scheduler_Run
void Scheduler_Run(scheduler_t *const me)
Runs the task scheduler.
Definition: task_scheduler.c:172