Synchronize threads using flags. More...
Functions | |
uint32_t | osThreadFlagsSet (osThreadId_t thread_id, uint32_t flags) |
Set the specified Thread Flags of a thread. | |
uint32_t | osThreadFlagsClear (uint32_t flags) |
Clear the specified Thread Flags of current running thread. | |
uint32_t | osThreadFlagsGet (void) |
Get the current Thread Flags of current running thread. | |
uint32_t | osThreadFlagsWait (uint32_t flags, uint32_t options, uint32_t timeout) |
Wait for one or more Thread Flags of the current running thread to become signaled. | |
Synchronize threads using flags.
Thread Flags are a more specialized version of the Event Flags. See Event Flags. While Event Flags can be used to globally signal a number of threads, thread flags are only send to a single specific thread. Every thread instance can receive thread flags without any additional allocation of a thread flags object.
Usage Example
The following (incomplete) code excerpt sketches the usage principals for Thread Flags.
The behavior is the following:
uint32_t osThreadFlagsSet | ( | osThreadId_t | thread_id, |
uint32_t | flags | ||
) |
Set the specified Thread Flags of a thread.
[in] | thread_id | thread ID obtained by osThreadNew or osThreadGetId. |
[in] | flags | specifies the flags of the thread that shall be set. |
The function osThreadFlagsSet sets the thread flags for a thread specified by parameter thread_id. The thread returns the flags stored in the thread control block, or an error code if highest bit is set (refer to Flags Functions Error Codes). Refer to Usage Examples below to understand how the return value is computed.
The target thread waiting for a flag to be set will resume from BLOCKED state.
Possible Flags Functions Error Codes return values:
Code Example
Usage Examples
The following diagram assumes that in the control block of Thread1 the flag 1 is already set. Thread2 now sets flag 2 and Thread1 returns the updated value immediately:
Depending on thread scheduling, the flag status can be modified before returning:
uint32_t osThreadFlagsClear | ( | uint32_t | flags | ) |
Clear the specified Thread Flags of current running thread.
[in] | flags | specifies the flags of the thread that shall be cleared. |
The function osThreadFlagsClear clears the specified flags for the currently running thread. It returns the flags before clearing, or an error code if highest bit is set (refer to Flags Functions Error Codes).
Possible Flags Functions Error Codes return values:
uint32_t osThreadFlagsGet | ( | void | ) |
Get the current Thread Flags of current running thread.
The function osThreadFlagsGet returns the flags currently set for the currently running thread. If called without a active and currently running thread osThreadFlagsGet return zero.
uint32_t osThreadFlagsWait | ( | uint32_t | flags, |
uint32_t | options, | ||
uint32_t | timeout | ||
) |
Wait for one or more Thread Flags of the current running thread to become signaled.
[in] | flags | specifies the flags to wait for. |
[in] | options | specifies flags options (osFlagsXxxx). |
[in] | timeout | Timeout Values or 0 in case of no time-out. |
The function osThreadFlagsWait suspends the execution of the currently RUNNING thread until any or all of the thread flags specified with the parameter flags are set. When these thread flags are already set, the function returns instantly. Otherwise the thread is put into the state BLOCKED.
The parameter options specifies the wait condition:
Option | |
---|---|
osFlagsWaitAny | Wait for any flag (default). |
osFlagsWaitAll | Wait for all flags. |
osFlagsNoClear | Do not clear flags which have been specified to wait for. |
If osFlagsNoClear
is set in the options osThreadFlagsClear can be used to clear flags manually. Otherwise osThreadFlagsWait automatically clears the flags waited for.
The parameter timeout represents a number of timer ticks and is an upper bound. The exact time delay depends on the actual time elapsed since the last timer tick.
The function returns the flags before clearing, or an error code if highest bit is set (refer to Flags Functions Error Codes).
Possible Flags Functions Error Codes return values:
Code Example