thread_flags.h File Reference

Thread flags. More...

Detailed Description

Thread flags API

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:

  • setting thread flags cannot fail If messages are used to notify a thread of a condition from within an ISR, and the receiving thread is not waiting, has no queue or the queue is full, the ISR cannot deliver the message. A thread flag can always be set.
  • thread flags are very flexible With thread flags it is possible to wait for multiple conditions and messages at the same time. When mutexes are used to notify about events, only one event can be waited for.

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 three most significant bits) are used by core functions and should not be set by the user. They can be waited for.

Author
Kaspar Schleiser kaspa.nosp@m.r@sc.nosp@m.hleis.nosp@m.er.d.nosp@m.e

Definition in file thread_flags.h.

#include "kernel_types.h"
#include "sched.h"
+ Include dependency graph for thread_flags.h:

Go to the source code of this file.

Macros

reserved thread flags
#define THREAD_FLAG_MSG_WAITING   (0x1<<15)
 
#define THREAD_FLAG_MUTEX_UNLOCKED   (0x1<<14)
 
#define THREAD_FLAG_TIMEOUT   (0x1<<13)
 

Define type of thread_flags_t

typedef uint16_t thread_flags_t
 
void thread_flags_set (thread_t *thread, thread_flags_t mask)
 Set thread flags, possibly waking it up. More...
 
thread_flags_t thread_flags_clear (thread_flags_t mask)
 Clear current thread's flags. More...
 
thread_flags_t thread_flags_wait_any (thread_flags_t mask)
 Wait for any flag in mask to become set (blocking) More...
 
thread_flags_t thread_flags_wait_all (thread_flags_t mask)
 Wait for all flags in mask to become set (blocking) More...
 
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. More...
 
int thread_flags_wake (thread_t *thread)
 Possibly Wake up thread waiting for flags. More...
 

Function Documentation

◆ thread_flags_clear()

thread_flags_t thread_flags_clear ( thread_flags_t  mask)
Parameters
[in]maskunset flags for the current thread, represented as a bitmask
Returns
flags that have actually been cleared (mask & thread->flags before clear)

◆ thread_flags_set()

void thread_flags_set ( thread_t thread,
thread_flags_t  mask 
)
Parameters
[in]threadthread to work on
[in]maskadditional flags to be set for the current thread, represented as a bitmask

◆ thread_flags_wait_all()

thread_flags_t thread_flags_wait_all ( thread_flags_t  mask)

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 (sched_active_thread-flags & mask).

Parameters
[in]maskmask of flags to wait for
Returns
mask

◆ thread_flags_wait_any()

thread_flags_t thread_flags_wait_any ( thread_flags_t  mask)

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 (sched_active_thread-flags & mask).

Parameters
[in]maskmask of flags to wait for
Returns
flags that caused return/wakeup ((sched_active_thread-flags & mask).

◆ thread_flags_wait_one()

thread_flags_t thread_flags_wait_one ( thread_flags_t  mask)

This function is like thread_flags_wait_any(), but will only clear and return one flag at a time, least significant set bit first.

Parameters
[in]maskmask of flags to wait for
Returns
flag that triggered the return / wait

◆ thread_flags_wake()

int thread_flags_wake ( thread_t thread)

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.