{"_id":"fifolock","_rev":"4-fe0c1ed98a9fded792dedcb59764f748","name":"fifolock","description":"Not-quite-barebones serial queue / lock.","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"fifolock","version":"1.0.0","description":"Not-quite-barebones serial queue / lock.","main":"index.js","scripts":{"test":"node test"},"repository":{"type":"git","url":"https://github.com/natevw/fifolock"},"keywords":["lock","queue"],"author":{"name":"Nathan Vander Wilt"},"license":"BSD-2-Clause","bugs":{"url":"https://github.com/natevw/fifolock/issues"},"homepage":"https://github.com/natevw/fifolock","_id":"fifolock@1.0.0","dist":{"shasum":"a37e54f3ebe69d13480d95a82abc42b7a5c1792d","tarball":"https://registry.npmjs.org/fifolock/-/fifolock-1.0.0.tgz","integrity":"sha512-CqipzmuW6+xm7emSaBx1rV/fX17UGF9HkzLH887cFOj/Pe3TJsrboGxjZZtzV/5JrQ5vMegQ7ipZkB9wvsBDDQ==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQDVtsz8mQWP+KTmZaEiM3QJ7UTEoWFS/E7E/kZ0eb9+uAIgN8CTtVDOK5EqoiQD8pTPoThhB5m4DiISbNZQwX5VCbA="}]},"_from":".","_npmVersion":"1.4.3","_npmUser":{"name":"natevw","email":"natevw@yahoo.com"},"maintainers":[{"name":"natevw","email":"natevw@yahoo.com"}]}},"readme":"# fifolock\n\nVery simple FIFO task runner (usable as a lock or serial queue), plus a callback-wrapping helper.\n\n\n## Installation\n\n`npm install fifolock`\n\n## Example\n\n\n```js\nvar q = require('fifolock')();\n\nq.acquire(function (release) {\n    setTimeout(function () {\n        console.log(\"This task started first.\");\n        release();\n    }, 1e3);\n});\n\nattemptSomething(function (e, d) {\n    if (e) console.warn(\"Attempt happened to fail.\", e);\n    else console.log(\"Attempt happened to succeed,\", d);\n});\n\nattemptSeveralSomethings(42, function (e) {\n    if (e) console.warn(\"Got the inevitable error.\", e);\n    else console.log(\"Wow, that was improbable…\");\n});\n\nq.acquire(function (done) {\n    console.log(\"This task was started last.\");\n    done();\n});\n\n\n// callers of q.TRANSACTION_WRAPPER wait to acquire the queue just like any direct users\nfunction attemptSomething(cb, _nested) { cb = q.TRANSACTION_WRAPPER(cb, function () {\n    if (Math.random() > 0.75) process.nextTick(function () {\n        cb(new Error(\"Chaos monkey struck!\"));\n    }); else setTimeout(function () {\n        cb(null, \"here's the data.\");\n    }, 0);\n    \n}, _nested); }\n\n// advanced trick: sharing a single acquisition with nested/nestable helper routines\nfunction attemptSeveralSomethings(n, cb) { cb = q.TRANSACTION_WRAPPER(cb, function () {\n    function recursiveAttempt(i) {\n        if (i < n) attemptSomething(function (e) {\n            if (e) cb(new Error(\"Only succeeded at \"+i+\" of \"+n+\" attempts\"));\n            else recursiveAttempt(i+1);\n        }, true);       // note how, unlike normal callers, we use our internal _nested parameter\n        else cb(null);\n    }\n    recursiveAttempt(0);\n}); }\n```\n\nThis code will output something like:\n\n> This task started first.\n> Attempt happened to succeed, here's the data.\n> Got the inevitable error. [Error: Only succeeded at 8 of 42 attempts]\n> This task was started last.\n\n\n## API\n\n* `var q = fifolock();` — the module exports a factory function, call it to get a queue instance\n* `q.acquire(task)` — enqueues `task` to start when all previously-queued tasks have finished (or in the next tick if `q` was empty). When it is started, `task` will receive one argument e.g. `(finish)` which is a function it *must* call to release the lock and allow any next task to proceed.\n* `cb = q.TRANSACTION_WRAPPER(cb, fn, [skipAcquisition])` — this method helps you ensure \"normal\" async logic happens in a consistent fashion. Before executing `fn` it waits to aquire a lock, but immediately returns a wrapper around `cb` which will forward the call while making sure the lock is properly released. The `skipAcquisition` argument is optional, intended to keep code that must work both within its own transactions, *and* under the auspices of another caller's already-acquired lock. (See example above.)\n* `var CUSTOM_WRAPPER = q.TRANSACTION_WRAPPER.bind({postAcquire:preFn, preRelease:postFn});` — the wrapper method also allows you to provide `postAcquire` and/or `preRelease` hooks to bracket a transaction with additional custom logic. The postAcquire hook `preFn(proceed)` should do any addition setup require and then must call `proceed`. Note that while the hook *must* proceed it could signal an error condition by passing custom arguments to `proceed`; these will be forwarded to the main function(s) which would then need to participate in any such failure-handling protocol. The preRelease hook `postFn(finish, [args, ctx])` should do any cleanup necessary and then *must* release the queue by calling `finish`. Note that the preRelease hook gets an array copy of the arguments which will be passed to the wrapped callback in case it affects cleanup, but cannot control what the callback receives. (See \"examples/custom_wrapper.js\" for a sample custom wrapper.)\n\n\n## License\n\n© 2014 Nathan Vander Wilt.\nFunding for this work was provided in part by Technical Machine, Inc.\n\nReuse under your choice of:\n\n* [BSD-2-Clause](http://opensource.org/licenses/BSD-2-Clause)\n* [Apache 2.0](http://www.apache.org/licenses/LICENSE-2.0.html)\n","maintainers":[{"name":"natevw","email":"natevw@yahoo.com"}],"time":{"modified":"2022-06-18T00:31:47.921Z","created":"2014-05-27T20:55:41.443Z","1.0.0":"2014-05-27T20:55:41.443Z"},"homepage":"https://github.com/natevw/fifolock","keywords":["lock","queue"],"repository":{"type":"git","url":"https://github.com/natevw/fifolock"},"author":{"name":"Nathan Vander Wilt"},"bugs":{"url":"https://github.com/natevw/fifolock/issues"},"license":"BSD-2-Clause","readmeFilename":"README.md"}