Latch

Reusable synchronization primitives for coordinating fibers. A Latch is either open or closed: when it is closed, await and whenOpen suspend until the latch opens or the current waiters are released. The module includes effectful and synchronous constructors plus helpers to open, release, close, wait, and gate effects behind the latch.

11 exports Added in v4.0.0 Source

Combinators

close

Added in v4.0.0 Source

Closes the latch so future await and whenOpen calls suspend.

When to use

Use to re-enable waiting on a latch after it was opened, so later await and whenOpen calls suspend again.

Details

The returned effect succeeds with true when this call changed the latch from open to closed, or false if it was already closed.

See

closeUnsafe for a synchronous variant
open for opening the latch for current and future waiters

Signature

declare function close(self: Latch): Effect<boolean>;

open

Added in v4.0.0 Source

Opens the latch and releases fibers waiting on it.

When to use

Use to open a latch and release all fibers that are waiting on it.

Details

The returned effect succeeds with true when this call changed the latch from closed to open, or false if it was already open.

See

openUnsafe for a synchronous variant
release to release waiting fibers without opening the latch

Signature

declare function open(self: Latch): Effect<boolean>;

release

Added in v4.0.0 Source

Releases the fibers currently waiting on a closed latch without opening it.

When to use

Use to let the fibers currently waiting on a latch proceed while keeping the latch closed for future waiters.

Details

The returned effect succeeds with true when release was requested while the latch was closed, or false if the latch was already open. Future waiters still suspend until the latch is opened or released again.

See

open for opening the latch for current and future waiters

Signature

declare function release(self: Latch): Effect<boolean>;

whenOpen

Added in v4.0.0 Source

Waits on the latch, then runs the provided effect.

When to use

Use to gate another effect so it starts only after the latch is opened or the current waiters are released.

Details

If the latch is open, the effect runs immediately. If it is closed, the returned effect suspends until the latch is opened or the current waiters are released. The provided effect's success, failure, and requirements are preserved.

See

await for waiting without running another effect
open for opening the latch for current and future waiters
release for resuming current waiters without opening the latch

Signature

declare const whenOpen: {
  (self: Latch): <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, R>;
  <A, E, R>(self: Latch, effect: Effect<A, E, R>): Effect<A, E, R>;
};

Constructors

make

Added in v4.0.0 Source

Creates a Latch inside Effect.

When to use

Use to create a latch for coordinating fibers inside Effect code.

Details

The latch starts closed by default; pass true to create it open.

See

makeUnsafe for synchronous allocation outside Effect code

Signature

declare const make: (open?: boolean) => Effect.Effect<Latch>;

makeUnsafe

Added in v4.0.0 Source

Creates a Latch synchronously, outside of Effect.

When to use

Use when you need to allocate a Latch synchronously outside an Effect workflow.

Details

The latch starts closed by default; pass true to create it open.

See

make for creating a latch inside Effect code

Signature

declare const makeUnsafe: (open?: boolean) => Latch;

Models

Latch interface

Added in v4.0.0 Source

A reusable coordination primitive that lets fibers wait until they are released by the latch.

When to use

Use to coordinate fibers that must wait for an explicit open or release signal before continuing.

Details

A closed latch causes await and whenOpen to suspend. open opens the latch and releases current and future waiters, release releases only current waiters without opening it, and close makes future waiters suspend again.

See

make for creating a latch inside Effect code
open for releasing current and future waiters
release for releasing only the current waiters

Signature

interface Latch {
  readonly await: Effect<void>;
  readonly close: Effect<boolean>;
  readonly open: Effect<boolean>;
  readonly release: Effect<boolean>;
  closeUnsafe(this: Latch): boolean;
  isOpen(this: Latch): boolean;
  openUnsafe(this: Latch): boolean;
  whenOpen<A, E, R>(self: Effect<A, E, R>): Effect<A, E, R>;
}

Other

await

Source

Signature

declare function await(self: Latch): Effect<void>;

Predicates

isOpen

Added in v4.0.0 Source

Checks whether the latch is currently open or closed.

When to use

Use to check the state of the latch without suspending or changing its state.

Signature

declare function isOpen(self: Latch): boolean;

Unsafe

closeUnsafe

Added in v4.0.0 Source

Closes the latch synchronously so future await and whenOpen calls suspend.

When to use

Use to close a latch synchronously when the state change must happen outside an Effect.

Details

Returns true when this call changed the latch from open to closed, or false if it was already closed. This unsafe variant performs the state change immediately instead of returning an Effect.

See

close for the effectful variant
openUnsafe to synchronously open the latch and release waiting fibers

Signature

declare function closeUnsafe(self: Latch): boolean;

openUnsafe

Added in v4.0.0 Source

Opens the latch synchronously and releases fibers waiting on it.

When to use

Use when you need synchronous code to open a latch immediately and release the fibers waiting on it.

Details

Returns true when this call changed the latch from closed to open, or false if it was already open. This unsafe variant performs the state change immediately instead of returning an Effect.

See

open for the effectful variant
release to release waiting fibers without opening the latch
closeUnsafe for the synchronous inverse operation

Signature

declare function openUnsafe(self: Latch): boolean;