@thi.ng/fibers 0.1.1 → 0.2.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-08-05T08:00:59Z
+- **Last updated**: 2023-08-10T12:25:09Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,33 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [0.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/fibers@0.2.0) (2023-08-10)
+
+#### 🚀 Features
+
+- ensure no pre-existing parent in Fiber.fork() ([612adf9](https://github.com/thi-ng/umbrella/commit/612adf9))
+- add auto terminate option, update child handling ([e59063d](https://github.com/thi-ng/umbrella/commit/e59063d))
+- add shuffle() operator, update deps ([b3efa79](https://github.com/thi-ng/umbrella/commit/b3efa79))
+- add CSP primitives ([d8fa8ce](https://github.com/thi-ng/umbrella/commit/d8fa8ce))
+  - add fiber-based Channel class
+  - add various buffer implementations
+    - fifo
+    - lifo
+    - sliding
+    - dropping
+
+#### ⏱ Performance improvements
+
+- rewrite FIFOBuffer as ring buffer ([ebac714](https://github.com/thi-ng/umbrella/commit/ebac714))
+  - use old impl as basis for LIFOBuffer only
+  - update other buffer types to use new ring buffer impl
+  - add min. capacity assertion in ctors
+
+#### ♻️ Refactoring
+
+- minor update all() ([52836a8](https://github.com/thi-ng/umbrella/commit/52836a8))
+- update arg types in various ops ([cb3c253](https://github.com/thi-ng/umbrella/commit/cb3c253))
+
 ### [0.1.1](https://github.com/thi-ng/umbrella/tree/@thi.ng/fibers@0.1.1) (2023-08-05)
 
 #### 🩹 Bug fixes

package/README.md

@@ -1,6 +1,7 @@
 <!-- This file is generated - DO NOT EDIT! -->
+<!-- Please see: https://github.com/thi-ng/umbrella/blob/develop/CONTRIBUTING.md#changes-to-readme-files -->
 
-# ![@thi.ng/fibers](https://media.thi.ng/umbrella/banners-20220914/thing-fibers.svg?d08288cb)
+# ![@thi.ng/fibers](https://media.thi.ng/umbrella/banners-20230807/thing-fibers.svg?d08288cb)
 
 [![npm version](https://img.shields.io/npm/v/@thi.ng/fibers.svg)](https://www.npmjs.com/package/@thi.ng/fibers)
 ![npm downloads](https://img.shields.io/npm/dm/@thi.ng/fibers.svg)
@@ -13,6 +14,10 @@ This project is part of the
   - [Basic usage](#basic-usage)
   - [Fiber operators](#fiber-operators)
   - [Composition via transducers](#composition-via-transducers)
+  - [CSP primitives (Communicating Sequential Processes)](#csp-primitives-communicating-sequential-processes)
+    - [Buffering behaviors](#buffering-behaviors)
+    - [Channels](#channels)
+    - [CSP ping/pong example](#csp-pingpong-example)
 - [Status](#status)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
@@ -114,6 +119,7 @@ The following operators act as basic composition helpers to construct more elabo
 - [`forkAll`](https://docs.thi.ng/umbrella/fibers/classes/Fiber.html#forkAll): create & attach multiple child processes
 - [`join`](https://docs.thi.ng/umbrella/fibers/classes/Fiber.html#join): wait for all child processes to complete
 - [`sequence`](https://docs.thi.ng/umbrella/fibers/functions/sequence.html): execute fibers in sequence
+- [`shuffle`](https://docs.thi.ng/umbrella/fibers/functions/shuffle.html): execute fibers in constantly randomized order
 - [`timeSlice`](https://docs.thi.ng/umbrella/fibers/functions/timeSlice.html): execute fiber in batches of N milliseconds
 - [`until`](https://docs.thi.ng/umbrella/fibers/functions/until.html): wait until predicate is truthy
 - [`untilEvent`](https://docs.thi.ng/umbrella/fibers/functions/untilEvent.html): wait until event occurs
@@ -173,6 +179,177 @@ sequence(
 // part 7
 ```
 
+### CSP primitives (Communicating Sequential Processes)
+
+References:
+
+- [Wikipedia](https://en.wikipedia.org/wiki/Communicating_sequential_processes)
+- [Communicating Sequential Processes, C.A.R.
+Hoare](https://dl.acm.org/doi/pdf/10.1145/359576.359585)
+
+In addition to the operators above, the basic fiber implementation can also be
+used to construct other types of primitives, like those required for
+channel-based communication between processes, as proposed by Tony Hoare. The
+package includes a fiber-based read/write channel primitive which can be
+customized with different buffer implementations to control blocking behaviors
+and backpressure handling (aka attempting to write faster to a channel than
+values are being read, essentially a memory management issue).
+
+#### Buffering behaviors
+
+The following channel buffer types/behaviors are included, all accepting a max.
+capacity and all implementing the
+[IReadWriteBuffer](https://docs.thi.ng/umbrella/fibers/interfaces/IReadWriteBuffer.html)
+interface required by the channel:
+
+- [`fifo`](https://docs.thi.ng/umbrella/fibers/functions/fifo.html): First in,
+  first out ring buffer. Writes to the channel will 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.
+- [`lifo`](https://docs.thi.ng/umbrella/fibers/functions/lifo.html): Last in,
+  first out. Read/write behavior is mostly the same as with `fifo`, with the
+  important difference, that (as the name indicates), the last value written
+  will be the first value read (i.e. stack behavior).
+- [`sliding`](https://docs.thi.ng/umbrella/fibers/functions/sliding.html):
+  Sliding window ring buffer. Writes to the channel are **never** blocking! Once
+  the buffer's capacity is reached, a new write will first expunge the oldest
+  buffered value (similar to LRU cache behavior). Read behavior is the same as
+  for `fifo`.
+- [`dropping`](https://docs.thi.ng/umbrella/fibers/functions/dropping.html):
+  Dropping value ring buffer. Writes to the channel are **never** blocking!
+  Whilst the buffer's capacity is reached, new writes will be silently ignored.
+  Read behavior is the same as for `fifo`.
+
+#### Channels
+
+As mentioned previously,
+[channels](https://docs.thi.ng/umbrella/fibers/functions/channel.html) and their
+[read](https://docs.thi.ng/umbrella/fibers/classes/Channel.html#read),
+[write](https://docs.thi.ng/umbrella/fibers/classes/Channel.html#write) and
+[close](https://docs.thi.ng/umbrella/fibers/classes/Channel.html#close)
+operations are the key building blocks for CSP. In this fiber-based
+implementation, all channel operations are executed in individual fibers to deal
+with the potential blocking behaviors. This is demonstrated in the simple
+example below.
+
+In general, due to fibers not being true multi-threaded processes (all are
+executed in the single thread of the JS engine), any number of fibers can read
+or write to a channel.
+
+Channels can be created like so:
+
+```ts
+// create unbuffered channel with single value capacity
+const chan1 = channel();
+
+// create channel with a FIFO buffer, capacity: 2 values
+const chan2 = channel(2);
+
+// create channel with a sliding window buffer and custom ID & logger
+const chan3 = channel(
+  sliding(3),
+  { id: "main", logger: new ConsoleLogger("chan") }
+);
+```
+
+#### CSP ping/pong example
+
+```ts tangle:export/pingpong.ts
+import { channel, fiber, wait } from "@thi.ng/fibers";
+import { ConsoleLogger } from "@thi.ng/logger";
+
+// create idle main fiber with custom options
+const app = fiber(null, {
+    id: "main",
+    logger: new ConsoleLogger("app"),
+    // if true, fiber automatically terminates once all child fibers are done
+    terminate: true,
+});
+
+// create CSP channels (w/ default config)
+const ping = channel<number>();
+const pong = channel<number>();
+
+// attach ping/pong child processes
+app.forkAll(
+    // ping
+    function* () {
+        while (ping.readable()) {
+            // blocking read op
+            // (waits until value is available in `ping` channel)
+            const x = yield* ping.read();
+            // check if channel was closed meanwhile
+            if (x === undefined) break;
+            console.log("PING", x);
+            // possibly blocking (in general) write op to other channel
+            yield* pong.write(x);
+            // slowdown
+            yield* wait(100);
+        }
+    },
+    // pong (very similar)
+    function* () {
+        while (pong.readable()) {
+            const x = yield* pong.read();
+            if (x === undefined) break;
+            console.log("PONG", x);
+            // trigger next iteration
+            yield* ping.write(x + 1);
+        }
+    },
+    // channel managment
+    function* () {
+        // kickoff ping/pong
+        yield* ping.write(0);
+        yield* wait(1000);
+        // wait for both channels to close
+        yield* ping.close();
+        yield* pong.close();
+    }
+);
+app.run();
+
+// [DEBUG] app: forking fib-0
+// [DEBUG] app: forking fib-1
+// [DEBUG] app: forking fib-2
+// [DEBUG] app: running main...
+// [DEBUG] app: init main
+// [DEBUG] app: init fib-0
+// [DEBUG] app: init fib-1
+// [DEBUG] app: init fib-2
+// PING 0
+// PONG 0
+// PING 1
+// PONG 1
+// ...
+// PING 9
+// PONG 9
+// [DEBUG] app: done fib-2 undefined
+// [DEBUG] app: deinit fib-2
+// [DEBUG] app: done fib-1 undefined
+// [DEBUG] app: deinit fib-1
+// [DEBUG] app: done fib-0 undefined
+// [DEBUG] app: deinit fib-0
+// [DEBUG] app: cancel main
+// [DEBUG] app: deinit main
+```
+
+Additional CSP operators are planned, but since everything here is based on
+fibers, the various channel operations can be already combined with the
+[available fiber operators/combinators](#fiber-operators)...
+
+For example, a channel read or write op can be combined with a timeout:
+
+```ts
+const res = (yield* withTimeout(chan.read(), 1000)).deref();
+if (res !== undefined) {
+    console.log("read value", x);
+} else {
+    console.log("read timeout");
+}
+```
+
 ## Status
 
 **ALPHA** - bleeding edge / work-in-progress
@@ -199,14 +376,18 @@ For Node.js REPL:
 const fibers = await import("@thi.ng/fibers");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 1.88 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 2.25 KB
 
 ## Dependencies
 
 - [@thi.ng/api](https://github.com/thi-ng/umbrella/tree/develop/packages/api)
+- [@thi.ng/arrays](https://github.com/thi-ng/umbrella/tree/develop/packages/arrays)
 - [@thi.ng/bench](https://github.com/thi-ng/umbrella/tree/develop/packages/bench)
 - [@thi.ng/checks](https://github.com/thi-ng/umbrella/tree/develop/packages/checks)
+- [@thi.ng/errors](https://github.com/thi-ng/umbrella/tree/develop/packages/errors)
+- [@thi.ng/idgen](https://github.com/thi-ng/umbrella/tree/develop/packages/idgen)
 - [@thi.ng/logger](https://github.com/thi-ng/umbrella/tree/develop/packages/logger)
+- [@thi.ng/random](https://github.com/thi-ng/umbrella/tree/develop/packages/random)
 
 ## Usage examples
 

package/api.d.ts

@@ -1,4 +1,4 @@
-import type { Fn, Fn2, IIDGen } from "@thi.ng/api";
+import type { Fn, Fn2, IClear, IIDGen } from "@thi.ng/api";
 import type { ILogger } from "@thi.ng/logger";
 import type { Fiber } from "./fiber.js";
 export type FiberFactory<T = any> = (f: Fiber<T>) => Generator<unknown, T, unknown>;
@@ -22,6 +22,15 @@ export interface FiberOpts {
      * @internal
      */
     parent: Fiber;
+    /**
+     * If true (default: false), the fiber cancels itself once it has no more
+     * children. See {@link Fiber.cancel}.
+     *
+     * @remarks
+     * When enabling this option, ensure that the fiber has child processes
+     * attached **before** execution!
+     */
+    terminate: boolean;
     /**
      * User init handler
      */
@@ -59,4 +68,27 @@ export declare const EVENT_FIBER_CANCELED = "fiber-canceled";
  */
 export declare const EVENT_FIBER_ERROR = "fiber-error";
 export type FiberEventType = typeof EVENT_FIBER_DONE | typeof EVENT_FIBER_CANCELED | typeof EVENT_FIBER_ERROR | "*";
+export interface IReadBuffer<T> {
+    /**
+     * Returns true iff the buffer has at least one value available for reading.
+     */
+    readable(): boolean;
+    /**
+     * Unguarded read operation. Assumes the caller checked
+     * {@link IReadBuffer.readable} immediately before. Returns next value from
+     * buffer.
+     */
+    read(): T;
+}
+export interface IReadWriteBuffer<T> extends IReadBuffer<T>, IClear {
+    /**
+     * Returns true iff the buffer has at least one slot available for writing.
+     */
+    writable(): boolean;
+    /**
+     * Unguarded write operation. Assumes the caller checked
+     * {@link IReadWriteBuffer.writable} immediately before.
+     */
+    write(x: T): void;
+}
 //# sourceMappingURL=api.d.ts.map

package/csp.d.ts

@@ -0,0 +1,193 @@
+import type { FiberOpts, IReadWriteBuffer } from "./api.js";
+import { Fiber } from "./fiber.js";
+declare const STATE_OPEN = 0;
+declare const STATE_CLOSING = 1;
+declare const STATE_CLOSED = 2;
+type CSPState = typeof STATE_OPEN | typeof STATE_CLOSING | typeof STATE_CLOSED;
+/**
+ * Fiber-based CSP channel implementation, supporting any
+ * {@link IReadWriteBuffer} 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<T | undefined>;
+    /**
+     * 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
+ * // 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?: number | IReadWriteBuffer<T> | undefined, opts?: Partial<FiberOpts>) => Channel<T>;
+/**
+ * First-in, first-out ring buffer implementation for use with {@link Channel}.
+ */
+export declare class FIFOBuffer<T> implements IReadWriteBuffer<T> {
+    protected buf: (T | undefined)[];
+    protected rpos: number;
+    protected wpos: number;
+    constructor(cap?: number);
+    clear(): void;
+    readable(): boolean;
+    read(): NonNullable<T>;
+    writable(): boolean;
+    write(x: T): void;
+}
+/**
+ * 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>;
+export declare class LIFOBuffer<T> implements IReadWriteBuffer<T> {
+    protected cap: number;
+    protected buf: T[];
+    constructor(cap?: number);
+    clear(): void;
+    readable(): boolean;
+    read(): NonNullable<T>;
+    writable(): boolean;
+    write(x: T): void;
+}
+/**
+ *  Returns a {@link LIFOBuffer} with given capacity for use with
+ * {@link channel}.
+ *
+ * @remarks
+ * Read/write behavior is mostly the same as with {@link fifo}, with the
+ * important difference, that (as the name indicates), 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>;
+export declare class SlidingBuffer<T> extends FIFOBuffer<T> {
+    writable(): boolean;
+    write(x: T): void;
+}
+/**
+ * Returns a {@link SlidingBuffer} with given capacity for use with
+ * {@link channel}.
+ *
+ * @remarks
+ * With this implementation, writes to the channel are **never** blocking! Once
+ * the buffer's capacity is reached, a new write will first expunge the oldest
+ * buffered value. 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>;
+export declare class DroppingBuffer<T> extends FIFOBuffer<T> {
+    writable(): boolean;
+    write(x: T): void;
+}
+/**
+ * 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's capacity is reached, 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

package/csp.js

@@ -0,0 +1,286 @@
+import { isNumber } from "@thi.ng/checks";
+import { assert } from "@thi.ng/errors/assert";
+import { Fiber, fiber } from "./fiber.js";
+const STATE_OPEN = 0;
+const STATE_CLOSING = 1;
+const STATE_CLOSED = 2;
+/**
+ * Fiber-based CSP channel implementation, supporting any
+ * {@link IReadWriteBuffer} implementation to customize read/write behaviors
+ * (and ordering). By default uses a single value {@link fifo} buffer impl.
+ */
+export class Channel {
+    constructor(buffer = 1, opts) {
+        this.opts = opts;
+        this.state = STATE_OPEN;
+        this.buffer = isNumber(buffer) ? new FIFOBuffer(buffer) : buffer;
+    }
+    /**
+     * 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() {
+        const $this = this;
+        return fiber(function* (ctx) {
+            while ($this.readable()) {
+                // wait until channel is readable
+                if ($this.buffer.readable()) {
+                    const val = $this.buffer.read();
+                    ctx.logger?.debug("read", val);
+                    return val;
+                }
+                else if ($this.state === STATE_CLOSING) {
+                    return;
+                }
+                yield;
+            }
+        }, this.opts);
+    }
+    /**
+     * 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) {
+        const $this = this;
+        return fiber(function* (ctx) {
+            while ($this.writable()) {
+                // wait until channel is writable
+                if ($this.buffer.writable()) {
+                    ctx.logger?.debug("write", val);
+                    $this.buffer.write(val);
+                    return;
+                }
+                yield;
+            }
+        }, this.opts);
+    }
+    /**
+     * 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 = true) {
+        const $this = this;
+        return fiber(function* (ctx) {
+            if ($this.state >= STATE_CLOSING)
+                return;
+            if (wait) {
+                ctx.logger?.debug("waiting to close...");
+                $this.state = STATE_CLOSING;
+                while ($this.buffer.readable())
+                    yield;
+            }
+            $this.state = STATE_CLOSED;
+            $this.buffer.clear();
+            ctx.logger?.debug("channel closed");
+        }, this.opts);
+    }
+    /**
+     * 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() {
+        return this.state <= STATE_CLOSING;
+    }
+    /**
+     * 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() {
+        return this.state === STATE_OPEN;
+    }
+    /**
+     * Returns true if the channel is fully closed and no further reads or
+     * writes are possible.
+     */
+    closed() {
+        return this.state === STATE_CLOSED;
+    }
+}
+/**
+ * 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
+ * // 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 const channel = (buffer, opts) => new Channel(buffer, opts);
+/**
+ * First-in, first-out ring buffer implementation for use with {@link Channel}.
+ */
+export class FIFOBuffer {
+    constructor(cap = 1) {
+        this.rpos = 0;
+        this.wpos = 0;
+        assert(cap >= 1, `capacity must be >= 1`);
+        this.buf = new Array(cap + 1);
+    }
+    clear() {
+        this.buf.fill(undefined);
+    }
+    readable() {
+        return this.rpos !== this.wpos;
+    }
+    read() {
+        const { buf, rpos } = this;
+        const val = buf[rpos];
+        buf[rpos] = undefined;
+        this.rpos = (rpos + 1) % buf.length;
+        return val;
+    }
+    writable() {
+        return (this.wpos + 1) % this.buf.length !== this.rpos;
+    }
+    write(x) {
+        const { buf, wpos } = this;
+        buf[wpos] = x;
+        this.wpos = (wpos + 1) % buf.length;
+    }
+}
+/**
+ * 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 const fifo = (cap) => new FIFOBuffer(cap);
+export class LIFOBuffer {
+    constructor(cap = 1) {
+        this.cap = cap;
+        this.buf = [];
+        assert(cap >= 1, `capacity must be >= 1`);
+    }
+    clear() {
+        this.buf.length = 0;
+    }
+    readable() {
+        return this.buf.length > 0;
+    }
+    read() {
+        return this.buf.pop();
+    }
+    writable() {
+        return this.buf.length < this.cap;
+    }
+    write(x) {
+        this.buf.push(x);
+    }
+}
+/**
+ *  Returns a {@link LIFOBuffer} with given capacity for use with
+ * {@link channel}.
+ *
+ * @remarks
+ * Read/write behavior is mostly the same as with {@link fifo}, with the
+ * important difference, that (as the name indicates), the last value written
+ * will be the first value read (i.e. stack behavior).
+ *
+ * @param cap
+ */
+export const lifo = (cap) => new LIFOBuffer(cap);
+export class SlidingBuffer extends FIFOBuffer {
+    writable() {
+        return true;
+    }
+    write(x) {
+        if (!super.writable()) {
+            const { buf, rpos } = this;
+            buf[rpos] = undefined;
+            this.rpos = (rpos + 1) % buf.length;
+        }
+        super.write(x);
+    }
+}
+/**
+ * Returns a {@link SlidingBuffer} with given capacity for use with
+ * {@link channel}.
+ *
+ * @remarks
+ * With this implementation, writes to the channel are **never** blocking! Once
+ * the buffer's capacity is reached, a new write will first expunge the oldest
+ * buffered value. Read behavior is the same as for {@link fifo}.
+ *
+ * Also see {@link dropping} for alternative behavior.
+ *
+ * @param cap
+ */
+export const sliding = (cap) => new SlidingBuffer(cap);
+export class DroppingBuffer extends FIFOBuffer {
+    writable() {
+        return true;
+    }
+    write(x) {
+        if (super.writable())
+            super.write(x);
+    }
+}
+/**
+ * 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's capacity is reached, 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 const dropping = (cap) => new DroppingBuffer(cap);

package/fiber.d.ts

@@ -14,7 +14,8 @@ export declare class Fiber<T = any> implements IDeref<T | undefined>, IID<string
     gen: Nullable<Generator<unknown, T>>;
     idgen?: IIDGen<string>;
     state: State;
-    children?: Fiber[];
+    autoTerminate: boolean;
+    children: Fiber[];
     value?: T;
     error?: Error;
     logger?: ILogger;
@@ -92,7 +93,7 @@ export declare class Fiber<T = any> implements IDeref<T | undefined>, IID<string
      * @param f
      * @param opts
      */
-    fork<F>(body?: Nullable<MaybeFiber<F>>, opts?: Partial<FiberOpts>): Fiber<F>;
+    fork<F>(body?: Nullable<MaybeFiber<F>>, opts?: Partial<FiberOpts>): Fiber<any>;
     /**
      * Calls {@link Fiber.fork} for all given fibers and returns them as array.
      *

package/fiber.js

@@ -1,17 +1,22 @@
+var Fiber_1;
 import { __decorate } from "tslib";
 import { INotifyMixin } from "@thi.ng/api/mixins/inotify";
 import { isFunction } from "@thi.ng/checks/is-function";
+import { illegalArgs } from "@thi.ng/errors/illegal-arguments";
 import { illegalState } from "@thi.ng/errors/illegal-state";
 import { monotonic, prefixed } from "@thi.ng/idgen";
 import { EVENT_FIBER_CANCELED, EVENT_FIBER_DONE, EVENT_FIBER_ERROR, STATE_ACTIVE, STATE_CANCELED, STATE_DONE, STATE_ERROR, STATE_NEW, } from "./api.js";
 let DEFAULT_ID_GEN = prefixed("fib-", monotonic());
 export const setDefaultIDGen = (gen) => (DEFAULT_ID_GEN = gen);
 const NO_RESULT = { done: false, value: undefined };
-export let Fiber = class Fiber {
+export let Fiber = Fiber_1 = class Fiber {
     constructor(gen, opts) {
         this.state = STATE_NEW;
+        this.autoTerminate = false;
+        this.children = [];
         this.value = undefined;
         if (opts) {
+            this.autoTerminate = !!opts.terminate;
             this.logger = opts.logger;
             this.parent = opts.parent;
             this.user = {
@@ -29,7 +34,7 @@ export let Fiber = class Fiber {
         else {
             this.idgen = DEFAULT_ID_GEN;
         }
-        if (!this.id && this.idgen)
+        if (this.idgen)
             this.id = this.idgen.next();
         this.gen = isFunction(gen) ? gen(this) : gen;
     }
@@ -63,7 +68,7 @@ export let Fiber = class Fiber {
      * @param id
      */
     childForID(id) {
-        return this.children?.find((f) => f.id === id);
+        return this.children.find((f) => f.id === id);
     }
     /**
      * Adds given `body` as child process to this fiber. If not already a
@@ -118,14 +123,20 @@ export let Fiber = class Fiber {
     fork(body, opts) {
         if (!this.isActive())
             illegalState(`fiber (id: ${this.id}) not active`);
-        const $fiber = fiber(body, {
-            parent: this,
-            logger: this.logger,
-            idgen: this.idgen,
-            ...opts,
-        });
-        if (!this.children)
-            this.children = [];
+        let $fiber;
+        if (body instanceof Fiber_1) {
+            if (body.parent)
+                illegalArgs(`fiber id: ${body.id} already has a parent`);
+            $fiber = body;
+        }
+        else {
+            $fiber = fiber(body, {
+                parent: this,
+                logger: this.logger,
+                idgen: this.idgen,
+                ...opts,
+            });
+        }
         this.children.push($fiber);
         this.logger?.debug("forking", $fiber.id);
         return $fiber;
@@ -151,7 +162,7 @@ export let Fiber = class Fiber {
      */
     *join() {
         this.logger?.debug("waiting for children...");
-        while (this.children?.length)
+        while (this.children.length)
             yield;
     }
     /**
@@ -174,7 +185,7 @@ export let Fiber = class Fiber {
             case STATE_ACTIVE:
                 try {
                     const { children } = this;
-                    if (children) {
+                    if (children.length) {
                         for (let i = 0, n = children.length; i < n;) {
                             const child = children[i];
                             if (child.state > STATE_ACTIVE ||
@@ -186,6 +197,10 @@ export let Fiber = class Fiber {
                                 i++;
                         }
                     }
+                    else if (this.autoTerminate) {
+                        this.cancel();
+                        break;
+                    }
                     const res = this.gen ? this.gen.next(this) : NO_RESULT;
                     if (res.done)
                         this.done(res.value);
@@ -206,8 +221,7 @@ export let Fiber = class Fiber {
     deinit() {
         this.logger?.debug("deinit", this.id);
         this.user?.deinit?.(this);
-        if (this.children)
-            this.children = undefined;
+        this.children.length = 0;
         this.gen = null;
     }
     /**
@@ -221,10 +235,8 @@ export let Fiber = class Fiber {
         if (!this.isActive())
             return;
         this.logger?.debug("cancel", this.id);
-        if (this.children) {
-            for (let child of this.children)
-                child.cancel();
-        }
+        for (let child of this.children)
+            child.cancel();
         this.deinit();
         this.state = STATE_CANCELED;
         this.idgen?.free(this.id);
@@ -245,10 +257,8 @@ export let Fiber = class Fiber {
             return;
         this.logger?.debug("done", this.id, value);
         this.value = value;
-        if (this.children) {
-            for (let child of this.children)
-                child.done();
-        }
+        for (let child of this.children)
+            child.done();
         this.deinit();
         this.state = STATE_DONE;
         this.idgen?.free(this.id);
@@ -272,10 +282,8 @@ export let Fiber = class Fiber {
         this.logger
             ? this.logger.severe(`error ${this.id}:`, err)
             : console.warn(`error ${this.id}:`, err);
-        if (this.children) {
-            for (let child of this.children)
-                child.cancel();
-        }
+        for (let child of this.children)
+            child.cancel();
         this.state = STATE_ERROR;
         this.error = err;
         this.deinit();
@@ -334,7 +342,7 @@ export let Fiber = class Fiber {
         return this;
     }
 };
-Fiber = __decorate([
+Fiber = Fiber_1 = __decorate([
     INotifyMixin
 ], Fiber);
 /**

package/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./api.js";
+export * from "./csp.js";
 export * from "./fiber.js";
 export * from "./ops.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,3 +1,4 @@
 export * from "./api.js";
+export * from "./csp.js";
 export * from "./fiber.js";
 export * from "./ops.js";

package/ops.d.ts

@@ -1,5 +1,6 @@
 import type { Fn0, Predicate } from "@thi.ng/api";
-import { type FiberFactory, type FiberOpts, type MaybeFiber } from "./api.js";
+import type { IRandom } from "@thi.ng/random";
+import { type FiberOpts, type MaybeFiber, type State } from "./api.js";
 import { Fiber } from "./fiber.js";
 /**
  * Returns co-routine which "blocks" for given number of milliseconds or
@@ -21,7 +22,7 @@ export declare function waitFrames(delay: number): Generator<undefined, void, un
  * @param fibers
  * @param opts
  */
-export declare const sequence: (fibers: Iterable<Fiber | FiberFactory | Generator>, opts?: Partial<FiberOpts>) => Fiber<unknown>;
+export declare const sequence: (fibers: Iterable<MaybeFiber>, opts?: Partial<FiberOpts>) => Fiber<unknown>;
 /**
  * Returns a fiber which executes given fibers as child processes until **one**
  * of them is finished/terminated. That child fiber itself will be the result.
@@ -44,7 +45,7 @@ export declare const sequence: (fibers: Iterable<Fiber | FiberFactory | Generato
  * @param fibers
  * @param opts
  */
-export declare const first: (fibers: (Fiber | FiberFactory | Generator)[], opts?: Partial<FiberOpts>) => Fiber<Fiber<any>>;
+export declare const first: (fibers: Iterable<MaybeFiber>, opts?: Partial<FiberOpts>) => Fiber<Fiber<any>>;
 /**
  * Returns a fiber which executes given fibers as child processes until **all**
  * of them are finished/terminated.
@@ -55,7 +56,7 @@ export declare const first: (fibers: (Fiber | FiberFactory | Generator)[], opts?
  * @param fibers
  * @param opts
  */
-export declare const all: (fibers: MaybeFiber[], opts?: Partial<FiberOpts>) => Fiber<void>;
+export declare const all: (fibers: Iterable<MaybeFiber>, opts?: Partial<FiberOpts>) => Fiber<void>;
 /**
  * Syntax sugar common use cases of {@link first} where a child fiber should be
  * limited to a max. time period before giving up.
@@ -68,11 +69,11 @@ export declare const all: (fibers: MaybeFiber[], opts?: Partial<FiberOpts>) => F
  * if (res.deref() != null) { ... }
  * ```
  *
- * @param fiber
+ * @param body
  * @param timeout
  * @param opts
  */
-export declare const withTimeout: (fiber: MaybeFiber, timeout: number, opts?: Partial<FiberOpts>) => Fiber<Fiber<any>>;
+export declare const withTimeout: (body: MaybeFiber, timeout: number, opts?: Partial<FiberOpts>) => Fiber<Fiber<any>>;
 /**
  * Higher-order fiber which repeatedly executes given `fiber` until its
  * completion, but does so in a time-sliced manner, such that the fiber never
@@ -82,7 +83,7 @@ export declare const withTimeout: (fiber: MaybeFiber, timeout: number, opts?: Pa
  * @param maxTime
  * @param opts
  */
-export declare const timeSlice: (body: Fiber | FiberFactory | Generator, maxTime: number, opts?: Partial<FiberOpts>) => Fiber<void>;
+export declare const timeSlice: (body: MaybeFiber, maxTime: number, opts?: Partial<FiberOpts>) => Fiber<void>;
 /**
  * Returns a fiber which "blocks" until given predicate function returns true.
  *
@@ -127,4 +128,55 @@ export declare const untilPromise: <T>(promise: PromiseLike<T>) => Fiber<T>;
  * @param opts
  */
 export declare const untilEvent: (target: EventTarget, type: string, opts?: Partial<FiberOpts>) => Fiber<unknown>;
+/**
+ * Custom fiber implementation for {@link shuffle}.
+ */
+export declare class Shuffle extends Fiber {
+    rnd: IRandom;
+    constructor(fibers: Iterable<MaybeFiber>, opts?: Partial<FiberOpts & {
+        rnd: IRandom;
+    }>);
+    next(): State;
+}
+/**
+ * Higher-order fiber for creating a constantly randomized execution order of
+ * given `fibers`, e.g. for distributing workloads. Creates and returns a new
+ * fiber as parent of the given `fibers` which then shuffles their execution
+ * order on each {@link Fiber.next} invocation/update. The fiber terminates when
+ * all children are done.
+ *
+ * @remarks
+ * The `rnd` option can be used to customize the
+ * [`IRandom`](https://docs.thi.ng/umbrella/random/interfaces/IRandom.html)
+ * implementation used for shuffling. Defaults to
+ * [`SYSTEM`](https://docs.thi.ng/umbrella/random/variables/SYSTEM.html).
+ *
+ * @example
+ * ```ts
+ * import { repeatedly } from "@thi.ng/transducers";
+ *
+ * // create & run fiber with 4 children, executing in random order
+ * shuffle(
+ *   repeatedly(
+ *     (id) => function*() { while(true) { console.log(`worker #{id}`); yield; } },
+ *     4
+ *   )
+ * ).run()
+ *
+ * // worker #0
+ * // worker #1
+ * // worker #3
+ * // worker #3
+ * // worker #2
+ * // worker #0
+ * // worker #2
+ * // ...
+ * ```
+ *
+ * @param fibers
+ * @param opts
+ */
+export declare const shuffle: (fibers: Iterable<MaybeFiber>, opts?: Partial<FiberOpts & {
+    rnd: IRandom;
+}>) => Shuffle;
 //# sourceMappingURL=ops.d.ts.map

package/ops.js

@@ -1,4 +1,6 @@
+import { shuffle as $shuffle } from "@thi.ng/arrays/shuffle";
 import { now, timeDiff } from "@thi.ng/bench/now";
+import { SYSTEM } from "@thi.ng/random/system";
 import { STATE_ACTIVE, STATE_DONE, STATE_ERROR, } from "./api.js";
 import { Fiber, fiber } from "./fiber.js";
 /**
@@ -65,7 +67,7 @@ export const sequence = (fibers, opts) => fiber(function* (ctx) {
  * @param opts
  */
 export const first = (fibers, opts) => fiber(function* (ctx) {
-    const $fibers = fibers.map((f) => ctx.fork(f));
+    const $fibers = [...fibers].map((f) => ctx.fork(f));
     while (true) {
         for (let f of $fibers) {
             if (!f.isActive())
@@ -85,8 +87,7 @@ export const first = (fibers, opts) => fiber(function* (ctx) {
  * @param opts
  */
 export const all = (fibers, opts) => fiber((ctx) => {
-    for (let f of fibers)
-        ctx.fork(f);
+    ctx.forkAll(...fibers);
     return ctx.join();
 }, opts);
 /**
@@ -101,11 +102,11 @@ export const all = (fibers, opts) => fiber((ctx) => {
  * if (res.deref() != null) { ... }
  * ```
  *
- * @param fiber
+ * @param body
  * @param timeout
  * @param opts
  */
-export const withTimeout = (fiber, timeout, opts) => first([fiber, wait(timeout)], opts);
+export const withTimeout = (body, timeout, opts) => first([body, wait(timeout)], opts);
 /**
  * Higher-order fiber which repeatedly executes given `fiber` until its
  * completion, but does so in a time-sliced manner, such that the fiber never
@@ -196,3 +197,58 @@ export const untilEvent = (target, type, opts) => {
         },
     });
 };
+/**
+ * Custom fiber implementation for {@link shuffle}.
+ */
+export class Shuffle extends Fiber {
+    constructor(fibers, opts) {
+        super((ctx) => ctx.join(), opts);
+        this.rnd = opts?.rnd || SYSTEM;
+        this.forkAll(...fibers);
+    }
+    next() {
+        if (!this.isActive())
+            return this.state;
+        $shuffle(this.children, this.children.length, this.rnd);
+        return super.next();
+    }
+}
+/**
+ * Higher-order fiber for creating a constantly randomized execution order of
+ * given `fibers`, e.g. for distributing workloads. Creates and returns a new
+ * fiber as parent of the given `fibers` which then shuffles their execution
+ * order on each {@link Fiber.next} invocation/update. The fiber terminates when
+ * all children are done.
+ *
+ * @remarks
+ * The `rnd` option can be used to customize the
+ * [`IRandom`](https://docs.thi.ng/umbrella/random/interfaces/IRandom.html)
+ * implementation used for shuffling. Defaults to
+ * [`SYSTEM`](https://docs.thi.ng/umbrella/random/variables/SYSTEM.html).
+ *
+ * @example
+ * ```ts
+ * import { repeatedly } from "@thi.ng/transducers";
+ *
+ * // create & run fiber with 4 children, executing in random order
+ * shuffle(
+ *   repeatedly(
+ *     (id) => function*() { while(true) { console.log(`worker #{id}`); yield; } },
+ *     4
+ *   )
+ * ).run()
+ *
+ * // worker #0
+ * // worker #1
+ * // worker #3
+ * // worker #3
+ * // worker #2
+ * // worker #0
+ * // worker #2
+ * // ...
+ * ```
+ *
+ * @param fibers
+ * @param opts
+ */
+export const shuffle = (fibers, opts) => new Shuffle(fibers, opts);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/fibers",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Process hierarchies & operators for cooperative multitasking",
   "type": "module",
   "module": "./index.js",
@@ -34,16 +34,18 @@
     "test": "testament test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.9.0",
-    "@thi.ng/bench": "^3.4.1",
-    "@thi.ng/checks": "^3.4.0",
-    "@thi.ng/errors": "^2.3.0",
-    "@thi.ng/idgen": "^2.2.0",
-    "@thi.ng/logger": "^1.4.16"
+    "@thi.ng/api": "^8.9.2",
+    "@thi.ng/arrays": "^2.5.17",
+    "@thi.ng/bench": "^3.4.3",
+    "@thi.ng/checks": "^3.4.2",
+    "@thi.ng/errors": "^2.3.2",
+    "@thi.ng/idgen": "^2.2.2",
+    "@thi.ng/logger": "^1.4.18",
+    "@thi.ng/random": "^3.5.3"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.36.3",
-    "@thi.ng/testament": "^0.3.18",
+    "@thi.ng/testament": "^0.3.20",
     "rimraf": "^5.0.1",
     "tools": "^0.0.1",
     "typedoc": "^0.24.8",
@@ -73,6 +75,9 @@
     "./api": {
       "default": "./api.js"
     },
+    "./csp": {
+      "default": "./csp.js"
+    },
     "./fiber": {
       "default": "./fiber.js"
     },
@@ -84,5 +89,5 @@
     "status": "alpha",
     "year": 2023
   },
-  "gitHead": "fdea6ba9d36111f7346827ed81e7549f10343a13\n"
+  "gitHead": "ad9ac3232c6fc5fc8a0df75ac82fc1e0e9fb0258\n"
 }