@thi.ng/fibers/csp.d.ts

Process hierarchies & operators for cooperative multitasking

import type { Maybe } from "@thi.ng/api";
import type { IReadWriteBuffer } from "@thi.ng/buffers";
import { DroppingBuffer } from "@thi.ng/buffers/dropping";
import { FIFOBuffer } from "@thi.ng/buffers/fifo";
import { LIFOBuffer } from "@thi.ng/buffers/lifo";
import { SlidingBuffer } from "@thi.ng/buffers/sliding";
import type { FiberOpts } from "./api.js";
import { Fiber } from "./fiber.js";
declare const STATE_OPEN = 0;
declare const STATE_CLOSING = 1;
declare const STATE_CLOSED = 2;
export type CSPState = typeof STATE_OPEN | typeof STATE_CLOSING | typeof STATE_CLOSED;
/**
 * Fiber-based CSP channel implementation, supporting any
 * [IReadWriteBuffer](https://docs.thi.ng/umbrella/buffers/interfaces/IReadWriteBuffer.html)
 * implementation to customize read/write behaviors (and ordering). By default
 * uses a single value {@link fifo} buffer impl.
 */
export declare class Channel<T> {
    opts?: Partial<FiberOpts> | undefined;
    protected buffer: IReadWriteBuffer<T>;
    protected state: CSPState;
    constructor(buffer?: IReadWriteBuffer<T> | number, opts?: Partial<FiberOpts> | undefined);
    /**
     * Returns a new fiber which attempts to read a value from the channel and
     * "blocks" until that value is available. Unless the channel has meanwhile
     * been closed, the fiber returns the read value (otherwise: `undefined`).
     *
     * @remarks
     * Depending on chosen back buffer behavior/implementation and
     * {@link Channel.close}, read requests might still be successful whilst the
     * channel is closing and there're still buffered values.
     *
     * @example
     * ```ts
     * const val = yield* chan.read();
     * ```
     */
    read(): Fiber<Maybe<T>>;
    /**
     * Returns a new fiber which attempts to write the given `value` to the
     * channel and "blocks" until channel is writable (which depends on the
     * channel's buffer implementation).
     *
     * @remarks
     * Once the channel has been closed (or still is closing, see
     * {@link Channel.close}), all write requests will be silently ignored.
     *
     * @example
     * ```ts
     * yield* chan.write(23);
     * ```
     */
    write(val: T): Fiber<any>;
    /**
     * Returns new fiber which closes the channel. By default this op will defer
     * the full closing until all buffered values have been read (by another
     * fiber), however any writes will already become unavailable/ignored even
     * at this stage (also see {@link Channel.write}). If `wait=false`, the
     * channel will be closed immediately, the backing buffered cleared and any
     * in-flight reads or writes will be canceled.
     *
     * @param wait
     */
    close(wait?: boolean): Fiber<any>;
    /**
     * Returns true if the channel is principally readable (i.e. not yet
     * closed), however there might not be any values available yet and reads
     * might block.
     */
    readable(): boolean;
    /**
     * Returns true if the channel is principally writable (i.e. not closing or
     * closed), however depending on buffer behavior the channel might not yet
     * accept new values and writes might block.
     */
    writable(): boolean;
    /**
     * Returns true if the channel is fully closed and no further reads or
     * writes are possible.
     */
    closed(): boolean;
}
/**
 * Functional syntax sugar for {@link Channel} ctor, using provided backing
 * buffer and shared options for all fibers returned by the channel for its
 * various operations.
 *
 * @remarks
 * If `buffer` is given as number, a {@link fifo} buffer of given capacity will
 * be used.
 *
 * @example
 * ```ts
 * import { channel, sliding } from "@thi.ng/fibers";
 * import { ConsoleLogger } from "@thi.ng/logger";
 *
 * // create unbuffered channel with single value capacity
 * const chan = channel();
 *
 * // create channel with a fixed buffer capacity of 3 values
 * const chan2 = channel(3);
 *
 * // create channel with a sliding window buffer and custom ID & logger
 * const chan3 = channel(
 *   sliding(3),
 *   { id: "main", logger: new ConsoleLogger("chan") }
 * );
 * ```
 *
 * @param buffer
 * @param opts
 */
export declare const channel: <T>(buffer?: IReadWriteBuffer<T> | number, opts?: Partial<FiberOpts>) => Channel<T>;
/**
 * Returns a {@link FIFOBuffer} ring buffer with given capacity for use with
 * {@link channel}.
 *
 * @remarks
 * With this implementation, writes to the channel will only start blocking once
 * the buffer's capacity is reached, otherwise complete immediately. Likewise,
 * channel reads are non-blocking whilst there're more buffered values
 * available. Reads will only block if the buffer is empty.
 *
 * Also see {@link lifo}.
 *
 * @param cap
 */
export declare const fifo: <T>(cap: number) => FIFOBuffer<T>;
/**
 *  Returns a {@link LIFOBuffer} with given capacity for use with
 * {@link channel}.
 *
 * @remarks
 *  Write behavior is the same as with {@link fifo}, reads are in reverse order
 *  (as the name indicates), i.e. the last value written will be the first value
 *  read (i.e. stack behavior).
 *
 * @param cap
 */
export declare const lifo: <T>(cap: number) => LIFOBuffer<T>;
/**
 * Returns a {@link SlidingBuffer} with given capacity for use with
 * {@link channel}.
 *
 * @remarks
 * With this implementation, writes to the channel are **never** blocking!
 * Whilst the buffer is at full capacity, new writes will first expunge the
 * oldest buffered value (similar to [LRU
 * cache](https://github.com/thi-ng/umbrella/blob/develop/packages/cache/README.md#lru)
 * behavior). Read behavior is the same as for {@link fifo}.
 *
 * Also see {@link dropping} for alternative behavior.
 *
 * @param cap
 */
export declare const sliding: <T>(cap: number) => SlidingBuffer<T>;
/**
 * Returns a {@link DroppingBuffer} with given capacity for use with
 * {@link channel}.
 *
 * @remarks
 * With this implementation, writes to the channel are **never** blocking!
 * Whilst the buffer is at full capacity, new writes will be silently ignored.
 * Read behavior is the same as for {@link fifo}.
 *
 * Also see {@link sliding} for alternative behavior.
 *
 * @param cap
 */
export declare const dropping: <T>(cap: number) => DroppingBuffer<T>;
export {};
//# sourceMappingURL=csp.d.ts.map