| 1 | # lockfile
|
| 2 |
|
| 3 | A very polite lock file utility, which endeavors to not litter, and to
|
| 4 | wait patiently for others.
|
| 5 |
|
| 6 | ## Usage
|
| 7 |
|
| 8 | ```javascript
|
| 9 | var lockFile = require('lockfile')
|
| 10 |
|
| 11 | // opts is optional, and defaults to {}
|
| 12 | lockFile.lock('some-file.lock', opts, function (er, fd) {
|
| 13 | // if the er happens, then it failed to acquire a lock.
|
| 14 | // if there was not an error, then the fd is opened in
|
| 15 | // wx mode. If you want to write something to it, go ahead.
|
| 16 |
|
| 17 | // do my stuff, free of interruptions
|
| 18 | // then, some time later, do:
|
| 19 | lockFile.unlock('some-file.lock', function (er) {
|
| 20 | // er means that an error happened, and is probably bad.
|
| 21 | })
|
| 22 | })
|
| 23 | ```
|
| 24 |
|
| 25 | ## Methods
|
| 26 |
|
| 27 | Sync methods return the value/throw the error, others don't. Standard
|
| 28 | node fs stuff.
|
| 29 |
|
| 30 | All known locks are removed when the process exits. Of course, it's
|
| 31 | possible for certain types of failures to cause this to fail, but a best
|
| 32 | effort is made to not be a litterbug.
|
| 33 |
|
| 34 | ### lockFile.lock(path, [opts], cb)
|
| 35 |
|
| 36 | Acquire a file lock on the specified path. Returns the FD.
|
| 37 |
|
| 38 | ### lockFile.lockSync(path, [opts])
|
| 39 |
|
| 40 | Acquire a file lock on the specified path
|
| 41 |
|
| 42 | ### lockFile.unlock(path, cb)
|
| 43 |
|
| 44 | Close and unlink the lockfile.
|
| 45 |
|
| 46 | ### lockFile.unlockSync(path)
|
| 47 |
|
| 48 | Close and unlink the lockfile.
|
| 49 |
|
| 50 | ### lockFile.check(path, [opts], cb)
|
| 51 |
|
| 52 | Check if the lockfile is locked and not stale.
|
| 53 |
|
| 54 | Returns boolean.
|
| 55 |
|
| 56 | ### lockFile.checkSync(path, [opts], cb)
|
| 57 |
|
| 58 | Check if the lockfile is locked and not stale.
|
| 59 |
|
| 60 | Callback is called with `cb(error, isLocked)`.
|
| 61 |
|
| 62 | ## Options
|
| 63 |
|
| 64 | ### opts.wait
|
| 65 |
|
| 66 | A number of milliseconds to wait for locks to expire before giving up.
|
| 67 | Only used by lockFile.lock. Relies on fs.watch. If the lock is not
|
| 68 | cleared by the time the wait expires, then it returns with the original
|
| 69 | error.
|
| 70 |
|
| 71 | ### opts.stale
|
| 72 |
|
| 73 | A number of milliseconds before locks are considered to have expired.
|
| 74 |
|
| 75 | ### opts.retries
|
| 76 |
|
| 77 | Used by lock and lockSync. Retry `n` number of times before giving up.
|
| 78 |
|
| 79 | ### opts.retryWait
|
| 80 |
|
| 81 | Used by lock. Wait `n` milliseconds before retrying.
|