Apache Asyncband 0.7.3 配置参数详解

asyncband 0.7.3 配置参数详解：Cargo feature 开关全表与依赖、同步原语构造参数、通道与池容量、PoolConfig 字段、MSRV 与运行时选择，全部实测验证。

Apache AsyncbandAsyncband2026/10/14

Apache Asyncband 0.7.3 配置参数详解

目标：把 Apache Asyncband 0.7.3 的"配置面"一次讲透——Cargo feature 能力开关全表及相互依赖、同步原语构造参数、通道与对象池容量参数、PoolConfig 结构字段、版本与兼容性参数、运行期运行时选择。所有结论均在 Ubuntu 22.04 与 CentOS 8（rustc/cargo 1.99.0，asyncband 0.7.3）实测验证，回显可复现。

一、Asyncband 的"配置"由三层构成

与常规软件的配置文件不同，asyncband 作为库没有 conf/ini 之类的配置载体，其行为配置分三层：

层载体决定什么
能力层Cargo feature 开关哪些原语模块进入编译产物（默认全部关闭）
参数层原语构造函数参数每个原语实例的容量、参与者数、初始值等
上下文层异步运行时与调用方任务调度、定时器、生命周期编排

能力层控制"编什么"，参数层控制"每个实例多大"，上下文层控制"谁来驱动"。三者解耦后，换运行时无需改原语代码，调容量无需改工程配置。

二、Cargo feature：能力开关层

2.1 查询 feature 清单

引导：cargo info 可查看 crate 的版本、许可证、MSRV 与全部 feature：

cargo info asyncband

回显（实测）：

asyncband #async #concurrency #synchronization #coordination #runtime-agnostic
Composable, runtime-agnostic concurrency building blocks for async Rust.
version: 0.7.3
license: Apache-2.0
rust-version: 1.86.0
documentation: https://docs.rs/asyncband
homepage: https://asyncband.apache.org
repository: https://github.com/apache/asyncband
crates.io: https://crates.io/crates/asyncband/0.7.3
features:
 +default      = []
  barrier      = []
  blocking     = []
  broadcast    = []
  completion   = []
  condvar      = [mutex]
  event        = []
  latch        = []
  lazy-cell    = [mutex]
  mpmc         = []
  mpsc         = []
  mutex        = []
  once         = [semaphore]
  once-cell    = [semaphore]
  once-map     = [dep:hashbrown, once-cell]
  oneshot      = []
  phaser       = []
  pool         = [semaphore]
  rwlock       = []
  semaphore    = []
  shutdown     = [latch, waitgroup]
  singleflight = [dep:hashbrown, once-cell]
  spmc         = []
  waitgroup    = []
  watch        = []

验证结果：default feature 为空集，即默认不启用任何 API；crate 要求 rust 1.86.0 及以上（rust-version 字段）。

2.2 全部 feature 与依赖关系

引导：feature 分为三类——纯开关（= []，无传递依赖）、级联开关（依赖其他 feature）、带外部依赖的开关（引入 hashbrown）。全表如下：

feature依赖启用后提供的 API
mutex无Mutex（异步互斥锁）
rwlock无RwLock（读写锁）
condvarmutexCondvar（条件变量）
semaphore无Semaphore（信号量）
barrier无Barrier（屏障）
event无ManualResetEvent / AutoResetEvent
latch无Latch（一次性倒计数）
phaser无Phaser（多阶段动态参与者同步）
waitgroup无WaitGroup（动态注册等待组）
shutdownlatch + waitgroupShutdown（优雅停机协调）
oncesemaphoreOnce（一次性异步初始化）
once-cellsemaphoreOnceCell（访问时初始化存储单元）
lazy-cellmutexLazyCell（惰性初始化单元）
once-maphashbrown + once-cellOnceMap（按 key 合并初始化）
singleflighthashbrown + once-cellGroup（按 key 合并重叠调用）
completion无Completion（一次发布、多观察者）
oneshot无oneshot 通道（单发单收）
mpmc无mpmc 通道（多生产多消费）
mpsc无mpsc 通道（多生产单消费，有界/无界）
spmc无spmc 通道（单生产多消费，有界/无界）
broadcast无broadcast 通道（多接收广播，有界/无界）
watch无watch 通道（最新状态发布）
poolsemaphorepool 对象池（有界/无界）
blocking无FutureExt（同步线程驱动单个 future）

2.3 feature 启用的实际效果

引导：cargo add 时用 --features 按需开启，未启用的模块不进编译产物，Cargo.toml 中对应 feature 数组即最终配置。实测组合（barrier + semaphore + mutex）：

cargo add asyncband --features barrier,semaphore,mutex

回显（实测，feature 段节选）：

      Adding asyncband v0.7.3 to dependencies
             Features:
             + barrier
             + mutex
             + semaphore
             - blocking
             - broadcast
             - completion
             - condvar
             - event
             - latch
             - lazy-cell
             - mpmc
             - mpsc
             - once
             - once-cell
             - once-map
             - oneshot
             - phaser
             - pool
             - rwlock
             - shutdown
             - singleflight
             - spmc
             - waitgroup
             - watch

验证结果：+ 前缀为本次启用的 3 个 feature，- 前缀为其余未启用项；Cargo.toml 生成 asyncband = { version = "0.7.3", features = ["barrier", "semaphore", "mutex"] }。若启用 condvar 而不写 mutex，cargo 会自动补齐级联依赖（condvar = [mutex]）。

三、同步原语构造参数

引导：每个原语实例的"容量类参数"在构造时传入，Rust 中构造即配置。以下签名均摘自 asyncband 0.7.3 源码并实测运行。

3.1 Semaphore：许可总数

use asyncband::semaphore::Semaphore;

let sem = Semaphore::new(2);       // 并发上限：2 个许可
let permit = sem.acquire(1).await; // 获取 1 个许可，可同时获取多个
sem.release(1);                    // 归还许可
  • new(permits: usize)：逻辑许可总数，即最大并发在途任务数。
  • acquire(permits: usize)：异步获取，许可不足时挂起等待。
  • try_acquire / acquire_owned：非阻塞尝试 / Arc 所有权获取。
  • available_permits()：当前可用许可数（实测 8 任务竞争 2 许可、全部归还后回显 available permits = 2）。

3.2 Barrier：参与者数量

use asyncband::barrier::Barrier;

let barrier = Barrier::new(4);         // 4 个参与者齐至后放行
let result = barrier.wait().await;     // 每代恰一个 is_leader() 为 true
  • new(n: u32)：每代参与者数，传 0 与传 1 等价（立即完成一代）。
  • wait()：阻塞到第 n 个参与者到达，返回值 BarrierWaitResult::is_leader() 标识本代 leader（实测 4 人中恰 1 人 leader=true）。

3.3 Mutex 与 RwLock：初始值与访问策略

use asyncband::mutex::Mutex;
use asyncband::rwlock::RwLock;

let counter = Mutex::new(0u32);        // 初始值 0
let mut guard = counter.lock().await;  // 独占写
let lock = RwLock::new(0u32);          // 读写锁，初始值 0
  • Mutex::new(t)：唯一参数为被保护数据的初始值；lock() 异步加锁，lock_owned() 供 Arc 所有权场景。
  • RwLock::new(t)：多读者或单写者；读多写少场景比 Mutex 并发度高。
  • 实测：8 个任务经 Mutex 保护并发自增，终值精确为 8，无丢失更新。

3.4 Latch 与 WaitGroup：倒计数与动态注册

use asyncband::latch::Latch;
use asyncband::waitgroup::WaitGroup;

let latch = Latch::new(3);     // 固定倒计数 3，到 0 后放行所有等待者
let group = WaitGroup::new();  // 动态注册，容量参数为 0（注册时才加）
  • Latch::new(count: u32)：一次性向下计数，countdown 到 0 后 wait 立即返回，不可复用。
  • WaitGroup::new()：无需初始容量，参与者动态注册/完成，适合任务数未知的场景。

3.5 事件类：信号保留模式

use asyncband::event::{AutoResetEvent, ManualResetEvent};

let auto = AutoResetEvent::new();     // 每次只放行一个等待者
let manual = ManualResetEvent::new(); // 放行当前与未来所有等待者，直到显式 reset
  • 两者均无构造参数；差异在信号保留策略：AutoResetEvent 一个信号释放一个等待者，ManualResetEvent 保持信号直到 reset()。

四、通道与对象池参数

4.1 mpsc / broadcast：缓冲区容量

use asyncband::mpsc;
use asyncband::broadcast;

let (tx, rx) = mpsc::bounded::<u32>(16);   // 有界队列：缓冲区 16，满则发送方等待
let (tx, rx) = mpsc::unbounded::<u32>();   // 无界队列：无容量参数
let (tx, rx) = broadcast::bounded::<u32>(64); // 广播：容量 64，落后接收方丢失旧值
  • mpsc::bounded<T>(buffer: usize)：有界背压通道，buffer 即配置参数，控制生产者的最大积压。
  • mpsc::unbounded<T>() / broadcast::unbounded<T>()：无界变体无容量参数。
  • broadcast::bounded<T>(capacity)：capacity 决定接收方可回放的最近消息窗口。

4.2 oneshot：单发通道

use asyncband::oneshot;

let (tx, rx) = oneshot::channel::<String>(); // 一次发送一个值、一个接收者
  • 无容量参数（语义上容量为 1）；send 后接收方取走即通道关闭。

4.3 对象池：PoolConfig 与容量字段

引导：pool 的"配置"集中在 PoolConfig 结构体，字段实测如下：

use asyncband::pool::{Pool, PoolConfig, QueueStrategy};

let config = PoolConfig::new(8)                  // 最大容量 max_size = 8
    .with_queue_strategy(QueueStrategy::Fifo)    // 出队顺序：先进先出
    .with_recycle_cancelled_strategy(RecycleCancelledStrategy::Detach);
let pool = Pool::new(config, manager);           // manager 实现 ManageObject 特征

PoolConfig 全部字段（asyncband 0.7.3 源码）：

字段类型说明
max_sizeusize池最大对象数，必须大于 0，否则 Pool::new 直接 panic
queue_strategyQueueStrategy对象排队策略，决定借出/归还顺序
recycle_cancelled_strategyRecycleCancelledStrategy回收被取消时的处理策略
  • 构造采用 builder 链：PoolConfig::new(max_size) 起步，with_queue_strategy / with_recycle_cancelled_strategy 追加。
  • 有界池另提供 Bounded::new(max_size: usize) 简写；无界池 Unbounded::new() 无容量参数。
  • 运行期可用 Pool::status() 读取 PoolStatus（max_size / current_size / idle_count）监控池水位。

五、版本与兼容性参数

5.1 rust-version / MSRV

引导：asyncband 0.7.3 声明 rust-version: 1.86.0（cargo info 实测回显），即最低支持版本。低于 1.86 的 rustc 无法编译；cargo add 时若本地 stable 更高则按最高兼容版本解析：

rustc --version && cargo tree

回显（实测）：

rustc 1.99.0 (b940084d7 2026-09-28)
asyncband-demo v0.1.0 (/root/asyncband-demo)
├── asyncband v0.7.3
└── tokio v1.53.2

验证结果：本地 rustc 1.99.0 高于 MSRV；依赖树中 asyncband 为叶子节点（零传递依赖），tokio 1.53.2 为唯一运行时依赖。

5.2 edition 与依赖锁定

引导：crate 使用 edition 2024（Cargo.toml 实测 edition = "2024"），要求较新的 cargo；工程侧依赖由 Cargo.lock 锁定精确版本：

grep -A1 'name = "asyncband"' Cargo.lock

回显（实测）：

name = "asyncband"
version = "0.7.3"

验证结果：Cargo.lock 固化 asyncband 0.7.3 与 tokio 1.53.2，保证可复现构建；升级版本用 cargo update -p asyncband。

六、运行期上下文：异步运行时选择

引导：asyncband 不 spawn 任务、不持有线程、不装定时器，只提供可 poll 的 future，因此"运行时"是调用方的自由参数。实测选用 tokio 多线程运行时：

tokio = { version = "1.53.2", features = ["macros", "rt-multi-thread"] }

#[tokio::main]
async fn main() {
    // asyncband 原语在此驱动
}

💡 技术拓展：异步运行时生态对比。Tokio 是事实标准的多线程运行时，功能最全（rt-multi-thread 提供工作线程池、macros 提供 #[tokio::main] 入口），生态最大但依赖最重；async-std 提供与标准库同名的 API 面，上手直观；smol 是极简派（约 40 个公开 API，依赖少、编译快）。三者都能 poll asyncband 的 future，因为 asyncband 只依赖标准 future/waker。切换运行时只需改 Cargo.toml 依赖与入口宏，原语代码零改动——这是 runtime-agnostic 设计的直接收益。若调用方完全同步（如纯 CLI 工具），还可启用 blocking feature，用 FutureExt::block_on 在同步线程驱动单个 future，无需任何运行时。

验证结果：demo 在 tokio 1.53.2 上运行三场景全部通过（信号量恢复、屏障 leader、计数精确），证明"原语与运行时解耦"成立。

七、参考链接

  1. Apache Asyncband 官方站点：https://asyncband.apache.org
  2. crates.io 上的 asyncband：https://crates.io/crates/asyncband
  3. docs.rs 文档（API map）：https://docs.rs/asyncband
  4. GitHub 源码仓库：https://github.com/apache/asyncband
  5. Rust 官方 cargo features 文档：https://doc.rust-lang.org/cargo/reference/features.html
  6. Tokio 官方文档：https://tokio.rs