Repository files navigation

This is a semaphore implementation for use withasync andawait. Theimplementation follows the traditional definition of a semaphore rather than thedefinition of an asynchronous semaphore seen in some js community examples.Where as the latter one generally allows every defined task to proceedimmediately and synchronizes at the end, async-sema allows only a selectednumber of tasks to proceed at once while the rest will remain waiting.

Async-sema manages the semaphore count as a list of tokens instead of a singlevariable containing the number of available resources. This enables aninteresting application of managing the actual resources with the semaphoreobject itself. To make it practical the constructor for Sema includes an optionfor providing an init function for the semaphore tokens. Use of a custom tokeninitializer is demonstrated inexamples/pooling.js.

Firstly, add the package to your project'sdependencies:

npm install --save async-sema

or

yarn add async-sema

Then start using it like shown in the following example. Check moreuse case exampleshere.

const{ Sema}=require('async-sema');consts=newSema(4,// Allow 4 concurrent async calls{capacity:100// Prealloc space for 100 tokens});asyncfunctionfetchData(x){awaits.acquire()try{console.log(s.nrWaiting()+' calls to fetch are waiting')// ... do some async stuff with x}finally{s.release();}}constdata=awaitPromise.all(array.map(fetchData));

The package also offers a simple rate limiter utilizing the semaphoreimplementation.

const{ RateLimit}=require('async-sema');asyncfunctionf(){constlim=RateLimit(5);// rpsfor(leti=0;i<n;i++){awaitlim();// ... do something async}}

Creates a semaphore object. The first argument is mandatory and the secondargument is optional.

• nr The maximum number of callers allowed to acquire the semaphoreconcurrently.
• initFn Function that is used to initialize the tokens used to managethe semaphore. The default is() => '1'.
• pauseFn An optional fuction that is called to opportunistically requestpausing the the incoming stream of data, instead of piling up waitingpromises and possibly running out of memory.Seeexamples/pausing.js.
• resumeFn An optional function that is called when there is room againto accept new waiters on the semaphore. This function must be declaredif apauseFn is declared.
• capacity Sets the size of the preallocated waiting list inside thesemaphore. This is typically used by high performance where the developercan make a rough estimate of the number of concurrent users of a semaphore.

Drains the semaphore and returns all the initialized tokens in an array.Draining is an ideal way to ensure there are no pending async tasks, forexample before a process will terminate.

Returns the number of callers waiting on the semaphore, i.e. the number ofpending promises.

Attempt to acquire a token from the semaphore, if one is available immediately.Otherwise, returnundefined.

Acquire a token from the semaphore, thus decrement the number of availableexecution slots. IfinitFn is not used then the return value of the functioncan be discarded.

Release the semaphore, thus increment the number of free execution slots. IfinitFn is used then thetoken returned byacquire() should be given asan argument when calling this function.

Creates a rate limiter function that blocks with a promise whenever the ratelimit is hit and resolves the promise once the call rate is within the limitset byrps. The second argument is optional.

ThetimeUnit is an optional argument setting the width of the rate limitingwindow in milliseconds. The defaulttimeUnit is1000 ms, therefore makingtherps argument act as requests per second limit.

TheuniformDistribution argument enforces a discrete uniform distribution overtime, instead of the default that allows hitting the functionrps time andthen pausing fortimeWindow milliseconds. Setting theuniformDistributionoption is mainly useful in a situation where the flow of rate limit functioncalls is continuous and and occuring faster thantimeUnit (e.g. reading afile) and not enabling it would cause the maximum number of calls to resolveimmediately (thus exhaust the limit immediately) and therefore the next bunchcalls would need to wait fortimeWindow milliseconds. However if the flow issparse then this option may make thecode run slower with no advantages.

1. Fork this repository to your own GitHub account and thenclone it to your local device
2. Move into the directory of the clone:cd async-sema
3. Link it to the global module directory of Node.js:npm link

Inside the project where you want to test your clone of the package, you can now either usenpm link async-sema to link the clone to the local dependencies.

Olli Vanhoja (@OVanhoja)