{"_id":"@alsadi/semaphore","name":"@alsadi/semaphore","dist-tags":{"latest":"0.0.1"},"versions":{"0.0.1":{"name":"@alsadi/semaphore","version":"0.0.1","private":false,"author":{"name":"alsadi@gmail.com"},"license":"Apache-2.0","type":"module","repository":{"type":"git","url":"git+https://github.com/muayyad-alsadi/es-semaphore.git"},"keywords":["async","ipc"],"bugs":{"url":"https://github.com/muayyad-alsadi/es-semaphore/issues"},"homepage":"https://github.com/muayyad-alsadi/es-semaphore#readme","gitHead":"88861bc34945736edf5a81af221ed026d4ce3698","description":"## Background","_id":"@alsadi/semaphore@0.0.1","_nodeVersion":"16.18.1","_npmVersion":"8.19.2","dist":{"integrity":"sha512-A9YffXSNTDzeycBfqGOcrRGMvW+stl9RC1J336b8UkzFjBwC7VU7YlJoVdDiUrvyam8vasMo8Hb9HTQ73AMkEg==","shasum":"882ebc9929d49c78475ec23b9eeaaf546228054d","tarball":"https://registry.npmjs.org/@alsadi/semaphore/-/semaphore-0.0.1.tgz","fileCount":7,"unpackedSize":20488,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQCf/cF2lGz6Gh4WkywEJvNkx6KAzrASLalV8/06AelqMQIhAIPvOZL7f8WZIF2wHwtKVMxp/stX3SlEPyK7QUvzwL/Y"}],"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v4.10.10\r\nComment: https://openpgpjs.org\r\n\r\nwsFzBAEBCAAGBQJj7KQiACEJED1NWxICdlZqFiEECWMYAoorWMhJKdjhPU1b\r\nEgJ2Vmq1GxAAi/W/3ceQKG/jcJz/jAkkuTRcO3T2jjr/MdBHACVZje7dDHx0\r\nvvSvIYml334lq5RSp7D8AKvlOnQjqx/32LhfQvr0Xi9P1xEizZ55EJ6tC5Bv\r\nvvc0VASOXcxzk0j5uMAyGgaTuW0cJtw3yhZmBms1mWGySWyANWIkmArHZ0dS\r\nHGDuwu0MgblIL0P3gcC+EsP0KmNA+Uks+OT/7h+z8KX0Nbpkw+2W+vFhFxY/\r\n4crbiG4dYIfnVzDJ538oWgEk1Vz0IDmcArsn2T8F9AbItoCvdpfXpvX9ZpjT\r\nfEg7rXy1nGfoiNDnXrttmse6H21zbNEN9Yg1kwxcof3cduSG9uA9DBrsyh6J\r\nYFo2tqTOo+Un4f+tvdffg52E8ysfefqSzG6z7CQ68GQuL+AVB1MIiGJlMBuO\r\nqYnqzWBa/akwdHrSxXaP0e9hXnKb2g2TnbkDqCyiM6OX0OYtHRVApRnj5c6x\r\nz/2wBKtzC6jKsGZ7zoyC82pCAfThxgUItINy1ZtpeJUYr2qh59FXbldvGw4t\r\nyGoVtCoqiLSgE4q6sq12kB71OeLCS7dm0ac9OHlxs6/i9XP7qA/CHbXbAiLG\r\nZ9sFsUt9LXPRuYCO8jYWD0YXSvMVnodcMrKCNjDDRJQw5qYVc2qqC/X+JNkY\r\nPsq/gUDjoPAQIV6J4TPy48ij87dtoIIor3E=\r\n=N5/n\r\n-----END PGP SIGNATURE-----\r\n"},"_npmUser":{"name":"alsadi","email":"alsadi@gmail.com"},"directories":{},"maintainers":[{"name":"alsadi","email":"alsadi@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/semaphore_0.0.1_1676452898418_0.7511468364566658"},"_hasShrinkwrap":false}},"time":{"created":"2023-02-15T09:21:38.327Z","0.0.1":"2023-02-15T09:21:38.558Z","modified":"2023-02-15T09:21:38.750Z"},"maintainers":[{"name":"alsadi","email":"alsadi@gmail.com"}],"description":"## Background","homepage":"https://github.com/muayyad-alsadi/es-semaphore#readme","keywords":["async","ipc"],"repository":{"type":"git","url":"git+https://github.com/muayyad-alsadi/es-semaphore.git"},"author":{"name":"alsadi@gmail.com"},"bugs":{"url":"https://github.com/muayyad-alsadi/es-semaphore/issues"},"license":"Apache-2.0","readme":"# es-semaphore - Async Semaphore for ECMAScript / Node / Browser\n\n## Background\n\nAs [Semaphores](https://man7.org/linux/man-pages/man7/sem_overview.7.html) are important to coordinate threads.\nThis node module gives you a similar feature for your async tasks.\n\nA Semaphore indicates available resources to a given capacity.\nWhen this limit is reached, it will sleep until a resource is free.\n\nThink of it like a sound card with limited number of channels,\nlet's say 8 channels, in this case we have a semaphore of size 8,\nwhen a process acquire it, there will be 7 free resources available\nwhen another process acquire it, there will be 6 free resources available.\nWhen all resources are taken the trial to acquire it will sleep until it's available.\n\n# Usage\n\nIf you have an async generator or you have a producer that generates many tasks\nand you want a cheap way to limit how many pending tasks\n\n```javascript\nimport {SemaphorePromise} from \"@alsadi/semaphore\";\n// indicate that we can have 5 pending tasks\n// 5 resources can be allocated without sleep\nconst sem = new SemaphorePromise(5);\nasync function main() {\n    // ...\n    await sem.acquire(); // this will return directly or sleep until resource is available\n    const wrapped_promise=myasync_task().then(console.log).finally(()=>sem.release()); // when done a resource is available again\n    // ...\n}\n```\n\nyou can use `sem.with(...)` to do `acquire()` and `release()` automatically.\n`sem.with(...)` takes a function that returns the promise\n\n```javascript\nimport {SemaphorePromise} from \"@alsadi/semaphore\";\n// indicate that we can have 5 pending tasks\n// 5 resources can be allocated without sleep\nconst sem = new SemaphorePromise(5);\nasync function main() {\n    // ...\n    const wrapped_promise = sem.with(function(){\n        return myasync_task().then(console.log)\n    });\n    // ...\n}\n```\n\nYou can use this inside async generators\n\n\n```javascript\nasync function *mygen() {\n    while(something()) {\n        yield sem.with(function(){\n            return myasync_task().then(console.log)\n        });\n    }\n}\n```\n\n\n## Implementation\n\nThis implementation only uses an integer counter and a Promise with a callback\nOther than that it's zero cost. It does not have busy loops or arbtrary sleeps.\nThe size of the semaphore does not affect its cost.\n\n\n","readmeFilename":"README.md"}