proper-lockfile

What is proper-lockfile?

The proper-lockfile npm package is used to create and manage file locks, ensuring that only one process can access a file at a time. This is particularly useful for preventing race conditions and ensuring data integrity in concurrent environments.

What are proper-lockfile's main functionalities?

Locking a file

This feature allows you to lock a file to prevent other processes from accessing it. The code sample demonstrates how to lock a file, perform some operations, and then release the lock.

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

async function lockFile() {
  try {
    const release = await lockfile.lock('somefile');
    console.log('File is locked');
    // Do some work with the locked file
    await release();
    console.log('File is released');
  } catch (err) {
    console.error('Failed to lock file', err);
  }
}

lockFile();

Checking if a file is locked

This feature allows you to check if a file is currently locked. The code sample demonstrates how to check the lock status of a file.

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

async function checkLock() {
  try {
    const isLocked = await lockfile.check('somefile');
    console.log(`File is ${isLocked ? 'locked' : 'not locked'}`);
  } catch (err) {
    console.error('Failed to check lock status', err);
  }
}

checkLock();

Unlocking a file

This feature allows you to manually unlock a file. The code sample demonstrates how to unlock a file that was previously locked.

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

async function unlockFile() {
  try {
    await lockfile.unlock('somefile');
    console.log('File is unlocked');
  } catch (err) {
    console.error('Failed to unlock file', err);
  }
}

unlockFile();

Other packages similar to proper-lockfile

lockfile

The lockfile package provides similar functionality for file locking. It is simpler but less feature-rich compared to proper-lockfile. It allows you to create, check, and remove locks on files.

async-lock

The async-lock package provides a general-purpose locking mechanism for asynchronous code. While it is not specifically designed for file locking, it can be used to manage access to resources in a concurrent environment.

rwlockfile

The rwlockfile package provides read-write locks for files. It allows multiple readers or a single writer to access a file, offering more granular control compared to proper-lockfile.

README

proper-lockfile

A lockfile utility based on fs that works cross process and machine (network file systems).

Installation

$ npm install proper-lockfile --save

Design

There are various ways to achieve file locking.

This library utilizes the mkdir strategy which works atomically on any kind of file system, even network based ones. The lockfile path is based on the file path you are trying to lock by suffixing it with .lock.

When a lock is successfully acquired, the lockfile's mtime (modified time) is periodically updated to prevent staleness. This allows to effectively check if a lock is stale by checking its mtime against a stale threshold. If the update of the mtime fails several times, the lock might be compromised.

Comparison

This library is similar to lockfile but the later has some drawbacks:

• It relies on open with O_EXCL flag which has problems in network file systems. proper-lockfile uses mkdir which doesn't have this issue.

O_EXCL is broken on NFS file systems; programs which rely on it for performing locking tasks will contain a race condition.

• The lockfile staleness check is done via creation time, which is unsuitable for long running processes. proper-lockfile constantly updates lockfiles mtime to do proper staleness check.

• It does not check if the lockfile was compromised, which can led to undesirable situations. proper-lockfile checks the lockfile when updating the mtime.

Usage

.lock(file, [options], callback, [compromised])

Tries to acquire a lock on file.

If the lock succeeds, an unlock function is given that should be called when you want to release the lock.
If the lock get compromised, the provided compromised function will be called (optionally).

Available options:

• stale: Duration in milliseconds in which the lock is considered stale, defaults to 10000 (false to disable)
• update: The interval in which the lockfile's mtime will be updated, defaults to 5000
• retries: The number of retries or a retry options object, defaults to 0
• resolve: Resolve to a canonical path to handle relative paths & symlinks properly, defaults to true
• fs: A custom fs to use, defaults to graceful-fs

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

lockfile.lock('some/file', function (err, unlock) {
    if (err) {
        throw err;      // Lock failed
    }

    // Do something while the file is locked

    // Call the provided unlock function when you're done
    // Note that you can optionally handle unlock errors
    unlock(/* function (err) {
        if (err) {
            throw err;  // Unlock failed
        }

        // Lock is released
    }*/)
}, function (err) {
    // If we get here, the lock has been compromised
    // e.g.: the lock has been manually deleted
});

.remove(file, [options], callback)

Removes a lock.

You should NOT call this function to unlock a previously acquired lock. Use the provided unlock function as seen above.

This function is provided to simply remove the lock, but its unsafe. If something is owning the lock on file, it will get compromised.

Available options:

• resolve: Resolve to a canonical path to handle relative paths & symlinks properly, defaults to true
• fs: A custom fs to use, defaults to graceful-fs

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

lockfile.remove('some/file', function (err, unlock) {
    if (err) {
        throw err;  // Removal failed
    }
});

Tests

Simply run the test suite with $ npm test

The test suite is very extensive. We even have a stress test to guarantee exclusiveness of locks.

License

Released under the MIT License.