@ carely/ flock (英语)
本地 macOS 和 Linux 上的 Bun 和 Node 24 的 crash- safe, fd- hold 咨询文件锁定 文件系统.
@bearly/flock 是一个小 flock(2) 有三项保证:
- 内核在最后描述符关闭后释放所有权,包括
当程序收到时
SIGKILL· ; - 仅限
EAGAIN编号 :EWOULDBLOCK(b) 其他系统调用 失败和错误; - 可选的诊断字节是完全写入和fsynced 之前的 获取的手柄被还原 .
持久路径名及其字节是诊断,而不是所有. 文件为
释放后有意保留,并可描述前主人。 使用
isFlockHeld() 以观察目前的所有权.
安装
从 npm 安装 。 源安装需要 Bun 或 有 TypeScript 剥取的节点 24.
bun add @bearly/flock
Bun用自己的东西 bun:ffi 适配器;节点使用预建的克菲 3.3.2适配器.
运行时间都无法装入另一个绑定值 。 Koffi 安装脚本不可信;
在支持的预建平台上不需要编译器 .
| 运行时间和平台 | 证据 |
|---|---|
| Bun, Linux 和 macOS 软件 | 现有土著合同套房 |
| 节点 24, Linux x64 | 已计量的承接FD和空难释放合同套间 |
| 节点24、Linux arm64和macOS x64/arm64 | 上游预建;我们没有测量 |
| 窗口 | 不支持 |
MacOS上的节点需要同一个合同套房在消费者通过之前通过
声明支持。 这个
合同仅限于本地文件系统。 网络文件系统可以执行
flock 和不同的语义 并不属于这个包的保证.
使用量
import { tryAcquireFlock } from "@bearly/flock"
using lock = tryAcquireFlock("/tmp/my-app/writer.lock", {
body: `${JSON.stringify({ pid: process.pid })}\n`,
})
if (lock === null) throw new Error("another writer owns the resource")
// The lock remains held until this scope closes its fd.
对于必须无限期地等待的同步关键部分:
import { acquireFlockBlocking } from "@bearly/flock"
using lock = acquireFlockBlocking("/tmp/my-app/migration.lock")
runMigration()
对于一个有限的同步等待, acquireFlockWithTimeout(path, timeoutMs, options?)
返回控点或 null 当约束到期时。 它使用一个描述符和
单调时间, 停止整个呼叫线 在尝试之间。 打电话的人
选择绑定;取消、路径政策和错误措辞保持不变.
现有 tryAcquireFlock() 仍然不等待就立即尝试.
描述式继承
lock.fd 是公开的,这样主管就可以将获得的描述符传递给
孩子们. release() 只关闭此手柄的描述符; 它从不调用
LOCK_UN,因为明确解锁也会释放一个仍然拥有的锁
通过继承的复制。 内核在上次后放弃所有权
打开文件描述的描述结束 .
lock.held 只报告此本地控件。 之后就变假了
lock.release() 即使继承的孩子仍然拥有一个复制品.
诊断字节
lock.replaceBody(body) 切换出, 写出每个字节, 和fsyncs 之前
回来。 如果截断、写入或同步失败,当地索赔即告终结
出现错误。 无视羊群的读者仍可以观察进取
短句/写出顺序;对于写作者来说,保证是完成或错误,
对解锁的读者来说不是原子的旧的或新的能见度.
发展
bun run test
# With Node 24 available:
bun run test:node
bun run typecheck
bun run build