TxSemaphore
Coordinates access to limited resources inside transactions.
A TxSemaphore has a fixed capacity and stores its available permit count in a TxRef. Acquiring or releasing permits can therefore commit atomically with other transactional state changes. This module includes operations for creating semaphores, checking capacity and availability, acquiring or releasing permits, and running effects while permits are held.
Combinators
Signature
declare function acquire(self: TxSemaphore): Effect<void>;Acquires the specified number of permits from the semaphore.
When to use
Use to manually acquire multiple permits transactionally, waiting until all requested permits are available.
Details
If fewer than n permits are available, the transaction retries until enough permits are released.
Gotchas
Passing a non-positive n dies with a defect. Passing a value greater than the semaphore capacity can wait forever because the capacity is fixed.
See
tryAcquireNfor a non-blocking multi-permit attemptreleaseNfor returning multiple permitswithPermitsfor automatic acquire and release around an effect
Signature
declare function acquireN(self: TxSemaphore, n: number): Effect<void>;Gets the current number of available permits in the semaphore.
When to use
Use to inspect how many permits are currently available.
See
capacityfor reading the fixed total permit count
Signature
declare function available(self: TxSemaphore): Effect<number>;Gets the maximum capacity (total permits) of the semaphore.
When to use
Use to inspect the fixed total number of permits managed by the semaphore.
See
availablefor reading the current available permit count
Signature
declare function capacity(self: TxSemaphore): Effect<number>;Releases one permit back to the semaphore, making it available for acquisition.
When to use
Use to manually return one permit after a transactional acquire.
Details
If the semaphore is already at capacity, this operation leaves the permit count unchanged.
See
Signature
declare function release(self: TxSemaphore): Effect<void>;Releases the specified number of permits back to the semaphore.
When to use
Use to manually return multiple permits after a transactional acquire.
Details
The available permit count is capped at the semaphore capacity.
Gotchas
Passing a non-positive n dies with a defect.
See
Signature
declare function releaseN(self: TxSemaphore, n: number): Effect<void>;tryAcquire
Tries to acquire a single permit from the semaphore without blocking, returning true if successful or false if no permits are available.
When to use
Use to attempt a single-permit acquisition without retrying when no permit is available.
See
acquirefor waiting until one permit is availabletryAcquireNfor attempting to acquire multiple permits without blocking
Signature
declare function tryAcquire(self: TxSemaphore): Effect<boolean>;tryAcquireN
Tries to acquire the specified number of permits from the semaphore without blocking, returning true if successful or false if not enough permits are available.
When to use
Use to attempt a multi-permit acquisition without retrying when not enough permits are available.
See
acquireNfor waiting until all requested permits are availabletryAcquirefor attempting to acquire one permit without blocking
Signature
declare function tryAcquireN(self: TxSemaphore, n: number): Effect<boolean>;withPermit
Executes an effect with a single permit from the semaphore. The permit is automatically acquired before execution and released afterwards, even if the effect fails or is interrupted.
When to use
Use to run an effect while automatically acquiring and releasing one transactional permit.
Details
The permit acquisition and release operations use atomic semantics to ensure proper resource management with Effect's scoped operations.
See
withPermitsfor automatically acquiring and releasing multiple permitswithPermitScopedfor acquiring one permit for the current scopeacquirefor manual single-permit acquisition
Signature
declare const withPermit: {
(self: TxSemaphore): <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, R>;
<A, E, R>(self: TxSemaphore, effect: Effect<A, E, R>): Effect<A, E, R>;
};withPermits
Runs an effect while holding the specified number of permits from the semaphore.
When to use
Use to run an effect while automatically acquiring and releasing multiple transactional permits.
Details
The permits are acquired before the effect starts and released after it completes, fails, or is interrupted.
Gotchas
Passing a non-positive n dies with a defect. Passing a value greater than the semaphore capacity can wait forever.
See
withPermitfor automatically acquiring and releasing one permitacquireNfor manual multi-permit acquisition
Signature
declare const withPermits: {
(self: TxSemaphore, n: number): <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, R>;
<A, E, R>(self: TxSemaphore, n: number, effect: Effect<A, E, R>): Effect<A, E, R>;
};withPermitScoped
Acquires a single permit from the semaphore in a scoped manner. The permit will be automatically released when the scope is closed, even if effects within the scope fail or are interrupted.
When to use
Use to acquire one transactional permit for the lifetime of the current scope.
Details
The permit acquisition and release operations use atomic semantics to ensure proper resource management with Effect's scoped operations.
See
withPermitfor acquiring one permit around a single effectacquirefor manual single-permit acquisition
Signature
declare function withPermitScoped(self: TxSemaphore): Effect<void, never, Scope>;Constructors
Creates a new TxSemaphore with the specified number of permits.
When to use
Use to create a transactional semaphore with a fixed permit capacity.
See
Signature
declare function make(permits: number): Effect<TxSemaphore>;Guards
isTxSemaphore
Determines if the provided value is a TxSemaphore.
When to use
Use to narrow an unknown value before treating it as a TxSemaphore.
See
makefor creating aTxSemaphore
Signature
declare function isTxSemaphore(u: unknown): u is TxSemaphore;Models
TxSemaphore interface
A transactional semaphore that manages permits using Software Transactional Memory (STM) semantics, providing atomic permit acquisition and release operations within Effect transactions for concurrency control over limited resources.
When to use
Use to coordinate permit accounting atomically with other transactional state changes.
See
makefor creating a transactional semaphorewithPermitfor automatically acquiring and releasing one permitacquirefor manually acquiring one permit transactionally
Signature
interface TxSemaphore extends Inspectable, Pipeable {
readonly "~effect/transactions/TxSemaphore": "~effect/transactions/TxSemaphore";
readonly capacity: number;
readonly permitsRef: TxRef<number>;
}
Acquires a single permit from the semaphore. If no permits are available, the effect will block until one becomes available.
When to use
Use to manually acquire one permit transactionally, waiting until one is available.
See
tryAcquirefor a non-blocking single-permit attemptreleasefor returning one permitwithPermitfor automatic acquire and release around an effect