xwrust::xwmd

Module xwcq

source
Expand description

§XWOS RUST：循环队列

XWOS RUST的 循环队列 是不依赖任何动态内存申请与释放的多线程间通讯机制。

循环队列有 N 个数据槽，每个数据槽的大小固定为 S 。 在创建循环队列时，需要指明类型常数 S 和 N，其内存完全在编译期进行分配。

发送时，可以将数据发送到队列后面（入队），也可以将数据发送到队列前面（插队）。 如果循环队列已满，不会阻塞发送者，循环队列会丢弃一份数据，腾出数据槽，再将新数据放入队列。

发送时，数据类型是泛型 T ，T 必须是 Sized 的，数据是被逐字节地被拷贝到循环队列的数据槽内的。 当发送的数据类型大小大于循环队列的数据槽大小 S ，发送会失败。

接收时，可以从循环队列的 首端 取出数据（首端离队），也可以从循环队列的 尾端 取出数据（尾端离队）。 还可以从循环队列的 首端 拷贝数据（首端拷贝），以及从循环队列的 尾端 拷贝数据（尾端拷贝）。

接收时，数据类型是泛型 T ， T 必须是 Sized 的，数据是被逐字节地从循环队列的数据槽中拷贝到出来的。 循环队列不会对接收时的 T 与 发送时的 T 进行检查，因此用户必须确保两个类型是一样的，或能安全地进行转换。

循环队列的 入队 与 首端离队 ，插队 与 尾端离队 分别组成了 先进先出(FIFO) 的关系。

由于不使用动态内存申请，又无法预测各个线程的生命周期，因此循环队列只能被定义为 static 限定的全局变量。

与 std::sync::mpsc 不同，循环队列不区分发送者与接收者，任何线程都可以发送与接收。

§创建

XWOS RUST的循环队列可使用 Xwcq::new() 创建。创建时需要指定两个常量参数：数据槽的大小 S 以及数量 N 。 循环队列只能创建为具有静态生命周期 static 约束的全局变量：

use xwrust::xwmd::xwcq::*;

static CQ: Xwcq<64, 16> = Xwcq::new(); // 数据槽大小 `S` = 64; 数量 `N` = 16

§初始化

使用前，必须调用 Xwcq::init() 对循环队列进行初始化。如果创建循环队列时的常量参数不合适，初始化将以错误码返回。

pub fn xwrust_example_xwcq() {
    let rc = CQ.init();
}

§发送

发送不会阻塞发送者，因此可在任意上下文进行发送。

§入队

入队 (EnQueue) Xwcq::eq 是指将数据发送到循环队列最后面。

§插队

插队 (Jump the Queue) Xwcq::jq 是指将数据发送到循环队列最前面。

§接收

§首端离队

首端离队是指从循环队列的 首端 取出数据。取出数据后，数据槽被释放。

  • Xwcq::dq() 若循环队列中为空，接收线程就阻塞等待，直到循环队列中有数据可取出或被中断。
  • Xwcq::dq_to() 若循环队列中为空，接收线程就限时阻塞等待，直到循环队列中有数据可取出或被中断或等待超时。
  • Xwcq::dq_unintr() 若循环队列中为空，接收线程就阻塞等待，直到循环队列中有数据可取出。阻塞等待不可被中断。
  • Xwcq::trydq() 若循环队列中为空，就立即返回，可在中断中使用。

§尾端离队

尾端离队是指从循环队列的 尾端 取出数据。取出数据后，数据槽被释放。

  • Xwcq::rq() 若循环队列中为空，接收线程就阻塞等待，直到循环队列中有数据可取出或被中断。
  • Xwcq::rq_to() 若循环队列中为空，接收线程就限时阻塞等待，直到循环队列中有数据可取出或被中断或等待超时。
  • Xwcq::rq_unintr() 若循环队列中为空，接收线程就阻塞等待，直到循环队列中有数据可取出。阻塞等待不可被中断。
  • Xwcq::tryrq() 若循环队列中为空，就立即返回，可在中断中使用。

§首端拷贝

从循环队列 首端 拷贝数据时，数据不会取走数据，数据槽不会被释放。因此命名为 前向窥视 (Peek at the Front of Queue) 。

  • Xwcq::pfq() 若循环队列中为空，接收线程就阻塞等待，直到循环队列中有数据可取出或被中断。
  • Xwcq::pfq_to() 若循环队列中为空，接收线程就限时阻塞等待，直到循环队列中有数据可取出或被中断或等待超时。
  • Xwcq::pfq_unintr() 若循环队列中为空，接收线程就阻塞等待，直到循环队列中有数据可取出。阻塞等待不可被中断。
  • Xwcq::trypfq() 若循环队列中为空，就立即返回，可在中断中使用。

§尾端拷贝

从循环队列 尾端 拷贝数据，数据不会取走数据，数据槽不会被释放。因此命名为 后向窥视 (Peek at the Rear of Queue) 。

  • Xwcq::prq() 若循环队列中为空，接收线程就阻塞等待，直到循环队列中有数据可取出或被中断。
  • Xwcq::prq_to() 若循环队列中为空，接收线程就限时阻塞等待，直到循环队列中有数据可取出或被中断或等待超时。
  • Xwcq::prq_unintr() 若循环队列中为空，接收线程就阻塞等待，直到循环队列中有数据可取出。阻塞等待不可被中断。
  • Xwcq::tryprq() 若循环队列中为空，就立即返回，可在中断中使用。

§清空循环队列

Xwcq::flush() 可将循环队列的所有数据槽清空。

§获取循环队列容量

Xwcq::capacity() 可获取循环队列的数据槽的数量 N 。

§获取循环队列数据槽的大小

Xwcq::size() 可获取循环队列数据槽的大小 S ，若 S 不满足内存对齐的要求，会自动向上调整。

§获取循环队列中有效数据槽的数量

Xwcq::availability() 可获取循环队列中有效数据槽的数量。有效数据槽是指包含了可被接收数据的数据槽。

§示例

XWOS/xwam/xwrust-example/xwrust_example_xwcq

Structs§

  • Xwcq
    循环队列对象结构体

Enums§

Constants§