@@ -17,6 +17,7 @@ import { dual, identity } from "./Function.ts"
1717import * as core from "./internal/core.ts"
1818import * as internal from "./internal/effect.ts"
1919import type * as Option from "./Option.ts"
20+ import type * as Scope from "./Scope.ts"
2021
2122/**
2223 * A counting semaphore that coordinates concurrent access with permits.
@@ -134,6 +135,24 @@ export interface Semaphore {
134135 */
135136 take ( this : Semaphore , permits : number ) : Effect . Effect < number >
136137
138+ /**
139+ * Acquires the specified number of permits for the lifetime of the current
140+ * scope, suspending the task if they are not yet available.
141+ *
142+ * **When to use**
143+ *
144+ * Use to hold permits until a scope closes, such as while a scoped resource
145+ * is leased.
146+ *
147+ * **Details**
148+ *
149+ * Waiting can be interrupted unless the caller is uninterruptible. The
150+ * permits are taken and their release is added to the scope in one
151+ * uninterruptible step, so acquired permits are always returned when the
152+ * scope closes.
153+ */
154+ takeScoped ( this : Semaphore , permits : number ) : Effect . Effect < void , never , Scope . Scope >
155+
137156 /**
138157 * Acquires the specified number of permits only if they are immediately
139158 * available.
@@ -281,6 +300,21 @@ class SemaphoreImpl implements Semaphore {
281300 return takePermits ( this , n , ( ) => internal . succeed ( n ) )
282301 }
283302
303+ takeScoped ( n : number ) : Effect . Effect < void , never , Scope . Scope > {
304+ return internal . uninterruptibleMask ( ( restore ) =>
305+ internal . flatMap ( internal . scope , ( scope ) => {
306+ const acquire : Effect . Effect < void > = internal . suspend ( ( ) => {
307+ if ( this . free < n ) {
308+ return internal . flatMap ( restore ( waitForPermits ( this , n , internal . void ) ) , ( ) => acquire )
309+ }
310+ this . taken += n
311+ return internal . scopeAddFinalizer ( scope , this . release ( n ) )
312+ } )
313+ return acquire
314+ } )
315+ )
316+ }
317+
284318 takeIfAvailable ( n : number ) : Effect . Effect < boolean > {
285319 return internal . suspend ( ( ) => {
286320 if ( this . free < n ) return internal . succeed ( false )
@@ -539,6 +573,47 @@ export const take: {
539573 ( self : Semaphore , permits : number ) : Effect . Effect < number >
540574} = dual ( 2 , ( self : Semaphore , permits : number ) => self . take ( permits ) )
541575
576+ /**
577+ * Acquires the specified number of permits until the current scope closes.
578+ *
579+ * **When to use**
580+ *
581+ * Use when permits should be held for the lifetime of a scope, such as while a
582+ * scoped resource is leased.
583+ *
584+ * **Details**
585+ *
586+ * The effect waits until enough permits are available. The wait can be
587+ * interrupted unless the caller is uninterruptible. The permits are taken and
588+ * their release is added to the scope in one uninterruptible step, so acquired
589+ * permits are always returned when the scope closes.
590+ *
591+ * **Example** (Holding a permit for a scope)
592+ *
593+ * ```ts import.meta.vitest
594+ * import { Effect, Semaphore } from "effect"
595+ *
596+ * const program = Effect.gen(function*() {
597+ * const semaphore = yield* Semaphore.make(1)
598+ * yield* Effect.scoped(Semaphore.takeScoped(semaphore, 1))
599+ * return yield* Semaphore.takeIfAvailable(semaphore, 1)
600+ * })
601+ *
602+ * Effect.runSync(program) // => true
603+ * ```
604+ *
605+ * @see {@link take } for acquiring permits that are released manually
606+ * @see {@link withPermits } for holding permits while one effect runs
607+ *
608+ * @stability stable
609+ * @category combinators
610+ * @since 4.0.7
611+ */
612+ export const takeScoped : {
613+ ( permits : number ) : ( self : Semaphore ) => Effect . Effect < void , never , Scope . Scope >
614+ ( self : Semaphore , permits : number ) : Effect . Effect < void , never , Scope . Scope >
615+ } = dual ( 2 , ( self : Semaphore , permits : number ) => self . takeScoped ( permits ) )
616+
542617/**
543618 * Acquires the specified number of permits only if they are immediately
544619 * available.
0 commit comments