正确锁定文件

一个在本地或网络文件系统中工作的跨进程和跨机器锁文件工具.

安装

$ npm install proper-lockfile

设计

有多种方法可以实现 文件锁定。 。 。 .

这个图书馆使用 mkdir 任何类型的文件系统 甚至是基于网络的系统. 锁定文件路径基于您试图用后缀锁定的文件路径 .lock。 。 。 .

当锁被成功获取时, 锁文件是 mtime (修改后的时间)定期更新,以防止停滞. 这样可以有效检查锁是否通过检查其 mtime 与坚固的门槛相抗衡。 如果mtime的更新失败了好几次,锁可能会被损坏. 这个 mtime 实值 支持 几乎每笔 filesystem。 。 。 .

比较

这个图书馆类似于 锁定文件 但后者有一些缺点:

• 它依赖 open 与 O_EXCL 在网络文件系统中有问题的旗帜. proper-lockfile 用途 mkdir 它没有这个问题.

O EXCL在NFS文件系统中被打破;依靠它执行锁定任务的程序将包含一个种族条件.

• 锁文件 Staleness 检查是通过 ctime 不适合长期运行的过程. proper-lockfile 不断更新锁文件 mtime 来检查一下状况.

• 它不检查锁文件是否被泄露,从而可能导致不良情况. proper-lockfile 更新时检查锁定文件 mtime。 。 。 .

• 它的默认值为 0 因为任何崩溃或过程会杀死 包不能优雅地处理 就会永远离开锁.

妥协

proper-lockfile 未发现以下情况:

• A 类 lockfile 手动取出,其他人在紧接着获得锁
• 不同 stale编号 :update 同一文件使用的值, 可能导致在同一文件上获取两个锁定

proper-lockfile 检测下列情况:

• 更新 lockfile 失败
• 更新所需时间比预期的要长,可能使锁在一定时间内僵化

如所见前二由用相坏故. 从技术上讲,可以探测到前两种情况,但会引入复杂性和最终的种族条件.

使用量

.lock( 文件, [选项])

尝试获取锁定 file 或否认警告者.

如果锁成功,a release 函数提供在要释放锁时应当调用。 这个 release 函数还拒绝错误时的许诺(例如,当锁已经失密时).

可用的选项 :

• stale: 以毫秒计的持续时间,其中锁被视为已停用,默认为 10000 (最低值为 5000(中文(简体) )
• update: 以毫秒表示的锁文件间隔 mtime 将更新,默认为 stale/2 (最低值为 1000,最大值为 stale/2(中文(简体) )
• retries: 重复次数或次数 重试 选项对象,默认为 0
• realpath: 使用 realpath 解析相链接,默认为 true (注意如果 true,则 file 必须是先前存在的)
• fs: 要使用的自定义 fs, 默认为 graceful-fs
• onCompromised: 如果锁被损坏, 调用时默认为只丢出可能导致进程失效的错误的函数
• lockfilePath: 自定义锁文件路径 。 例如: 如果您想要锁定目录并创建其中的锁文件, 您可以通过 file 作为 <dir path> 财务报告和审定财务报表 options.lockfilePath 作为 <dir path>/dir.lock

const lockfile = require('proper-lockfile');

lockfile.lock('some/file')
.then((release) => {
    // Do something while the file is locked

    // Call the provided release function when you're done,
    // which will also return a promise
    return release();
})
.catch((e) => {
    // either lock could not be acquired
    // or releasing it failed
    console.error(e)
});

// Alternatively, you may use lockfile('some/file') directly.

.unlock(文件,[选项])

释放先前获得的锁定 file 或否认警告者.

尽可能使用 release 函数代替(如上所示)。 仍然有一些情况下,很难在代码周围保持引用. 在这种情况下 unlock() 可能比较方便.

可用的选项 :

• realpath: 使用 realpath 解析相链接,默认为 true (注意如果 true,则 file 必须是先前存在的)
• fs: 要使用的自定义 fs, 默认为 graceful-fs
• lockfilePath: 自定义锁文件路径 。 例如: 如果您想要锁定目录并创建其中的锁文件, 您可以通过 file 作为 <dir path> 财务报告和审定财务报表 options.lockfilePath 作为 <dir path>/dir.lock

const lockfile = require('proper-lockfile');

lockfile.lock('some/file')
.then(() => {
    // Do something while the file is locked

    // Later..
    return lockfile.unlock('some/file');
});

检查(文件,[选项])

检查文件是否被锁定且其锁文件不呆滞, 拒绝错误的保证 .

可用的选项 :

• stale: 以毫秒计的持续时间,其中锁被视为已停用,默认为 10000 (最低值为 5000(中文(简体) )
• realpath: 使用 realpath 解析相链接,默认为 true (注意如果 true,则 file 必须是先前存在的)
• fs: 要使用的自定义 fs, 默认为 graceful-fs
• lockfilePath: 自定义锁文件路径 。 例如: 如果您想要锁定目录并创建其中的锁文件, 您可以通过 file 作为 <dir path> 财务报告和审定财务报表 options.lockfilePath 作为 <dir path>/dir.lock

const lockfile = require('proper-lockfile');

lockfile.check('some/file')
.then((isLocked) => {
    // isLocked will be true if 'some/file' is locked, false otherwise
});

.lockSync(文件,[选项])

同步版本 .lock()。 。 。 .
返回 release 函数或投放出错.

. 解锁同步( 文件, [选项])

同步版本 .unlock()。 。 。 .
投出出错.

。checkSync(文件,[选项])

同步版本 .check()。 。 。 . 返回布尔或投出错误.

优雅的离开

proper-lockfile 如果进程退出,则自动去除锁,除非进程与SIGKILL一起被杀死,或者由于VM致命错误而崩溃(如:出自内存).

测试

$ npm test
$ npm test -- --watch 开发期间

测试套房非常广泛. 甚至有压力测试来保证锁的专属性.

许可证

释放 MIT 许可证。 。 。 .