Queue.ts overview
Since v2.0.0
Exports Grouped by Category
constructors
bounded
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>>
Since v2.0.0
dropping
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>>
Since v2.0.0
make
Signature
declare const make: <A>(queue: BackingQueue<A>, strategy: Strategy<A>) => Effect.Effect<Queue<A>>
Since v2.0.0
sliding
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>>
Since v2.0.0
unbounded
Creates a new unbounded Queue
.
Signature
declare const unbounded: <A>() => Effect.Effect<Queue<A>>
Since v2.0.0
getters
capacity
Returns the number of elements the queue can hold.
Signature
declare const capacity: <A>(self: Dequeue<A> | Enqueue<A>) => number
Since v2.0.0
isEmpty
Returns true
if the Queue
contains zero elements, false
otherwise.
Signature
declare const isEmpty: <A>(self: Dequeue<A> | Enqueue<A>) => Effect.Effect<boolean>
Since v2.0.0
isFull
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>
Since v2.0.0
isShutdown
Returns true
if shutdown
has been called, otherwise returns false
.
Signature
declare const isShutdown: <A>(self: Dequeue<A> | Enqueue<A>) => Effect.Effect<boolean>
Since v2.0.0
size
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>
Since v2.0.0
models
BackingQueue (interface)
Signature
export interface BackingQueue<in out A> extends Queue.BackingQueueVariance<A> {
/**
* Dequeues an element from the queue.
* Returns either an element from the queue, or the `def` param.
*/
poll<Def>(def: Def): A | Def
/**
* Dequeues up to `limit` elements from the queue.
*/
pollUpTo(limit: number): Chunk.Chunk<A>
/**
* Enqueues a collection of values into the queue.
*
* Returns a `Chunk` of the values that were **not** able to be enqueued.
*/
offerAll(elements: Iterable<A>): Chunk.Chunk<A>
/**
* Offers an element to the queue.
*
* Returns whether the enqueue was successful or not.
*/
offer(element: A): boolean
/**
* The **maximum** number of elements that a queue can hold.
*
* **Note**: unbounded queues can still implement this interface with
* `capacity = Infinity`.
*/
capacity(): number
/**
* Returns the number of elements currently in the queue
*/
length(): number
}
Since v2.0.0
BaseQueue (interface)
The base interface that all Queue
s must implement.
Signature
export interface BaseQueue {
/**
* Returns the number of elements the queue can hold.
*/
capacity(): number
/**
* Returns false if shutdown has been called.
*/
isActive(): boolean
/**
* 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.
*/
readonly size: Effect.Effect<number>
/**
* 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. Returns None if shutdown has been called
*/
unsafeSize(): Option.Option<number>
/**
* Returns `true` if the `Queue` contains at least one element, `false`
* otherwise.
*/
readonly isFull: Effect.Effect<boolean>
/**
* Returns `true` if the `Queue` contains zero elements, `false` otherwise.
*/
readonly isEmpty: Effect.Effect<boolean>
/**
* Interrupts any fibers that are suspended on `offer` or `take`. Future calls
* to `offer*` and `take*` will be interrupted immediately.
*/
readonly shutdown: Effect.Effect<void>
/**
* Returns `true` if `shutdown` has been called, otherwise returns `false`.
*/
readonly isShutdown: Effect.Effect<boolean>
/**
* Waits until the queue is shutdown. The `Effect` returned by this method will
* not resume until the queue has been shutdown. If the queue is already
* shutdown, the `Effect` will resume right away.
*/
readonly awaitShutdown: Effect.Effect<void>
}
Since v2.0.0
Dequeue (interface)
Signature
export interface Dequeue<out A> extends Effect.Effect<A>, Queue.DequeueVariance<A>, BaseQueue {
/**
* 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.
*/
readonly take: Effect.Effect<A>
/**
* Takes all the values in the queue and returns the values. If the queue is
* empty returns an empty collection.
*/
readonly takeAll: Effect.Effect<Chunk.Chunk<A>>
/**
* Takes up to max number of values from the queue.
*/
takeUpTo(max: number): Effect.Effect<Chunk.Chunk<A>>
/**
* 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.
*/
takeBetween(min: number, max: number): Effect.Effect<Chunk.Chunk<A>>
readonly [Unify.typeSymbol]?: unknown
readonly [Unify.unifySymbol]?: DequeueUnify<this>
readonly [Unify.ignoreSymbol]?: DequeueUnifyIgnore
}
Since v2.0.0
DequeueUnify (interface)
Signature
export interface DequeueUnify<A extends { [Unify.typeSymbol]?: any }> extends Effect.EffectUnify<A> {
Dequeue?: () => A[Unify.typeSymbol] extends Dequeue<infer A0> | infer _ ? Dequeue<A0> : never
}
Since v3.8.0
DequeueUnifyIgnore (interface)
Signature
export interface DequeueUnifyIgnore extends Effect.EffectUnifyIgnore {
Effect?: true
}
Since v3.8.0
Enqueue (interface)
Signature
export interface Enqueue<in A> extends Queue.EnqueueVariance<A>, BaseQueue, Pipeable {
/**
* Places one value in the queue.
*/
offer(value: A): Effect.Effect<boolean>
/**
* Places one value in the queue when possible without needing the fiber runtime.
*/
unsafeOffer(value: A): boolean
/**
* 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.
*/
offerAll(iterable: Iterable<A>): Effect.Effect<boolean>
}
Since v2.0.0
Queue (interface)
Signature
export interface Queue<in out A> extends Enqueue<A>, Dequeue<A> {
/** @internal */
readonly queue: BackingQueue<A>
/** @internal */
readonly takers: MutableQueue.MutableQueue<Deferred.Deferred<A>>
/** @internal */
readonly shutdownHook: Deferred.Deferred<void>
/** @internal */
readonly shutdownFlag: MutableRef.MutableRef<boolean>
/** @internal */
readonly strategy: Strategy<A>
readonly [Unify.typeSymbol]?: unknown
readonly [Unify.unifySymbol]?: QueueUnify<this>
readonly [Unify.ignoreSymbol]?: QueueUnifyIgnore
}
Since v2.0.0
QueueUnify (interface)
Signature
export interface QueueUnify<A extends { [Unify.typeSymbol]?: any }> extends DequeueUnify<A> {
Queue?: () => Extract<A[Unify.typeSymbol], Queue<any>>
}
Since v3.8.0
QueueUnifyIgnore (interface)
Signature
export interface QueueUnifyIgnore extends DequeueUnifyIgnore {
Dequeue?: true
}
Since v3.8.0
Strategy (interface)
Signature
export interface Strategy<in out A> extends Queue.StrategyVariance<A> {
/**
* Returns the number of surplus values that were unable to be added to the
* `Queue`
*/
surplusSize(): number
/**
* Determines how the `Queue.Strategy` should shut down when the `Queue` is
* shut down.
*/
readonly shutdown: Effect.Effect<void>
/**
* Determines the behavior of the `Queue.Strategy` when there are surplus
* values that could not be added to the `Queue` following an `offer`
* operation.
*/
handleSurplus(
iterable: Iterable<A>,
queue: BackingQueue<A>,
takers: MutableQueue.MutableQueue<Deferred.Deferred<A>>,
isShutdown: MutableRef.MutableRef<boolean>
): Effect.Effect<boolean>
/**
* It is called when the backing queue is empty but there are some
* takers that can be completed
*/
onCompleteTakersWithEmptyQueue(takers: MutableQueue.MutableQueue<Deferred.Deferred<A>>): void
/**
* Determines the behavior of the `Queue.Strategy` when the `Queue` has empty
* slots following a `take` operation.
*/
unsafeOnQueueEmptySpace(queue: BackingQueue<A>, takers: MutableQueue.MutableQueue<Deferred.Deferred<A>>): void
}
Since v2.0.0
refinements
isDequeue
Returns true
if the specified value is a Dequeue
, false
otherwise.
Signature
declare const isDequeue: (u: unknown) => u is Dequeue<unknown>
Since v2.0.0
isEnqueue
Returns true
if the specified value is a Enqueue
, false
otherwise.
Signature
declare const isEnqueue: (u: unknown) => u is Enqueue<unknown>
Since v2.0.0
isQueue
Returns true
if the specified value is a Queue
, false
otherwise.
Signature
declare const isQueue: (u: unknown) => u is Queue<unknown>
Since v2.0.0
strategies
backPressureStrategy
Signature
declare const backPressureStrategy: <A>() => Strategy<A>
Since v2.0.0
droppingStrategy
Signature
declare const droppingStrategy: <A>() => Strategy<A>
Since v2.0.0
slidingStrategy
Signature
declare const slidingStrategy: <A>() => Strategy<A>
Since v2.0.0
symbols
BackingQueueTypeId
Signature
declare const BackingQueueTypeId: unique symbol
Since v2.0.0
BackingQueueTypeId (type alias)
Signature
type BackingQueueTypeId = typeof BackingQueueTypeId
Since v2.0.0
DequeueTypeId
Signature
declare const DequeueTypeId: unique symbol
Since v2.0.0
DequeueTypeId (type alias)
Signature
type DequeueTypeId = typeof DequeueTypeId
Since v2.0.0
EnqueueTypeId
Signature
declare const EnqueueTypeId: unique symbol
Since v2.0.0
EnqueueTypeId (type alias)
Signature
type EnqueueTypeId = typeof EnqueueTypeId
Since v2.0.0
QueueStrategyTypeId
Signature
declare const QueueStrategyTypeId: unique symbol
Since v2.0.0
QueueStrategyTypeId (type alias)
Signature
type QueueStrategyTypeId = typeof QueueStrategyTypeId
Since v2.0.0
utils
Queue (namespace)
Since v2.0.0
EnqueueVariance (interface)
Signature
export interface EnqueueVariance<in A> {
readonly [EnqueueTypeId]: {
readonly _In: Types.Contravariant<A>
}
}
Since v2.0.0
DequeueVariance (interface)
Signature
export interface DequeueVariance<out A> {
readonly [DequeueTypeId]: {
readonly _Out: Types.Covariant<A>
}
}
Since v2.0.0
StrategyVariance (interface)
Signature
export interface StrategyVariance<in out A> {
readonly [QueueStrategyTypeId]: {
readonly _A: Types.Invariant<A>
}
}
Since v2.0.0
BackingQueueVariance (interface)
Signature
export interface BackingQueueVariance<in out A> {
readonly [BackingQueueTypeId]: {
readonly _A: Types.Invariant<A>
}
}
Since v2.0.0
awaitShutdown
Waits until the queue is shutdown. The Effect
returned by this method will not resume until the queue has been shutdown. If the queue is already shutdown, the Effect
will resume right away.
Signature
declare const awaitShutdown: <A>(self: Dequeue<A> | Enqueue<A>) => Effect.Effect<void>
Since v2.0.0
offer
Places one value in the queue.
Signature
declare const offer: {
<A>(value: A): (self: Enqueue<A>) => Effect.Effect<boolean>
<A>(self: Enqueue<A>, value: A): Effect.Effect<boolean>
}
Since v2.0.0
offerAll
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.Effect<boolean>
<A>(self: Enqueue<A>, iterable: Iterable<A>): Effect.Effect<boolean>
}
Since v2.0.0
poll
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>>
Since v2.0.0
shutdown
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>
Since v2.0.0
take
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>
Since v2.0.0
takeAll
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>>
Since v2.0.0
takeBetween
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.Effect<Chunk.Chunk<A>>
<A>(self: Dequeue<A>, min: number, max: number): Effect.Effect<Chunk.Chunk<A>>
}
Since v2.0.0
takeN
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.Effect<Chunk.Chunk<A>>
<A>(self: Dequeue<A>, n: number): Effect.Effect<Chunk.Chunk<A>>
}
Since v2.0.0
takeUpTo
Takes up to max number of values from the queue.
Signature
declare const takeUpTo: {
(max: number): <A>(self: Dequeue<A>) => Effect.Effect<Chunk.Chunk<A>>
<A>(self: Dequeue<A>, max: number): Effect.Effect<Chunk.Chunk<A>>
}
Since v2.0.0
unsafeOffer
Places one value in the queue.
Signature
declare const unsafeOffer: { <A>(value: A): (self: Enqueue<A>) => boolean; <A>(self: Enqueue<A>, value: A): boolean }
Since v2.0.0