Add pooling, semaphores, latches, and mutexes

[aleclarson]

Pooling: Manages reusable objects to reduce creation/destruction overhead. Useful for expensive resources like database connections or complex data structures.

Semaphores: Limit concurrent asynchronous operations. Control simultaneous API calls or database queries to prevent resource exhaustion or rate limit breaches.

Latch: Coordinates multiple asynchronous operations, allowing you to wait until all are complete. Initializes with a count, decrements as operations finish, and resolves a promise when the count reaches zero.

Mutex: Ensures non-overlapping access to shared resources in asynchronous code. Implements critical sections for async operations, preventing interference when multiple async functions run concurrently.

These tools optimize resource management and control flow in JavaScript's asynchronous, event-driven environment.

We are currently taking suggestions on which popular NPM libraries to model our simple reimplementation on. Our goal is to mimic the API of a popular NPM library for each of these, so you can always upgrade to their more feature-rich implementations when/if you need it.

[aleclarson]

When creating this post, I had the wrong idea of what a semaphore is (I was really thinking of a latch, apparently). I believe #145 covers the use cases of a semaphore, though I could be wrong. If anyone has more familiarity, feel free to confirm or deny.

I suppose a semaphore API could look more like a class, rather than the currying style of bottleneck in #145. A good example of that is Shopify's semaphore package: @shopify/semaphore. They claim in their readme that a semaphore can be used for mutex behavior as well, so we may not need a separate mutex implementation.

[adamhamlin]

Re: latch -- What kind of functionality are you thinking about beyond what Promise.all or Promise.allSettled already provides, a la await Promise.allSettled(myPromises)?

[aleclarson]

Maybe a “dynamic” latch (where the count is not known beforehand) could be useful? For example, when scraping a web page, you may recursively scan linked pages, but you can't know if you'll find any until you do. To be fair, that's not the best example, since you'd probably want a purpose-built library for web scraping.

I agree that Promise.all and allSettled are good enough for known counts. I don't know of a use case where being able to pass around the latch would be necessary or substantially better, but that's the advantage I see over using Promise.all etc.

[hugo082]

Here is some related functions proposal. I would love to get your feedbacks in order to send PRs.

Proposal inspired from @shopify/semaphore, async-mutex & rust async_weighted_semaphore.

Let me know that are the next steps.

createSemaphore proposal

import * as _ from 'radashi'

const semaphore = _.createSemaphore(/* size: */ 2)

// available properties / methods
const release = await semaphore.acquire({ weight: 1, priority: 1 })
semaphore.isLocked()
release()

// ran one by one
await _.all([
	semaphore.exclusive(async () => /* ... */, { weight: 1, priority: 1 }),
	semaphore.exclusive(async () => /* ... */),
])

createMutex proposal

import * as _ from 'radashi'

// same as createSemaphore(1)
const mutex = _.createMutex()

exclusive proposal

import * as _ from 'radashi'

// create a mutex (semaphore = 1) around the function
const exclusiveFn = _.exclusive(async () => /* ... */)

// ran one by one
await _.all([
	exclusiveFn(),
	exclusiveFn()
])

[hugo082]

Ok I will take some time during the week to send a PR that implement withSemaphore, let's iterate on it 👍

[aleclarson]

Hey @hugo082! It's been about 12 days, so I'm checking in. Let me know your status so I can plan accordingly. Thanks! :)

[hugo082]

Hi @aleclarson! Sorry for the late update but here is the PR: #331 😄

[aleclarson]

Hey @hugo082, thanks for opening the PR! It's great to have your help. I wrote my own implementation for my own use, before you had opened #331, so I opened #335 for us to compare our approaches and come to consensus on what should be merged. Let me know what you think 👍

[hugo082]

Hey @aleclarson, I just checked your PR.
IMO it's a good thing to match the standard so users can quickly find the function & know that the function is doing.
Adding a manual management on acquire/release allows to deal with async locking mechanism - .e.g. the release comes from an event. I agree, it's more error prone but I don't think this is the responsibility of the lib to ensure the code quality.
About the getRunning it is always useful to be able to get this info for debugging, logging or whatever. I'm ok to add the hasCapacity, could be useful too.
Note that the withMutex is equivalent to withSemaphore({ capacity: 1 }, ...) but expose different usage interface isLocked/acquire/release