Skip to content

Commit b2f95a9

Browse files
authored
Add Semaphore takeIfAvailable (#6793)
1 parent 98de280 commit b2f95a9

3 files changed

Lines changed: 78 additions & 0 deletions

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"effect": minor
3+
---
4+
5+
Add `Semaphore.takeIfAvailable` for non-blocking manual permit acquisition.

‎packages/effect/src/Semaphore.ts‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,16 @@ export interface Semaphore {
130130
*/
131131
take(this: Semaphore, permits: number): Effect.Effect<number>
132132

133+
/**
134+
* Acquires the specified number of permits only if they are immediately
135+
* available.
136+
*
137+
* **When to use**
138+
*
139+
* Use to manually acquire permits without waiting, paired with `release`.
140+
*/
141+
takeIfAvailable(this: Semaphore, permits: number): Effect.Effect<boolean>
142+
133143
/**
134144
* Releases the specified number of permits and returns the resulting
135145
* available permits.
@@ -226,6 +236,14 @@ class SemaphoreImpl implements Semaphore {
226236
return take
227237
}
228238

239+
takeIfAvailable(n: number): Effect.Effect<boolean> {
240+
return internal.suspend(() => {
241+
if (this.free < n) return internal.succeed(false)
242+
this.taken += n
243+
return internal.succeed(true)
244+
})
245+
}
246+
229247
updateTakenUnsafe(fiber: Fiber<any, any>, f: (n: number) => number): number {
230248
this.taken = f(this.taken)
231249
if (this.waiters.size > 0) {
@@ -458,6 +476,7 @@ export const withPermitsIfAvailable: {
458476
*
459477
* @see {@link withPermit} for automatically acquiring and releasing one permit around an effect
460478
* @see {@link withPermits} for automatically acquiring and releasing multiple permits around an effect
479+
* @see {@link takeIfAvailable} for manually acquiring permits without waiting
461480
* @see {@link release} for returning manually acquired permits
462481
*
463482
* @category combinators
@@ -468,6 +487,33 @@ export const take: {
468487
(self: Semaphore, permits: number): Effect.Effect<number>
469488
} = dual(2, (self: Semaphore, permits: number) => self.take(permits))
470489

490+
/**
491+
* Acquires the specified number of permits only if they are immediately
492+
* available.
493+
*
494+
* **When to use**
495+
*
496+
* Use when you need fail-fast manual permit acquisition for a lower-level
497+
* protocol with explicit acquisition and release control.
498+
*
499+
* **Details**
500+
*
501+
* If enough permits are available, they are acquired and the effect returns
502+
* `true`. Otherwise, the effect returns `false` immediately without acquiring
503+
* any permits.
504+
*
505+
* @see {@link take} for the variant that waits until permits are available
506+
* @see {@link release} for returning manually acquired permits
507+
* @see {@link withPermitsIfAvailable} for automatic acquisition and release around an effect
508+
*
509+
* @category combinators
510+
* @since 4.0.0
511+
*/
512+
export const takeIfAvailable: {
513+
(permits: number): (self: Semaphore) => Effect.Effect<boolean>
514+
(self: Semaphore, permits: number): Effect.Effect<boolean>
515+
} = dual(2, (self: Semaphore, permits: number) => self.takeIfAvailable(permits))
516+
471517
/**
472518
* Releases the specified number of permits and returns the resulting available
473519
* permits.

‎packages/effect/test/Semaphore.test.ts‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -332,6 +332,33 @@ describe("Semaphore", () => {
332332
assert.isTrue(acquired)
333333
}))
334334

335+
it.effect("takeIfAvailable acquires permits when they are available", () =>
336+
Effect.gen(function*() {
337+
const sem = yield* Semaphore.make(2)
338+
339+
const acquired = yield* Semaphore.takeIfAvailable(sem, 2)
340+
assert.isTrue(acquired)
341+
342+
const unavailable = yield* sem.takeIfAvailable(1)
343+
assert.isFalse(unavailable)
344+
345+
const released = yield* sem.release(2)
346+
assert.strictEqual(released, 2)
347+
}))
348+
349+
it.effect("takeIfAvailable returns immediately when permits are unavailable", () =>
350+
Effect.gen(function*() {
351+
const sem = yield* Semaphore.make(1)
352+
353+
yield* sem.take(1)
354+
355+
const acquired = yield* Semaphore.takeIfAvailable(1)(sem)
356+
assert.isFalse(acquired)
357+
358+
yield* sem.release(1)
359+
assert.isTrue(yield* sem.takeIfAvailable(1))
360+
}))
361+
335362
it.effect("module-level combinators delegate to the instance api", () =>
336363
Effect.gen(function*() {
337364
const sem = yield* Semaphore.make(1)

0 commit comments

Comments
 (0)