Struct Sem

pub struct Sem { /* private fields */ }

信号量对象结构体

Implementations

impl Sem

pub const fn new() -> Self

新建信号量对象

此方法是编译期方法。

示例

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

use xwrust::xwos::sync::sem::*;

static GLOBAL_SEM: Sem  = Sem::new();

• 在heap中创建：

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

pub fn xwrust_example_sem() {
    let sem = Arc::new(Sem::new());
}

pub fn init(&self, val: XwSsq, max: XwSsq)

初始化信号量对象

信号量对象必须调用此方法一次，方可正常使用。

参数说明

• val: 初始值
• max: 最大值

上下文

• 任意

示例

use xwrust::types::*;
use xwrust::xwos::sync::sem::*;

static GLOBAL_SEM: Sem = Sem::new();

pub fn xwrust_example_sem() {
    // ...省略...
    GLOBAL_SEM.init(0, XwSsq::max);
    // 从此处开始 GLOBAL_SEM 可正常使用
}

pub fn freeze(&self) -> SemError

冻结信号量

信号量被冻结后，可被线程等待，但被能被单播 Sem::post() 。

上下文

• 任意

错误码

• SemError::Ok 没有错误
• SemError::NotInit 信号量没有初始化
• SemError::AlreadyFrozen 信号量已被冻结

示例

use xwrust::types::*;
use xwrust::errno::*;
use xwrust::xwos::sync::sem::*;

pub fn xwrust_example_sem() {
    // ...省略...
    let sem: Sem = Sem::new();
    sem.init(0, XwSsq::max);
    sem.freeze();
}

pub fn thaw(&self) -> SemError

解冻信号量

被冻结的信号量解冻后，可被单播 Sem::post() 。

上下文

• 任意

错误码

• SemError::Ok 没有错误
• SemError::NotInit 信号量没有初始化
• SemError::AlreadyThawed 信号量已解冻

示例

use xwrust::types::*;
use xwrust::errno::*;
use xwrust::xwos::sync::sem::*;

pub fn xwrust_example_sem() {
    // ...省略...
    let sem: Sem = Sem::new();
    sem.init(0, XwSsq::max);
    sem.freeze(); // 冻结
    // ...省略...
    sem.thaw(); // 解冻
}

pub fn post(&self) -> SemError

发布信号量

上下文

• 任意

错误码

• SemError::Ok 没有错误
• SemError::NotInit 信号量没有初始化
• SemError::AlreadyFrozen 信号量已被冻结

示例

use xwrust::types::*;
use xwrust::errno::*;
use xwrust::xwos::sync::sem::*;

pub fn xwrust_example_sem() {
    // ...省略...
    let sem: Sem = Sem::new();
    sem.init(0, XwSsq::max);
    // ...省略...
    sem.post();
}

pub fn get_max(&self) -> Result<XwSsq, SemError>

获取信号量对象计数器的最大值

成功将在 Ok() 中返回信号量对象计数器的值。

错误码

• Err(SemError::NotInit) 信号量没有初始化

示例

use xwrust::types::*;
use xwrust::errno::*;
use xwrust::xwos::sync::sem::*;

pub fn xwrust_example_sem() {
    // ...省略...
    let sem: Sem = Sem::new();
    sem.init(0, XwSsq::MAX);
    // ...省略...
    let res = sem.get_max();
    match res {
        Ok(max) => {
            // 返回信号量的值
        },
        Err(e) => {
            // 返回错误码
        },
    };
}

pub fn get_value(&self) -> Result<XwSsq, SemError>

获取信号量对象计数器的值

成功将在 Ok() 中返回信号量对象计数器的值。

错误码

• Err(SemError::NotInit) 信号量没有初始化

示例

use xwrust::types::*;
use xwrust::errno::*;
use xwrust::xwos::sync::sem::*;

pub fn xwrust_example_sem() {
    // ...省略...
    let sem: Sem = Sem::new();
    sem.init(0, XwSsq::MAX);
    // ...省略...
    let res = sem.get_value();
    match res {
        Ok(val) => {
            // 返回信号量的值
        },
        Err(e) => {
            // 返回错误码
        },
    };
}

pub fn wait(&self) -> SemError

等待并获取信号量

• 若信号量的值小于等于0，线程会阻塞等待。
• 当信号量的值大于0时，线程被唤醒，并取走一个值（信号量的值减少1），然后返回 SemError::Ok 。
• 当线程阻塞等待被中断时，返回 SemError::Interrupt 。

上下文

• 线程

错误码

• SemError::Ok 没有错误
• SemError::NotInit 信号量没有初始化
• SemError::Interrupt 等待被中断
• SemError::NotThreadContext 不在线程上下文内
• SemError::DisPmpt 抢占被关闭
• SemError::DisBh 中断底半部被关闭
• SemError::DisIrq 中断被关闭

示例

use xwrust::types::*;
use xwrust::xwos::sync::sem::*;

pub fn xwrust_example_sem() {
    // ...省略...
    let sem: Sem = Sem::new();
    sem.init(0, XwSsq::max);
    // ...省略...
    let rc = sem.wait();
    match rc {
        SemError::Ok => {
            // 获取信号量
        },
        _ => {
            // 等待信号量失败
        },
    };
}

pub fn wait_to(&self, to: XwTm) -> SemError

限时等待并获取信号量

• 若信号量的值小于等于0，线程会阻塞等待，等待时会指定一个唤醒时间点。
• 当信号量的值大于0时，线程被唤醒，并取走一个值（信号量的值减少1），然后返回 SemError::Ok 。
• 当线程阻塞等待被中断时，返回 SemError::Interrupt 。
• 当到达指定的唤醒时间点，线程被唤醒，并返回 SemError::Timedout 。
• 如果 to 是过去的时间点，将直接返回 SemError::Timedout 。

参数说明

• to: 期望唤醒的时间点

上下文

• 线程

错误码

• SemError::Ok 没有错误
• SemError::NotInit 信号量没有初始化
• SemError::Interrupt 等待被中断
• SemError::Timedout 等待超时
• SemError::NotThreadContext 不在线程上下文内
• SemError::DisPmpt 抢占被关闭
• SemError::DisBh 中断底半部被关闭
• SemError::DisIrq 中断被关闭

示例

use xwrust::types::*;
use xwrust::errno::*;
use xwrust::xwos::sync::sem::*;

pub fn xwrust_example_sem() {
    // ...省略...
    let sem: Sem = Sem::new();
    sem.init(0, XwSsq::max);
    // ...省略...
    let rc = sem.wait_to(xwtm::ft(xwtm::s(1))); // 最多等待1s
    match rc {
        SemError::Ok => {
            // 获取信号量
        },
        _ => {
            // 等待信号量失败
        },
    };
}

pub fn wait_unintr(&self) -> SemError

等待并获取信号量，且等待不可被中断

• 若信号量的值小于等于0，线程会阻塞等待，且不可被中断，也不会超时。
• 当信号量的值大于0时，线程被唤醒，并取走一个值（信号量的值减少1），然后返回 SemError::Ok 。

上下文

• 线程

错误码

• SemError::Ok 没有错误
• SemError::NotInit 信号量没有初始化
• SemError::NotThreadContext 不在线程上下文内
• SemError::DisPmpt 抢占被关闭
• SemError::DisBh 中断底半部被关闭
• SemError::DisIrq 中断被关闭

示例

use xwrust::types::*;
use xwrust::errno::*;
use xwrust::xwos::sync::sem::*;

pub fn xwrust_example_sem() {
    // ...省略...
    let sem: Sem = Sem::new();
    sem.init(0, XwSsq::max);
    // ...省略...
    let rc = sem.wait_unintr();
    match rc {
        SemError::Ok => {
            // 获取信号量
        },
        _ => {
            // 等待信号量失败
        },
    };
}

pub fn trywait(&self) -> SemError

尝试获取信号量

• 当信号量的值大于0时，就取走一个值（信号量的值减少1），然后返回 SemError::Ok 。
• 当信号量的值小于等于0时，立即返回 SemError::NoData 。

上下文

• 任意

错误码

• SemError::Ok 没有错误
• SemError::NotInit 信号量没有初始化
• SemError::NoData 信号量不可用

示例

use xwrust::types::*;
use xwrust::errno::*;
use xwrust::xwos::sync::sem::*;

pub fn xwrust_example_sem() {
    // ...省略...
    let sem: Sem = Sem::new();
    sem.init(0, XwSsq::max);
    // ...省略...
    let rc = sem.trywait();
    match rc {
        SemError::Ok => {
            // 获取信号量
        },
        _ => {
            // 等待信号量失败
        },
    };
}

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

where [XwBmp; { _ }]: Sized,

绑定信号量对象到信号选择器

• 信号量绑定到信号选择器上时， 独占 一个位置。
• 绑定成功，通过 Ok() 返回 SemSel<'a, M> 。
• 如果位置已被占领，通过 Err() 返回 SemError::SelPosBusy 。
• 当指定的位置超出范围（例如 Sel<M> 只有8个位置，用户偏偏要绑定到位置9 ），通过 Err() 返回 SemError::OutOfSelPos 。
• 重复绑定，通过 Err() 返回 SemError::AlreadyBound 。

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

参数说明

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

上下文

• 任意

错误码

• SemError::OutOfSelPos 信号选择器的位置超出范围
• SemError::AlreadyBound 信号量已经绑定
• SemError::SelPosBusy 信号选择器的位置被占用

示例

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

Trait Implementations

impl Drop for Sem

fn drop(&mut self)

Executes the destructor for this type.

impl Send for Sem

impl Sync for Sem