- Generated on Fri Apr 19 2024 10:16:51 by
1.9.8
Thread flags.
This API can be used to notify threads of conditions in a race-free and allocation-less way.
Each thread can handle up to 16 boolean flags, stored as a bitmask in the flags field of its thread. Those flags can be set or unset, using thread_flags_set(), from ISR's, other threads or even by the thread itself.
A thread can wait for any combination of its flags to become set, using thread_flags_wait_any() or thread_flags_wait_all(). Those functions clear flags that caused them to return. It is not possible to wait for flags to become unset.
Thread flags have certain properties that make them the preferred choice over messages or mutexes in some circumstances:
Usually, if it is only of interest that an event occurred, but not how many of them, thread flags should be considered.
Note that some flags (currently the two most significant bits) are used by core functions and should not be set by the user. They can be waited for. Unlike messages (which are only ever sent when requested), these flags can be set unprompted. (For example, THREAD_FLAG_MSG_WAITING is set on a thread automatically with every message sent there).
This API is optional and must be enabled by adding "core_thread_flags" to USEMODULE.
Files | |
| file | thread_flags.h |
| Thread Flags API. | |
Typedefs | |
| typedef uint16_t | thread_flags_t |
| Type definition of thread_flags_t. | |
Functions | |
| void | thread_flags_set (thread_t *thread, thread_flags_t mask) |
| Set thread flags, possibly waking it up. | |
| thread_flags_t | thread_flags_clear (thread_flags_t mask) |
| Clear current thread's flags. | |
| thread_flags_t | thread_flags_wait_any (thread_flags_t mask) |
| Wait for any flag in mask to become set (blocking) | |
| thread_flags_t | thread_flags_wait_all (thread_flags_t mask) |
| Wait for all flags in mask to become set (blocking) | |
| thread_flags_t | thread_flags_wait_one (thread_flags_t mask) |
| Wait for any flags in mask to become set (blocking), one at a time. | |
| int | thread_flags_wake (thread_t *thread) |
| Possibly Wake up thread waiting for flags. | |
reserved thread flags | |
| #define | THREAD_FLAG_MSG_WAITING (1u << 15) |
| Set when a message becomes available. | |
| #define | THREAD_FLAG_TIMEOUT (1u << 14) |
| Set by xtimer_set_timeout_flag() when the timer expires. | |
| #define | THREAD_FLAG_PREDEFINED_MASK (THREAD_FLAG_MSG_WAITING | THREAD_FLAG_TIMEOUT) |
| Comprehensive set of all predefined flags. | |
| #define THREAD_FLAG_MSG_WAITING (1u << 15) |
Set when a message becomes available.
This flag is set for a thread if a message becomes available either by being queued in the thread's message queue or by another thread becoming send-blocked.
It is only reset through thread_flags_wait_*(), not by msg_receive().
One thread flag event might point to one, many or no messages ready to be received. It is advisable to use the non-blocking msg_try_receive() in a loop to retrieve the messages. Use e.g., the following pattern when waiting for both thread flags and messages:
while(1) {
thread_flags_t flags = thread_flags_wait_any(0xFFFF);
if (flags & THREAD_FLAG_MSG_WAITING) {
msg_t msg;
while (msg_try_receive(&msg) == 1) {
[ handle msg ]
}
}
...
}
Definition at line 97 of file thread_flags.h.
| #define THREAD_FLAG_PREDEFINED_MASK (THREAD_FLAG_MSG_WAITING | THREAD_FLAG_TIMEOUT) |
Comprehensive set of all predefined flags.
This bit mask is set for all thread flag bits that are predefined in RIOT. Flags within this set may be set on a thread by the operating system without the thread soliciting them (though not all are; for example, THREAD_FLAG_TIMEOUT is not).
When using custom flags, asserting that they are not in this set can help avoid conflict with future additions to the predefined flags.
Definition at line 116 of file thread_flags.h.
| #define THREAD_FLAG_TIMEOUT (1u << 14) |
Set by xtimer_set_timeout_flag() when the timer expires.
Definition at line 103 of file thread_flags.h.
| typedef uint16_t thread_flags_t |
Type definition of thread_flags_t.
Definition at line 122 of file thread_flags.h.
| thread_flags_t thread_flags_clear | ( | thread_flags_t | mask | ) |
Clear current thread's flags.
| [in] | mask | unset flags for the current thread, represented as a bitmask |
| void thread_flags_set | ( | thread_t * | thread, |
| thread_flags_t | mask | ||
| ) |
Set thread flags, possibly waking it up.
| [in] | thread | thread to work on |
| [in] | mask | additional flags to be set for the current thread, represented as a bitmask |
| thread_flags_t thread_flags_wait_all | ( | thread_flags_t | mask | ) |
Wait for all flags in mask to become set (blocking)
If all the flags in mask are already set, this function will return immediately, otherwise, it will suspend the thread (as THREAD_STATUS_WAIT_ALL) until all of the flags in mask have been set.
Both ways, it will clear and return (thread_get_active()->flags & mask).
| [in] | mask | mask of flags to wait for |
| thread_flags_t thread_flags_wait_any | ( | thread_flags_t | mask | ) |
Wait for any flag in mask to become set (blocking)
If any of the flags in mask are already set, this function will return immediately, otherwise, it will suspend the thread (as THREAD_STATUS_WAIT_ANY) until any of the flags in mask get set.
Both ways, it will clear and return (thread_get_active()->flags & mask).
| [in] | mask | mask of flags to wait for |
thread_get_active()->flags & mask). | thread_flags_t thread_flags_wait_one | ( | thread_flags_t | mask | ) |
Wait for any flags in mask to become set (blocking), one at a time.
This function is like thread_flags_wait_any(), but will only clear and return one flag at a time, least significant set bit first.
| [in] | mask | mask of flags to wait for |
| int thread_flags_wake | ( | thread_t * | thread | ) |
Possibly Wake up thread waiting for flags.
Wakes up a thread if it is thread flag blocked and its condition is met. Has to be called with interrupts disabled. Does not trigger yield.
1.9.8