Queue API Reference

Constructors

bounded

Since v2.0.0

Makes a new bounded Queue. When the capacity of the queue is reached, any additional calls to offer will be suspended until there is more room in the queue.

Note: When possible use only power of 2 capacities; this will provide better performance by utilising an optimised version of the underlying RingBuffer.

Signature

declare const bounded: <A>(requestedCapacity: number) => Effect.Effect<Queue<A>>

dropping

Since v2.0.0

Makes a new bounded Queue with the dropping strategy.

When the capacity of the queue is reached, new elements will be dropped and the old elements will remain.

Note: When possible use only power of 2 capacities; this will provide better performance by utilising an optimised version of the underlying RingBuffer.

Signature

declare const dropping: <A>(requestedCapacity: number) => Effect.Effect<Queue<A>>

make

Since v2.0.0

Signature

declare const make: <A>(queue: BackingQueue<A>, strategy: Strategy<A>) => Effect.Effect<Queue<A>>

sliding

Since v2.0.0

Makes a new bounded Queue with the sliding strategy.

When the capacity of the queue is reached, new elements will be added and the old elements will be dropped.

Note: When possible use only power of 2 capacities; this will provide better performance by utilising an optimised version of the underlying RingBuffer.

Signature

declare const sliding: <A>(requestedCapacity: number) => Effect.Effect<Queue<A>>

unbounded

Since v2.0.0

Creates a new unbounded Queue.

Signature

declare const unbounded: <A>() => Effect.Effect<Queue<A>>

Getters

capacity

Since v2.0.0

Returns the number of elements the queue can hold.

Signature

declare const capacity: <A>(self: Dequeue<A> | Enqueue<A>) => number

isEmpty

Since v2.0.0

Returns true if the Queue contains zero elements, false otherwise.

Signature

declare const isEmpty: <A>(self: Dequeue<A> | Enqueue<A>) => Effect.Effect<boolean>

isFull

Since v2.0.0

Returns true if the Queue contains at least one element, false otherwise.

Signature

declare const isFull: <A>(self: Dequeue<A> | Enqueue<A>) => Effect.Effect<boolean>

isShutdown

Since v2.0.0

Returns true if shutdown has been called, otherwise returns false.

Signature

declare const isShutdown: <A>(self: Dequeue<A> | Enqueue<A>) => Effect.Effect<boolean>

size

Since v2.0.0

Retrieves the size of the queue, which is equal to the number of elements in the queue. This may be negative if fibers are suspended waiting for elements to be added to the queue.

Signature

declare const size: <A>(self: Dequeue<A> | Enqueue<A>) => Effect.Effect<number>

Models

BackingQueue

interface

Since v2.0.0

Signature

interface BackingQueue<in out A> extends BackingQueueVariance<A> {
  capacity(): number;
  length(): number;
  offer(element: A): boolean;
  offerAll(elements: Iterable<A>): Chunk<A>;
  poll<Def>(def: Def): A | Def;
  pollUpTo(limit: number): Chunk<A>;
}

BaseQueue

interface

Since v2.0.0

The base interface that all Queues must implement.

Signature

interface BaseQueue {
  readonly awaitShutdown: Effect<void>;
  readonly isEmpty: Effect<boolean>;
  readonly isFull: Effect<boolean>;
  readonly isShutdown: Effect<boolean>;
  readonly shutdown: Effect<void>;
  readonly size: Effect<number>;
  capacity(): number;
  isActive(): boolean;
  unsafeSize(): Option<number>;
}

Dequeue

interface

Since v2.0.0

Signature

interface Dequeue<out A> extends Effect<A>, DequeueVariance<A>, BaseQueue {
  readonly [ignoreSymbol]?: DequeueUnifyIgnore;
  readonly [typeSymbol]?: unknown;
  readonly [unifySymbol]?: DequeueUnify<Dequeue<A>>;
  readonly take: Effect<A>;
  readonly takeAll: Effect<Chunk<A>>;
  takeBetween(min: number, max: number): Effect<Chunk<A>>;
  takeUpTo(max: number): Effect<Chunk<A>>;
}

DequeueUnify

interface

Since v3.8.0

Signature

interface DequeueUnify<A extends {
  [typeSymbol]?: any;
}> extends EffectUnify<A> {
  Dequeue?: () => A[typeof typeSymbol] extends Dequeue<A0> | _ ? Dequeue<A0> : never;
}

DequeueUnifyIgnore

interface

Since v3.8.0

Signature

interface DequeueUnifyIgnore extends EffectUnifyIgnore {
  Effect?: true;
}

Enqueue

interface

Since v2.0.0

Signature

interface Enqueue<in A> extends EnqueueVariance<A>, BaseQueue, Pipeable {
  offer(value: A): Effect<boolean>;
  offerAll(iterable: Iterable<A>): Effect<boolean>;
  unsafeOffer(value: A): boolean;
}

Queue

interface

Since v2.0.0

Signature

interface Queue<in out A> extends Enqueue<A>, Dequeue<A> {
  readonly [ignoreSymbol]?: QueueUnifyIgnore;
  readonly [typeSymbol]?: unknown;
  readonly [unifySymbol]?: QueueUnify<Queue<A>>;
}

QueueUnify

interface

Since v3.8.0

Signature

interface QueueUnify<A extends {
  [typeSymbol]?: any;
}> extends DequeueUnify<A> {
  Queue?: () => Extract<A[typeof typeSymbol], Queue<any>>;
}

QueueUnifyIgnore

interface

Since v3.8.0

Signature

interface QueueUnifyIgnore extends DequeueUnifyIgnore {
  Dequeue?: true;
}

Strategy

interface

Since v2.0.0

Signature

interface Strategy<in out A> extends StrategyVariance<A> {
  readonly shutdown: Effect<void>;
  handleSurplus(iterable: Iterable<A>, queue: BackingQueue<A>, takers: MutableQueue<Deferred<A, never>>, isShutdown: MutableRef<boolean>): Effect<boolean>;
  onCompleteTakersWithEmptyQueue(takers: MutableQueue<Deferred<A, never>>): void;
  surplusSize(): number;
  unsafeOnQueueEmptySpace(queue: BackingQueue<A>, takers: MutableQueue<Deferred<A, never>>): void;
}

Refinements

isDequeue

Since v2.0.0

Returns true if the specified value is a Dequeue, false otherwise.

Signature

declare const isDequeue: (u: unknown) => u is Dequeue<unknown>

isEnqueue

Since v2.0.0

Returns true if the specified value is a Enqueue, false otherwise.

Signature

declare const isEnqueue: (u: unknown) => u is Enqueue<unknown>

isQueue

Since v2.0.0

Returns true if the specified value is a Queue, false otherwise.

Signature

declare const isQueue: (u: unknown) => u is Queue<unknown>

Strategies

backPressureStrategy

Since v2.0.0

Signature

declare const backPressureStrategy: <A>() => Strategy<A>

droppingStrategy

Since v2.0.0

Signature

declare const droppingStrategy: <A>() => Strategy<A>

slidingStrategy

Since v2.0.0

Signature

declare const slidingStrategy: <A>() => Strategy<A>

Symbols

BackingQueueTypeId

Since v2.0.0

Signature

declare const BackingQueueTypeId: unique symbol

BackingQueueTypeId

type

Since v2.0.0

Signature

type BackingQueueTypeId = typeof BackingQueueTypeId

DequeueTypeId

Since v2.0.0

Signature

declare const DequeueTypeId: unique symbol

DequeueTypeId

type

Since v2.0.0

Signature

type DequeueTypeId = typeof DequeueTypeId

EnqueueTypeId

Since v2.0.0

Signature

declare const EnqueueTypeId: unique symbol

EnqueueTypeId

type

Since v2.0.0

Signature

type EnqueueTypeId = typeof EnqueueTypeId

QueueStrategyTypeId

Since v2.0.0

Signature

declare const QueueStrategyTypeId: unique symbol

QueueStrategyTypeId

type

Since v2.0.0

Signature

type QueueStrategyTypeId = typeof QueueStrategyTypeId

For Bounded Queue: uses the BackPressure Strategy, places the values in the queue and always returns true. If the queue has reached capacity, then the fiber performing the offerAll will be suspended until there is room in the queue.

For Unbounded Queue: Places all values in the queue and returns true.

For Sliding Queue: uses Sliding Strategy If there is room in the queue, it places the values otherwise it removes the old elements and enqueues the new ones. Always returns true.

For Dropping Queue: uses Dropping Strategy, It places the values in the queue but if there is no room it will not enqueue them and return false.

Signature

declare const offerAll: {
  <A>(iterable: Iterable<A>): (self: Enqueue<A>) => Effect<boolean>;
  <A>(self: Enqueue<A>, iterable: Iterable<A>): Effect<boolean>;
}

poll

Since v2.0.0

Returns the first value in the Queue as a Some<A>, or None if the queue is empty.

Signature

declare const poll: <A>(self: Dequeue<A>) => Effect.Effect<Option.Option<A>>

shutdown

Since v2.0.0

Interrupts any fibers that are suspended on offer or take. Future calls to offer* and take* will be interrupted immediately.

Signature

declare const shutdown: <A>(self: Dequeue<A> | Enqueue<A>) => Effect.Effect<void>

take

Since v2.0.0

Takes the oldest value in the queue. If the queue is empty, this will return a computation that resumes when an item has been added to the queue.

Signature

declare const take: <A>(self: Dequeue<A>) => Effect.Effect<A>

takeAll

Since v2.0.0

Takes all the values in the queue and returns the values. If the queue is empty returns an empty collection.

Signature

declare const takeAll: <A>(self: Dequeue<A>) => Effect.Effect<Chunk.Chunk<A>>

takeBetween

Since v2.0.0

Takes a number of elements from the queue between the specified minimum and maximum. If there are fewer than the minimum number of elements available, suspends until at least the minimum number of elements have been collected.

Signature

declare const takeBetween: {
  (min: number, max: number): <A>(self: Dequeue<A>) => Effect<Chunk<A>>;
  <A>(self: Dequeue<A>, min: number, max: number): Effect<Chunk<A>>;
}

takeN

Since v2.0.0

Takes the specified number of elements from the queue. If there are fewer than the specified number of elements available, it suspends until they become available.

Signature

declare const takeN: {
  (n: number): <A>(self: Dequeue<A>) => Effect<Chunk<A>>;
  <A>(self: Dequeue<A>, n: number): Effect<Chunk<A>>;
}

takeUpTo

Since v2.0.0

Takes up to max number of values from the queue.

Signature

declare const takeUpTo: {
  (max: number): <A>(self: Dequeue<A>) => Effect<Chunk<A>>;
  <A>(self: Dequeue<A>, max: number): Effect<Chunk<A>>;
}

unsafeOffer

Since v2.0.0

Places one value in the queue.

Signature

declare const unsafeOffer: {
  <A>(value: A): (self: Enqueue<A>) => boolean;
  <A>(self: Enqueue<A>, value: A): boolean;
}