Skip to content

Commit a6e6501

Browse files
arkhipenkoarkhipenko
authored
Refactor and clarify compile-time options documentation
Updated documentation for compile-time options, consolidating and clarifying descriptions for various task scheduling features.
1 parent cd2b4a3 commit a6e6501

File tree

1 file changed

+90
-130
lines changed

1 file changed

+90
-130
lines changed

‎src/TaskSchedulerDeclarations.h‎

Lines changed: 90 additions & 130 deletions
Original file line numberDiff line numberDiff line change
@@ -29,148 +29,108 @@
2929
// ----------------------------------------
3030
/**
3131
* @defgroup CompileTimeOptions Compile Time Options
32-
* @brief The following "defines" control library functionality at compile time,
33-
* and should be used in the main sketch depending on the functionality required
34-
* @{
35-
*/
36-
37-
/**
38-
* @def _TASK_TIMECRITICAL
39-
* @brief Enable monitoring scheduling overruns
40-
* @details Enables tracking when the current execution took place relative to when it was scheduled.
32+
* @brief Available compile-time configuration options
33+
*
34+
* The following defines control library functionality at compile time,
35+
* and should be used in the main sketch depending on the functionality required.
36+
* To enable any option, uncomment the corresponding #define in your code.
37+
*
38+
* @par _TASK_TIMECRITICAL
39+
* Enable monitoring scheduling overruns.
40+
* Enables tracking when the current execution took place relative to when it was scheduled.
4141
* Provides getStartDelay() and getOverrun() methods for performance monitoring.
42-
*/
43-
44-
/**
45-
* @def _TASK_SLEEP_ON_IDLE_RUN
46-
* @brief Enable 1 ms SLEEP_IDLE powerdowns between runs if no callback methods were invoked during the pass
47-
* @details When enabled, the scheduler will place the processor into IDLE sleep mode for approximately 1 ms
42+
*
43+
* @par _TASK_SLEEP_ON_IDLE_RUN
44+
* Enable 1 ms SLEEP_IDLE powerdowns between runs if no callback methods were invoked during the pass.
45+
* When enabled, the scheduler will place the processor into IDLE sleep mode for approximately 1 ms
4846
* after what is determined to be an "idle" pass. AVR boards only.
49-
*/
50-
51-
/**
52-
* @def _TASK_STATUS_REQUEST
53-
* @brief Compile with support for StatusRequest functionality
54-
* @details Enables triggering tasks on status change events in addition to time-based scheduling.
47+
*
48+
* @par _TASK_STATUS_REQUEST
49+
* Compile with support for StatusRequest functionality.
50+
* Enables triggering tasks on status change events in addition to time-based scheduling.
5551
* Allows tasks to wait on an event and signal event completion to each other.
56-
*/
57-
58-
/**
59-
* @def _TASK_WDT_IDS
60-
* @brief Compile with support for watchdog timer control points and task IDs
61-
* @details Each task can be assigned an ID and Control Points can be defined within tasks
52+
*
53+
* @par _TASK_WDT_IDS
54+
* Compile with support for watchdog timer control points and task IDs.
55+
* Each task can be assigned an ID and Control Points can be defined within tasks
6256
* for watchdog timer integration and error handling.
63-
*/
64-
65-
/**
66-
* @def _TASK_LTS_POINTER
67-
* @brief Compile with support for local task storage pointer
68-
* @details LTS is a generic (void*) pointer that can reference a variable or structure
57+
*
58+
* @par _TASK_LTS_POINTER
59+
* Compile with support for local task storage pointer.
60+
* LTS is a generic (void*) pointer that can reference a variable or structure
6961
* specific to a particular task, allowing the same callback code for multiple tasks.
70-
*/
71-
72-
/**
73-
* @def _TASK_PRIORITY
74-
* @brief Support for layered scheduling priority
75-
* @details Enables task prioritization by creating several schedulers and organizing them in priority layers.
62+
*
63+
* @par _TASK_PRIORITY
64+
* Support for layered scheduling priority.
65+
* Enables task prioritization by creating several schedulers and organizing them in priority layers.
7666
* Higher priority tasks are evaluated more frequently.
77-
*/
78-
79-
/**
80-
* @def _TASK_MICRO_RES
81-
* @brief Support for microsecond resolution
82-
* @details Enables microsecond scheduling resolution instead of default millisecond resolution.
67+
*
68+
* @par _TASK_MICRO_RES
69+
* Support for microsecond resolution.
70+
* Enables microsecond scheduling resolution instead of default millisecond resolution.
8371
* All time-relevant parameters will be treated as microseconds.
84-
*/
85-
86-
/**
87-
* @def _TASK_STD_FUNCTION
88-
* @brief Support for std::function (ESP8266/ESP32 ONLY)
89-
* @details Enables support for standard functions instead of function pointers for callbacks.
90-
*/
91-
92-
/**
93-
* @def _TASK_DEBUG
94-
* @brief Make all methods and variables public for debug purposes
95-
* @details Should not be used in production. Exposes all private and protected members as public.
96-
*/
97-
98-
/**
99-
* @def _TASK_INLINE
100-
* @brief Make all methods "inline"
101-
* @details Needed to support some multi-tab, multi-file implementations. Lets compiler optimize.
102-
*/
103-
104-
/**
105-
* @def _TASK_TIMEOUT
106-
* @brief Support for overall task timeout
107-
* @details Any task can be set to time out after a certain period, and timeout can be reset.
72+
*
73+
* @par _TASK_STD_FUNCTION
74+
* Support for std::function (ESP8266/ESP32 ONLY).
75+
* Enables support for standard functions instead of function pointers for callbacks.
76+
*
77+
* @par _TASK_DEBUG
78+
* Make all methods and variables public for debug purposes.
79+
* Should not be used in production. Exposes all private and protected members as public.
80+
*
81+
* @par _TASK_INLINE
82+
* Make all methods "inline".
83+
* Needed to support some multi-tab, multi-file implementations. Lets compiler optimize.
84+
*
85+
* @par _TASK_TIMEOUT
86+
* Support for overall task timeout.
87+
* Any task can be set to time out after a certain period, and timeout can be reset.
10888
* Can be used as an individual Task's watchdog timer.
109-
*/
110-
111-
/**
112-
* @def _TASK_OO_CALLBACKS
113-
* @brief Support for callbacks via inheritance
114-
* @details Useful for implementing Tasks as classes derived from the Task class.
89+
*
90+
* @par _TASK_OO_CALLBACKS
91+
* Support for callbacks via inheritance.
92+
* Useful for implementing Tasks as classes derived from the Task class.
11593
* Enables dynamic binding for object-oriented callback approach.
116-
*/
117-
118-
/**
119-
* @def _TASK_EXPOSE_CHAIN
120-
* @brief Methods to access tasks in the task chain
121-
* @details Provides access to scheduling chain methods and tasks on the chain.
122-
*/
123-
124-
/**
125-
* @def _TASK_SCHEDULING_OPTIONS
126-
* @brief Support for multiple scheduling options
127-
* @details Enables different task scheduling options like TASK_SCHEDULE, TASK_SCHEDULE_NC, and TASK_INTERVAL.
128-
*/
129-
130-
/**
131-
* @def _TASK_SELF_DESTRUCT
132-
* @brief Enable tasks to "self-destruct" after disable
133-
* @details Tasks can be set to automatically delete themselves when disabled.
134-
*/
135-
136-
/**
137-
* @def _TASK_TICKLESS
138-
* @brief Enable support for tickless sleep on FreeRTOS
139-
* @details Enables support for tickless sleep mode on FreeRTOS systems.
140-
*/
141-
142-
/**
143-
* @def _TASK_DO_NOT_YIELD
144-
* @brief Disable yield() method in execute() for ESP chips
145-
* @details Disables automatic yielding in the execute loop for ESP-based systems.
146-
*/
147-
148-
/**
149-
* @def _TASK_ISR_SUPPORT
150-
* @brief For ESP chips - place control methods in IRAM
151-
* @details Places critical control methods in IRAM for ESP8266/ESP32 interrupt support.
152-
*/
153-
154-
/**
155-
* @def _TASK_NON_ARDUINO
156-
* @brief For non-Arduino use
157-
* @details Enables compilation for non-Arduino environments.
158-
*/
159-
160-
/**
161-
* @def _TASK_HEADER_AND_CPP
162-
* @brief Compile CPP file (non-Arduino IDE platforms)
163-
* @details For non-Arduino IDE platforms that require explicit CPP compilation.
164-
*/
165-
166-
/**
167-
* @def _TASK_THREAD_SAFE
168-
* @brief Enable additional checking for thread safety
169-
* @details Uses an internal mutex to protect task scheduling methods from preemption.
94+
*
95+
* @par _TASK_EXPOSE_CHAIN
96+
* Methods to access tasks in the task chain.
97+
* Provides access to scheduling chain methods and tasks on the chain.
98+
*
99+
* @par _TASK_SCHEDULING_OPTIONS
100+
* Support for multiple scheduling options.
101+
* Enables different task scheduling options like TASK_SCHEDULE, TASK_SCHEDULE_NC, and TASK_INTERVAL.
102+
*
103+
* @par _TASK_SELF_DESTRUCT
104+
* Enable tasks to "self-destruct" after disable.
105+
* Tasks can be set to automatically delete themselves when disabled.
106+
*
107+
* @par _TASK_TICKLESS
108+
* Enable support for tickless sleep on FreeRTOS.
109+
* Enables support for tickless sleep mode on FreeRTOS systems.
110+
*
111+
* @par _TASK_DO_NOT_YIELD
112+
* Disable yield() method in execute() for ESP chips.
113+
* Disables automatic yielding in the execute loop for ESP-based systems.
114+
*
115+
* @par _TASK_ISR_SUPPORT
116+
* For ESP chips - place control methods in IRAM.
117+
* Places critical control methods in IRAM for ESP8266/ESP32 interrupt support.
118+
*
119+
* @par _TASK_NON_ARDUINO
120+
* For non-Arduino use.
121+
* Enables compilation for non-Arduino environments.
122+
*
123+
* @par _TASK_HEADER_AND_CPP
124+
* Compile CPP file (non-Arduino IDE platforms).
125+
* For non-Arduino IDE platforms that require explicit CPP compilation.
126+
*
127+
* @par _TASK_THREAD_SAFE
128+
* Enable additional checking for thread safety.
129+
* Uses an internal mutex to protect task scheduling methods from preemption.
170130
* Recommended for ESP32 and other MCUs running under preemptive schedulers like FreeRTOS.
131+
*
171132
*/
172133

173-
/** @} */ // End of CompileTimeOptions group
174134

175135
#ifdef _TASK_NON_ARDUINO
176136
#include <stdbool.h>

0 commit comments

Comments
 (0)