Struct Flg

pub struct Flg<const N: XwSz>
where
    [XwBmp; { _ }]: Sized,
{ /* private fields */ }

事件标志对象结构体

Implementations

impl<const N: XwSz> Flg<N>

where [XwBmp; { _ }]: Sized,

pub const fn new() -> Self

新建事件标志对象

此方法是编译期方法。

示例

• 具有 static 约束的全局变量全局变量：

use xwrust::xwos::sync::flg::*;

static GLOBAL_FLG: Flg<8> = Flg::new();

• 在heap中创建：

extern crate alloc;
use alloc::sync::Arc;

pub fn xwrust_example_flg() {
    let flg = Arc::new(Flg::<8>::new());
}

pub fn init(&self)

初始化事件标志对象

事件标志对象必须调用此方法一次，方可正常使用。

上下文

• 任意

示例

use xwrust::xwos::sync::flg::*;

static GLOBAL_FLG: Flg<8> = Flg::new();

pub fn xwrust_example_flg() {
    // ...省略...
    GLOBAL_FLG.init();
    // 从此处开始 GLOBAL_FLG 可正常使用
}

pub const fn get_num(&self) -> XwSz

获取事件标志中事件槽的数量

pub fn read(&self) -> Result<Bmp<N>, FlgError>

读取事件标志位图的值

直接读取位图的值，不会等待，也不会改变位图的状态。

pub fn s1m(&self, msk: &Bmp<N>) -> FlgError

同时设置多个事件标志位

此方法会将事件标志位图中，被掩码 msk 覆盖的位全部设置为 1 。

此方法除了会修改事件标志位图的状态，还会通过 广播 唤醒所有正在等待的线程。 然后，线程通过比对位图状态，确定事件是否已经满足触发条件。 若满足触发条件，就退出等待；若未满足触发条件，重新进入阻塞等待状态。

参数说明

• msk: 事件的位图掩码

pub fn s1i(&self, pos: XwSq) -> FlgError

设置单个事件标志位

此方法会将事件标志位图中，序号为 pos 的单个位设置为 1 。

此函数除了会修改事件标志位图的状态，还会通过 广播 唤醒所有正在等待的线程。 然后，线程通过比对位图状态，确定事件是否已经满足触发条件。 若满足触发条件，就退出等待；若未满足触发条件，重新进入阻塞等待状态。

参数说明

• pos: 事件的序号

pub fn c0m(&self, msk: &Bmp<N>) -> FlgError

同时清除多个事件标志位

此方法会将事件标志位图中，被掩码 msk 覆盖的位全部清 0 。

此方法除了会修改事件标志位图的状态，还会通过 广播 唤醒所有正在等待的线程。 然后，线程通过比对位图状态，确定事件是否已经满足触发条件。 若满足触发条件，就退出等待；若未满足触发条件，重新进入阻塞等待状态。

参数说明

• msk: 事件的位图掩码

pub fn c0i(&self, pos: XwSq) -> FlgError

清除单个事件标志位

此方法会将事件标志位图中，序号为 pos 的单个位清 0 。

此函数除了会修改事件标志位图的状态，还会通过 广播 唤醒所有正在等待的线程。 然后，线程通过比对位图状态，确定事件是否已经满足触发条件。 若满足触发条件，就退出等待；若未满足触发条件，重新进入阻塞等待状态。

参数说明

• pos: 事件的序号

pub fn x1m(&self, msk: &Bmp<N>) -> FlgError

同时翻转多个事件标志位

此方法会将事件标志位图中，被掩码 msk 覆盖的位全部翻转。

此方法除了会修改事件标志位图的状态，还会通过 广播 唤醒所有正在等待的线程。 然后，线程通过比对位图状态，确定事件是否已经满足触发条件。 若满足触发条件，就退出等待；若未满足触发条件，重新进入阻塞等待状态。

参数说明

• msk: 事件的位图掩码

pub fn x1i(&self, pos: XwSq) -> FlgError

翻转单个事件标志位

此方法会将事件标志位图中，序号为 pos 的单个位翻转。

此函数除了会修改事件标志位图的状态，还会通过 广播 唤醒所有正在等待的线程。 然后，线程通过比对位图状态，确定事件是否已经满足触发条件。 若满足触发条件，就退出等待；若未满足触发条件，重新进入阻塞等待状态。

参数说明

• pos: 事件的序号

pub fn wait( &self, tg: Trigger, act: Action, origin: &mut Bmp<N>, msk: &Bmp<N>, ) -> FlgError

等待事件

• 当没有检测到事件时，线程会阻塞等待。
• 当检测到事件时，线程被唤醒，然后返回 FlgError::Ok 。
• 当线程阻塞等待被中断时，返回 FlgError::Interrupt 。

事件的触发条件

事件的触发条件可通过参数 tg 设置。事件的触发条件分为两类。

电平触发

电平触发 源于数字电路，是一种类比概念，是指事件位图的特定状态（ 1 或 0 ）所产生的触发事件，包括：

• Trigger::SetAll 所有事件位被置 1 触发
• Trigger::SetAny 任意事件位被置 1 触发
• Trigger::ClearAll 所有事件位被清 0 触发
• Trigger::ClearAny 任意事件位被清 0 触发

电平触发 时，若参数 action 取值 Action::Consumption ，表示线程在读取事件位图后，会 清除 事件位图。 电平触发 时，参数 origin 用于返回事件发生时的位图状态。

边沿触发

边沿触发 源于数字电路，是一种类比概念，是指事件状态发生改变（ 1 变 0 或 0 变 1 ）时产生的唤醒信号，包括：

• Trigger::SetAll 所有事件位发生翻转触发
• Trigger::SetAny 任意事件位发生翻转触发

边沿触发 时，参数 action 没有作用，取值 Action::None 即可。 边沿触发 时，必须要有一个初始状态，就像数字电路一样：

• 当位的初始值为 0 (低电平)，然后跳变到 1 (高电平)的瞬间被称为上升沿。此时触发的事件被称为上升沿触发。
• 当位的初始值为 1 (高电平)，然后跳变到 0 (低电平)的瞬间被称为下降沿。此时触发的事件被称为下降沿触发。

初始值就由参数 origin 指明，触发后，事件位发生跳变，跳变后的结果还是由参数 origin 返回。

参数说明

• tg: 事件触发条件
• act: 事件触发后的动作
• origin: 事件位图
  • 电平触发 时，参数 origin 用于返回事件发生时的位图状态。
  • 初始值就由参数 origin 指明，触发后，事件位发生跳变，跳变后的结果还是由参数 origin 返回。
• msk: 事件的位图掩码

上下文

• 线程

错误码

• FlgError::Ok 没有错误
• FlgError::NotInit 事件标志没有初始化
• FlgError::Interrupt 等待被中断
• FlgError::NotThreadContext 不在线程上下文内

示例

extern crate alloc;
use alloc::sync::Arc;

use xwrust::xwos::sync::flg::*;

pub fn xwrust_example_flg() {
}

pub fn wait_to( &self, tg: Trigger, act: Action, origin: &mut Bmp<N>, msk: &Bmp<N>, to: XwTm, ) -> FlgError

限时等待事件

• 当没有检测到事件时，线程会阻塞等待，等待时会指定一个唤醒时间点 to 。
• 当检测到事件时，线程被唤醒，然后返回 FlgError::Ok 。
• 当线程阻塞等待被中断时，返回 FlgError::Interrupt 。
• 当到达指定的唤醒时间点时，线程被唤醒，并返回 FlgError::Timedout 。

事件的触发条件

事件的触发条件可通过参数 tg 设置。事件的触发条件分为两类。

电平触发

电平触发 源于数字电路，是一种类比概念，是指事件位图的特定状态（ 1 或 0 ）所产生的触发事件，包括：

• Trigger::SetAll 所有事件位被置 1 触发
• Trigger::SetAny 任意事件位被置 1 触发
• Trigger::ClearAll 所有事件位被清 0 触发
• Trigger::ClearAny 任意事件位被清 0 触发

电平触发 时，若参数 action 取值 Action::Consumption ，表示线程在读取事件位图后，会 清除 事件位图。 电平触发 时，参数 origin 用于返回事件发生时的位图状态。

边沿触发

边沿触发 源于数字电路，是一种类比概念，是指事件状态发生改变（ 1 变 0 或 0 变 1 ）时产生的唤醒信号，包括：

• Trigger::SetAll 所有事件位发生翻转触发
• Trigger::SetAny 任意事件位发生翻转触发

边沿触发 时，参数 action 没有作用，取值 Action::None 即可。 边沿触发 时，必须要有一个初始状态，就像数字电路一样：

• 当位的初始值为 0 (低电平)，然后跳变到 1 (高电平)的瞬间被称为上升沿。此时触发的事件被称为上升沿触发。
• 当位的初始值为 1 (高电平)，然后跳变到 0 (低电平)的瞬间被称为下降沿。此时触发的事件被称为下降沿触发。

初始值就由参数 origin 指明，触发后，事件位发生跳变，跳变后的结果还是由参数 origin 返回。

参数说明

• tg: 事件触发条件
• act: 事件触发后的动作
• origin: 事件位图
  • 电平触发 时，参数 origin 用于返回事件发生时的位图状态。
  • 初始值就由参数 origin 指明，触发后，事件位发生跳变，跳变后的结果还是由参数 origin 返回。
• msk: 事件的位图掩码
• to: 期望唤醒的时间点

上下文

• 线程

错误码

• FlgError::Ok 没有错误
• FlgError::NotInit 事件标志没有初始化
• FlgError::Interrupt 等待被中断
• FlgError::Timedout 等待超时
• FlgError::NotThreadContext 不在线程上下文内

示例

extern crate alloc;
use alloc::sync::Arc;

use xwrust::xwos::sync::flg::*;

pub fn xwrust_example_flg() {
}

pub fn trywait( &self, tg: Trigger, act: Action, origin: &mut Bmp<N>, msk: &Bmp<N>, ) -> FlgError

检查事件

• 当检测到事件时，立即返回 FlgError::Ok 。
• 当没有检测到事件时，立即返回 FlgError::NoEvent 。

事件的触发条件

事件的触发条件可通过参数 tg 设置。事件的触发条件分为两类。

电平触发

电平触发 源于数字电路，是一种类比概念，是指事件位图的特定状态（ 1 或 0 ）所产生的触发事件，包括：

• Trigger::SetAll 所有事件位被置 1 触发
• Trigger::SetAny 任意事件位被置 1 触发
• Trigger::ClearAll 所有事件位被清 0 触发
• Trigger::ClearAny 任意事件位被清 0 触发

电平触发 时，若参数 action 取值 Action::Consumption ，表示线程在读取事件位图后，会 清除 事件位图。 电平触发 时，参数 origin 用于返回事件发生时的位图状态。

边沿触发

边沿触发 源于数字电路，是一种类比概念，是指事件状态发生改变（ 1 变 0 或 0 变 1 ）时产生的唤醒信号，包括：

• Trigger::SetAll 所有事件位发生翻转触发
• Trigger::SetAny 任意事件位发生翻转触发

边沿触发 时，参数 action 没有作用，取值 Action::None 即可。 边沿触发 时，必须要有一个初始状态，就像数字电路一样：

• 当位的初始值为 0 (低电平)，然后跳变到 1 (高电平)的瞬间被称为上升沿。此时触发的事件被称为上升沿触发。
• 当位的初始值为 1 (高电平)，然后跳变到 0 (低电平)的瞬间被称为下降沿。此时触发的事件被称为下降沿触发。

初始值就由参数 origin 指明，触发后，事件位发生跳变，跳变后的结果还是由参数 origin 返回。

参数说明

• tg: 事件触发条件
• act: 事件触发后的动作
• origin: 事件位图
  • 电平触发 时，参数 origin 用于返回事件发生时的位图状态。
  • 初始值就由参数 origin 指明，触发后，事件位发生跳变，跳变后的结果还是由参数 origin 返回。
• msk: 事件的位图掩码

上下文

• 任意

错误码

• FlgError::Ok 没有错误
• FlgError::NotInit 事件标志没有初始化
• FlgError::NoEvent 没有检测到事件

示例

extern crate alloc;
use alloc::sync::Arc;

use xwrust::xwos::sync::flg::*;

pub fn xwrust_example_flg() {
}

pub fn bind<'a, const M: XwSz>( &'a self, sel: &'a Sel<M>, pos: XwSq, ) -> Result<FlgSel<'a, N, M>, FlgError>

where [XwBmp; { _ }]: Sized,

绑定事件标志对象到信号选择器

• 事件标志绑定到信号选择器上时，采用 非独占 的方式进行绑定。
• 绑定成功，通过 Ok() 返回 FlgSel<'a, N, M> 。
• 如果位置已被其他 同步对象 以 独占 的方式占领，通过 Err() 返回 FlgError::SelPosBusy 。
• 当指定的位置超出范围（例如 Sel<M> 只有8个位置，用户偏偏要绑定到位置9 ），通过 Err() 返回 FlgError::OutOfSelPos 。
• 重复绑定，通过 Err() 返回 FlgError::AlreadyBound 。

FlgSel<'a, N, M> 中包含事件标志的绑定信息。 FlgSel<'a, N, M> 与 Flg<N> 与 Sel<M> 具有相同的生命周期约束 'a 。 FlgSel::selected() 可用来判断事件标志是否被选择。当 FlgSel<'a, N, M> drop() 时，会自动解绑。

参数说明

• sel: 信号选择器的引用
• pos: 位置

上下文

• 任意

错误码

• FlgError::OutOfSelPos 信号选择器的位置超出范围
• FlgError::AlreadyBound 事件标志已经绑定
• FlgError::SelPosBusy 信号选择器的位置被占用

示例

pub fn xwrust_example_sel() {
    // ...省略...
    let flg0 = Arc::new(Flg::new());
    flg0.init();
    let flg0sel = match flg0.bind(&sel, 0) {
        Ok(s) => { // 绑定成功，`s` 为 `FlgSel`
            s
        },
        Err(e) => { // 绑定失败，`e` 为 `SelError`
            return;
        }
    };
    // ...省略...
}

Trait Implementations

impl<const N: XwSz> Drop for Flg<N>

where [XwBmp; { _ }]: Sized,

fn drop(&mut self)

Executes the destructor for this type.

impl<const N: XwSz> Send for Flg<N>

where [XwBmp; { _ }]: Sized,

impl<const N: XwSz> Sync for Flg<N>

where [XwBmp; { _ }]: Sized,