CMSIS-RTOS2 文档翻译 之 参考（CMSIS-RTOS2 API 之 线程标志）

线程标志

CMSIS-RTOS2 API

使用标志同步线程。更多...

函数
uint32_t	osThreadFlagsSet (osThreadId_t thread_id, uint32_t flags)
	设置线程的指定线程标志。更多...
uint32_t	osThreadFlagsClear (uint32_t flags)
	清除当前运行线程的指定线程标志。更多...
uint32_t	osThreadFlagsGet (void)
	获取当前正在运行的线程的当前线程标志。更多...
uint32_t	osThreadFlagsWait (uint32_t flags, uint32_t options, uint32_t timeout)
	等待当前正在运行的线程的一个或多个线程标志发出信号。更多...

描述

线程标志是事件标志的更专业版本。请参阅事件标志。虽然事件标志可用于全局发送多个线程，但线程标志只能发送到单个特定线程。每个线程实例都可以接收线程标志，而不需要额外分配线程标志对象。

注意

线程标志管理函数不能从中断服务例程调用，osThreadFlagsSet 除外。

用法示例

以下（不完整）代码片段描述线程标志的使用原则。

行为如下：

• app_main 开始执行
• 语句 A 将线程标志设置为 0x02（标志 = 0x02 - 设置后）
• app_main 输入延迟
• 执行切换到 threadX
• 语句 B 等待标志 0x01 并且因为标志未被设置而阻塞
• 执行切换到 app_main
• 语句 C 将线程标志设置为 0x07
• threadX 唤醒并清除标志 0x01，线程标志 = 0x06，返回值设置为 0x07（在清除之前），注意：所有这些都发生在语句 C
• 语句 C 返回标志 = 0x06
• app_main 输入延迟
• 执行切换到 threadX
• 语句 B 以 flagsX = 0x07 返回

#include "cmsis_os2.h"

osThreadId_t tid;

uint32_t flagsX;

uint32_t flags;

void threadX ( void *argument) {

osDelay(1U);

for (;;) {

flagsX = osThreadFlagsWait(0x0001U, osFlagsWaitAny, osWaitForever); /* B */

}

}

void app_main ( void *argument) {

tid = osThreadNew(threadX, NULL, NULL);

flags = osThreadFlagsSet(tid, 0x0002U); /* A */

osDelay(2U);

flags = osThreadFlagsSet(tid, 0x0005U); /* C */

osDelay(2U);

for(;;);

}

函数文档

uint32_t osThreadFlagsSet	(	osThreadId_t	thread_id,
		uint32_t	flags
	)

参数

[in]	thread_id	线程 ID 由 osThreadNew 或 osThreadGetId 获取。
[in]	flags	指定应该设置的线程的标志。

返回

设置后的线程标志或设置最高位时的错误代码。

函数 osThreadFlagsSet 为参数 thread_id 指定的线程设置线程标志。它返回标志设置，或者如果设置了最高位，则返回错误代码（请参阅标志功能错误代码）。该功能也可以在中断服务程序中使用。等待标志被设置的线程将从阻塞状态恢复。

可能的标志功能错误代码返回值：

• osFlagsErrorUnknown: 未指定的错误。
• osFlagsErrorResource: 由参数 thread_id 指定的线程无效以接收标志。
• osFlagsErrorParameter: 参数 thread_id 不是有效的线程，或者标志的最高位被设置。

注意

这个函数可以从中断服务程序中调用。

代码示例

/*----------------------------------------------------------------------------

* Function 'signal_func' called from multiple threads

*---------------------------------------------------------------------------*/

void signal_func ( osThreadId_t tid) {

osThreadFlagsSet(tid_clock, 0x0100); /* set signal to clock thread */

osDelay(500); /* delay 500ms */

osThreadFlagsSet(tid_clock, 0x0100); /* set signal to clock thread */

osDelay(500); /* delay 500ms */

osThreadFlagsSet(tid, 0x0001); /* set signal to thread 'thread' */

osDelay(500); /* delay 500ms */

}

uint32_t osThreadFlagsClear

(

uint32_t

flags

)

参数

[in]

flags

指定应被清除的线程标志。

返回

清除前的线程标志或设置最高位时的错误代码。

函数 osThreadFlagsClear 清除当前正在运行的线程的指定标志。它在清除之前返回标志，如果设置了最高位，则返回错误代码（请参阅标志功能错误代码）。

可能的标志功能错误代码返回值：

• osFlagsErrorUnknown: 未指定的错误，即不从正在运行的线程上下文中调用。
• osFlagsErrorResource: 正在运行的线程无法接收标志。
• osFlagsErrorParameter: 参数标志的最高位被设置。

注意

该函数不能从中断服务程序调用。

uint32_t osThreadFlagsGet

(

void

)

返回

当前线程标志。

函数 osThreadFlagsGet 返回为当前运行的线程设置的标志。如果调用没有活动和当前正在运行的线程 osThreadFlagsGet 返回零。

注意

该函数不能从中断服务程序调用。

uint32_t osThreadFlagsWait	(	uint32_t	flags,
		uint32_t	options,
		uint32_t	timeout
	)

参数

[in]	flags	指定要等待的标志。
[in]	options	指定标志选项（osFlagsXxxx）。
[in]	timeout	超时值或 0 在没有超时的情况下。

返回

清除前的线程标志或设置最高位时的错误代码。

osThreadFlagsWait 函数暂停执行当前的 RUNNING 线程，直到设置了任何或所有使用参数标志指定的线程标志为止。当这些线程标志已经被设置时，该函数立即返回。否则，线程将进入 BLOCKED 状态。

参数选项指定等待条件：

选项
osFlagsWaitAny	等待任何标志（默认）。
osFlagsWaitAll	等待所有的标志。
osFlagsNoClear	不要清除已经指定等待的标志。

如果在选项中设置了 osFlagsNoClear ，则可以使用 osThreadFlagsClear 手动清除标志。否则 osThreadFlagsWait 自动清除等待的标志。

参数超时代表一些计时器滴答，并且是一个上限。确切的时间延迟取决于自上次计时器刻度以来所经过的实际时间。

该函数在清除之前返回标志，如果设置了最高位，则返回错误代码（请参阅标志函数错误代码）。

可能的标志功能错误代码返回值：

• osFlagsErrorUnknown: 未指定的错误，即不从正在运行的线程上下文中调用。
• osFlagsErrorTimeout: 在给定的超时期间，等待的标志没有被设置。
• osFlagsErrorResource: 正在运行的线程无法接收标志。
• osFlagsErrorParameter: 参数标志的最高位被设置。

注意

该函数不能从中断服务程序调用。

代码示例

#include "cmsis_os2.h"

void Thread ( void* arg) {

;

osThreadFlagsWait (0x00000001U, osFlagsWaitAny, osWaitForever); // Wait forever until thread flag 1 is set.

;

osThreadFlagsWait (0x00000003U, osFlagsWaitAny, osWaitForever); // Wait forever until either thread flag 0 or 1 is set.

;

osThreadFlagsWait (0x00000003U, osFlagsWaitAll, 10); // Wait for 10 timer ticks until thread flags 0 and 1 are set. Timeout afterwards.

;

osThreadFlagsWait (0x00000003U, osFlagsWaitAll | osFlagsNoClear, osWaitForever); // Same as the above, but the flags will not be cleared.

}