普贤教程 › 包参考

rate 包

令牌桶限流

项	值
包名	`rate`
版本	`0.2.0`
可用版本	`0.1.0 / 0.2.0`
入口	`rate.px`
分类	`并发与通用模式`
文件数 / 行数	`1 / 115`

安装与引入

bash

pxpkg init          # 首次
pxpkg add rate@0.2.0
pxpkg install

import rate

所属分类教程：并发与通用模式

公开接口

函数	参数
`rt_new`	`capacity, rate`
`rt_tokens`	`b, now`
`rt_allow`	`b, now`
`rt_allow_n`	`b, n, now`

其余 7 个 def（内部与辅助，可直接调用但不属稳定接口）

函数	参数
`rt_copy`	`b`
`rt_refill`	`b, now`
`rt_take_n`	`b, n, now`
`rt_wait_time`	`b, n, now`
`rt_reset`	`b`
`rt_stats`	`b, now`
`rt_allow_batch`	`b, count, now`

包内说明（源码头注释）

text

============================================================
普贤生态库：registry/rate —— 令牌桶限流
------------------------------------------------------------
纯函数库（无 IO、无状态），编译（px build）与解释（px run）双模式一致。
rt_new(capacity, rate)            → dict   新建满桶
rt_allow(bucket, now)             → [新桶, bool]     消耗 1 令牌（不足拒绝）
rt_allow_n(bucket, n, now)        → [新桶, bool]     消耗 n 令牌
rt_tokens(bucket, now)            → [新桶, int]      当前令牌数（先补满到 now）
状态表示：dict {cap:int, rate:int(每秒令牌数), tokens:int, last:int(秒时间戳)}
语义：
- 令牌按 (now - last) * rate 补给，上限 cap（初始满桶，允许突发）
- now 为 Unix 秒（可用 now_sec()）；tokens 以整数记（子集）
- 纯函数：所有操作返回新桶状态，不改传入 dict（写库规范：顶层无状态）
- 并发场景由调用方持有桶状态（chan + mutex 需编译模式，见 PX-DEF-006）
============================================================
新建满桶