@pipedog/asyncio 0.1.0 → 0.2.0

package/dist/primitives.js

@@ -1,9 +1,13 @@
 // Copyright (c) 2026, pipedog contributors
 // SPDX-License-Identifier: BSD-2-Clause
 //
-// asyncio synchronization primitives and helpers. Every wait here is a
-// cancellation point (see task.ts). Durations are in seconds, as in Python.
-import { CancelledError, createTask, currentTask, suspend, Task, TimeoutError, } from "./task.js";
+// asyncio synchronization primitives and helpers, ported from CPython's
+// asyncio (locks.py, queues.py, tasks.py, timeouts.py) on top of Future, so
+// they wake waiters exactly as asyncio does: through the ready queue, never
+// synchronously. Every wait here is a cancellation point (see task.ts).
+// Durations are in seconds, as in Python.
+import { callLater, callSoon } from "./loop.js";
+import { abortable, awaitFuture, CancelledError, createTask, currentTask, Future, TimeoutError, } from "./task.js";
 /** Monotonic time in seconds (loop.time()). */
 export function monotonic() {
     return performance.now() / 1000;
@@ -24,47 +28,75 @@ export function time() {
     const origin = performance.timeOrigin;
     return origin ? (origin + performance.now()) / 1000 : Date.now() / 1000;
 }
-/** asyncio.sleep(seconds). `sleep(0)` yields to other tasks. */
+function remove(items, item) {
+    const i = items.indexOf(item);
+    if (i < 0)
+        return false;
+    items.splice(i, 1);
+    return true;
+}
+/**
+ * asyncio.sleep(seconds). `sleep(0)` yields once: the task goes to the back
+ * of the ready queue, so everything already scheduled runs first.
+ */
 export function sleep(seconds) {
-    return suspend((resolve) => {
-        const timer = setTimeout(resolve, Math.max(0, seconds * 1000));
-        return () => clearTimeout(timer);
+    if (!(seconds > 0))
+        return sleep0();
+    const future = new Future();
+    const handle = callLater(seconds, () => {
+        if (!future.done())
+            future.setResult(undefined);
+    });
+    const done = awaitFuture(future);
+    done.then(() => handle.cancel(), () => handle.cancel());
+    return done;
+}
+/** A bare `yield` in a task: reschedule it at the back of the ready queue. */
+function sleep0() {
+    const task = currentTask();
+    return new Promise((resolve, reject) => {
+        callSoon(() => {
+            const cancelled = task?._takeCancelRequest();
+            if (cancelled)
+                reject(cancelled);
+            else
+                resolve();
+        });
     });
 }
 /** asyncio.Event */
 export class Event {
-    #set = false;
-    #waiters = new Set();
+    #value = false;
+    #waiters = [];
     isSet() {
-        return this.#set;
+        return this.#value;
     }
     set() {
-        if (this.#set)
+        if (this.#value)
             return;
-        this.#set = true;
-        const waiters = [...this.#waiters];
-        this.#waiters.clear();
-        for (const waiter of waiters)
-            waiter();
+        this.#value = true;
+        for (const future of this.#waiters) {
+            if (!future.done())
+                future.setResult(true);
+        }
     }
     clear() {
-        this.#set = false;
+        this.#value = false;
     }
-    wait() {
-        if (this.#set) {
-            try {
-                currentTask()?.checkpoint();
-            }
-            catch (e) {
-                return Promise.reject(e);
-            }
-            return Promise.resolve(true);
+    async wait() {
+        if (this.#value) {
+            currentTask()?.checkpoint();
+            return true;
+        }
+        const future = new Future();
+        this.#waiters.push(future);
+        try {
+            await future;
+            return true;
+        }
+        finally {
+            remove(this.#waiters, future);
         }
-        return suspend((resolve) => {
-            const waiter = () => resolve(true);
-            this.#waiters.add(waiter);
-            return () => this.#waiters.delete(waiter);
-        });
     }
 }
 export class QueueEmpty extends Error {
@@ -77,7 +109,7 @@ export class QueueShutDown extends Error {
     name = "QueueShutDown";
 }
 /**
- * asyncio.Queue. Subclasses override `_init/_put/_get/_size/_items` to change
+ * asyncio.Queue. Subclasses override `_init/_put/_get/_size` to change
  * ordering, as Python's PriorityQueue and LifoQueue do.
  */
 export class Queue {
@@ -92,19 +124,47 @@ export class Queue {
         this._init();
         this.#finished.set();
     }
-    // Storage hooks.
+    // Storage hooks. FIFO storage is `_items` from index `_head` on: a deque
+    // (collections.deque in Python), since Array.shift() is O(n) on V8.
     _items = [];
+    _head = 0;
     _init() {
         this._items = [];
+        this._head = 0;
     }
     _put(item) {
         this._items.push(item);
     }
     _get() {
-        return this._items.shift();
+        const items = this._items;
+        const item = items[this._head];
+        items[this._head] = undefined;
+        this._head++;
+        if (this._head === items.length) {
+            items.length = 0;
+            this._head = 0;
+        }
+        else if (this._head >= 1024 && this._head * 2 >= items.length) {
+            items.splice(0, this._head);
+            this._head = 0;
+        }
+        return item;
     }
     _size() {
-        return this._items.length;
+        return this._items.length - this._head;
+    }
+    /** The queued items in storage order (for subclasses that inspect them). */
+    _queued() {
+        return this._head === 0 ? this._items : this._items.slice(this._head);
+    }
+    #wakeupNext(waiters) {
+        while (waiters.length > 0) {
+            const waiter = waiters.shift();
+            if (!waiter.done()) {
+                waiter.setResult(undefined);
+                break;
+            }
+        }
     }
     qsize() {
         return this._size();
@@ -122,14 +182,19 @@ export class Queue {
         while (this.full()) {
             if (this.#shutdown)
                 throw new QueueShutDown();
-            await suspend((resolve) => {
-                this.#putters.push(resolve);
-                return () => {
-                    const i = this.#putters.indexOf(resolve);
-                    if (i >= 0)
-                        this.#putters.splice(i, 1);
-                };
-            });
+            const putter = new Future();
+            this.#putters.push(putter);
+            try {
+                await putter;
+            }
+            catch (e) {
+                putter.cancel();
+                remove(this.#putters, putter);
+                // Woken up by getNowait() but can't take the slot: pass it on.
+                if (!this.full() && !putter.cancelled())
+                    this.#wakeupNext(this.#putters);
+                throw e;
+            }
         }
         this.putNowait(item);
     }
@@ -141,26 +206,29 @@ export class Queue {
         this._put(item);
         this.#unfinished++;
         this.#finished.clear();
-        this.#wakeGetter();
+        this.#wakeupNext(this.#getters);
     }
     async get() {
-        if (!this.empty() && this.#getters.length === 0) {
+        if (!this.empty())
             currentTask()?.checkpoint();
-            return this.getNowait();
-        }
-        if (this.#shutdown && this.empty())
-            throw new QueueShutDown();
-        return suspend((resolve, reject) => {
-            const getter = { resolve, reject };
+        while (this.empty()) {
+            if (this.#shutdown && this.empty())
+                throw new QueueShutDown();
+            const getter = new Future();
             this.#getters.push(getter);
-            // Item may already be available if getters were queued before us.
-            this.#wakeGetter();
-            return () => {
-                const i = this.#getters.indexOf(getter);
-                if (i >= 0)
-                    this.#getters.splice(i, 1);
-            };
-        });
+            try {
+                await getter;
+            }
+            catch (e) {
+                getter.cancel();
+                remove(this.#getters, getter);
+                // Woken up by putNowait() but can't take the item: pass it on.
+                if (!this.empty() && !getter.cancelled())
+                    this.#wakeupNext(this.#getters);
+                throw e;
+            }
+        }
+        return this.getNowait();
     }
     getNowait() {
         if (this.empty()) {
@@ -169,7 +237,7 @@ export class Queue {
             throw new QueueEmpty();
         }
         const item = this._get();
-        this.#wakePutter();
+        this.#wakeupNext(this.#putters);
         return item;
     }
     taskDone() {
@@ -194,22 +262,15 @@ export class Queue {
             if (this.#unfinished === 0)
                 this.#finished.set();
         }
-        for (const getter of this.#getters.splice(0))
-            getter.reject(new QueueShutDown());
-        for (const putter of this.#putters.splice(0))
-            putter();
-    }
-    #wakeGetter() {
-        while (this.#getters.length > 0 && !this.empty()) {
-            const getter = this.#getters.shift();
-            const item = this._get();
-            getter.resolve(item);
-            this.#wakePutter();
+        // All getters need to re-check queue-empty to raise QueueShutDown.
+        for (const getter of this.#getters.splice(0)) {
+            if (!getter.done())
+                getter.setResult(undefined);
+        }
+        for (const putter of this.#putters.splice(0)) {
+            if (!putter.done())
+                putter.setResult(undefined);
         }
-    }
-    #wakePutter() {
-        const putter = this.#putters.shift();
-        putter?.();
     }
 }
 /** asyncio.LifoQueue */
@@ -289,23 +350,32 @@ export class PriorityQueue extends Queue {
 /** asyncio.Lock */
 export class Lock {
     #locked = false;
-    #waiters = [];
+    #waiters = null;
     locked() {
         return this.#locked;
     }
     async acquire() {
-        if (!this.#locked && this.#waiters.length === 0) {
+        if (!this.#locked && (this.#waiters === null || this.#waiters.every((w) => w.cancelled()))) {
             this.#locked = true;
             return true;
         }
-        await suspend((resolve) => {
-            this.#waiters.push(resolve);
-            return () => {
-                const i = this.#waiters.indexOf(resolve);
-                if (i >= 0)
-                    this.#waiters.splice(i, 1);
-            };
-        });
+        this.#waiters ??= [];
+        const future = new Future();
+        this.#waiters.push(future);
+        try {
+            try {
+                await future;
+            }
+            finally {
+                remove(this.#waiters, future);
+            }
+        }
+        catch (e) {
+            // If the lock is free, make sure the next waiter in line runs.
+            if (e instanceof CancelledError && !this.#locked)
+                this.#wakeUpFirst();
+            throw e;
+        }
         this.#locked = true;
         return true;
     }
@@ -313,13 +383,13 @@ export class Lock {
         if (!this.#locked)
             throw new Error("Lock is not acquired.");
         this.#locked = false;
-        const next = this.#waiters.shift();
-        if (next) {
-            // Hand over directly so no one can barge in.
-            this.#locked = true;
-            next();
-            // `acquire` sets locked again after resuming; keep it consistent.
-        }
+        this.#wakeUpFirst();
+    }
+    #wakeUpFirst() {
+        const first = this.#waiters?.[0];
+        // done() means that the waiter is already set to wake up.
+        if (first && !first.done())
+            first.setResult(true);
     }
     /** `async with lock:` → `await lock.run(async () => {...})` */
     async run(fn) {
@@ -335,34 +405,64 @@ export class Lock {
 /** asyncio.Semaphore */
 export class Semaphore {
     #value;
-    #waiters = [];
+    #waiters = null;
     constructor(value = 1) {
+        if (value < 0)
+            throw new RangeError("Semaphore initial value must be >= 0");
         this.#value = value;
     }
+    /** Due to state, or FIFO rules (must allow others to run first). */
     locked() {
-        return this.#value === 0;
+        return this.#value === 0 || (this.#waiters ?? []).some((w) => !w.cancelled());
     }
     async acquire() {
-        if (this.#value > 0 && this.#waiters.length === 0) {
+        if (!this.locked()) {
+            // Maintain FIFO, wait for others to start even if value > 0.
             this.#value--;
             return true;
         }
-        await suspend((resolve) => {
-            this.#waiters.push(resolve);
-            return () => {
-                const i = this.#waiters.indexOf(resolve);
-                if (i >= 0)
-                    this.#waiters.splice(i, 1);
-            };
-        });
+        this.#waiters ??= [];
+        const future = new Future();
+        this.#waiters.push(future);
+        try {
+            try {
+                await future;
+            }
+            finally {
+                remove(this.#waiters, future);
+            }
+        }
+        catch (e) {
+            if (e instanceof CancelledError && future.done() && !future.cancelled()) {
+                // Woken up by #wakeUpNext() but not acquiring: undo its bookkeeping.
+                this.#value++;
+            }
+            throw e;
+        }
+        finally {
+            // New waiters may have arrived but had to wait due to FIFO.
+            while (this.#value > 0) {
+                if (!this.#wakeUpNext())
+                    break;
+            }
+        }
         return true;
     }
     release() {
-        const next = this.#waiters.shift();
-        if (next)
-            next();
-        else
-            this.#value++;
+        this.#value++;
+        this.#wakeUpNext();
+    }
+    #wakeUpNext() {
+        if (!this.#waiters)
+            return false;
+        for (const future of this.#waiters) {
+            if (!future.done()) {
+                this.#value--;
+                future.setResult(true);
+                return true;
+            }
+        }
+        return false;
     }
     async run(fn) {
         await this.acquire();
@@ -374,63 +474,197 @@ export class Semaphore {
         }
     }
 }
-function toTask(aw, name) {
-    if (aw instanceof Task)
+/** asyncio.ensure_future: functions and foreign promises run as tasks. */
+function ensureFuture(aw, name) {
+    if (aw instanceof Future)
         return aw;
     if (typeof aw === "function")
         return createTask(aw, name);
     return createTask(() => aw, name);
 }
+/** Await `aw` in the current task, as `await aw` would in Python. */
+function awaitInline(aw) {
+    if (aw instanceof Future)
+        return awaitFuture(aw);
+    if (typeof aw === "function")
+        return aw();
+    // A foreign promise: make the wait cancellable.
+    return abortable(aw);
+}
+/** tasks._cancel_and_wait: cancel `future` and wait until it is done. */
+async function cancelAndWait(future) {
+    const waiter = new Future();
+    const release = () => {
+        if (!waiter.done())
+            waiter.setResult(undefined);
+    };
+    future.addDoneCallback(release);
+    try {
+        future.cancel();
+        // Not waiting on `future` directly keeps this reliably cancellable.
+        await waiter;
+    }
+    finally {
+        future.removeDoneCallback(release);
+    }
+}
 /**
- * asyncio.wait_for(aw, timeout). Pass a function (a "coroutine") so it can
- * run as a child task that is cancelled on timeout. `timeout` null waits forever.
+ * asyncio.timeout(seconds) around `fn`, run in the current task: on expiry
+ * the task is cancelled and the CancelledError becomes TimeoutError
+ * (timeouts.Timeout). `seconds` null never expires.
  */
-export async function waitFor(aw, timeout) {
-    const child = toTask(aw, "wait_for");
-    if (timeout === null || timeout === undefined)
-        return await child;
-    let timedOut = false;
-    const timer = setTimeout(() => {
-        timedOut = true;
-        child.cancel();
-    }, Math.max(0, timeout * 1000));
+async function withTimeout(seconds, fn) {
+    const task = currentTask();
+    if (!task) {
+        // asyncio.timeout() needs a task; give it one.
+        return await createTask(() => withTimeout(seconds, fn), "timeout");
+    }
+    let expiring = false;
+    const cancelling = task.cancelling();
+    let handle = null;
+    if (seconds !== null && seconds !== undefined) {
+        const onTimeout = () => {
+            task.cancel();
+            expiring = true;
+            handle = null;
+        };
+        handle = seconds <= 0 ? callSoon(onTimeout) : callLater(seconds, onTimeout);
+    }
+    let result;
     try {
-        return await child;
+        result = await fn();
     }
     catch (e) {
-        if (timedOut && e instanceof CancelledError && !(currentTask()?.cancelling() ?? 0)) {
+        handle?.cancel();
+        if (expiring && task.uncancel() <= cancelling && e instanceof CancelledError) {
             throw new TimeoutError();
         }
         throw e;
     }
-    finally {
-        clearTimeout(timer);
+    handle?.cancel();
+    if (expiring)
+        task.uncancel();
+    return result;
+}
+/**
+ * asyncio.wait_for(aw, timeout). A function (a "coroutine") or a foreign
+ * promise is awaited in the current task, a Task is awaited (and cancelled on
+ * timeout). `timeout` null waits forever.
+ */
+export async function waitFor(aw, timeout) {
+    if (timeout !== null && timeout !== undefined && timeout <= 0) {
+        const future = ensureFuture(aw, "wait_for");
+        if (future.done())
+            return future.result();
+        await cancelAndWait(future);
+        try {
+            return future.result();
+        }
+        catch (e) {
+            if (e instanceof CancelledError)
+                throw new TimeoutError();
+            throw e;
+        }
     }
+    return await withTimeout(timeout, () => awaitInline(aw));
+}
+/**
+ * asyncio.timeout(seconds) as a scope: runs `fn` and cancels it on timeout,
+ * raising TimeoutError.
+ */
+export function timeout(seconds, fn) {
+    return withTimeout(seconds, fn);
+}
+/** tasks._GatheringFuture: cancelling it cancels the children. */
+class GatheringFuture extends Future {
+    #children;
+    cancelRequested = false;
+    constructor(children) {
+        super();
+        this.#children = children;
+    }
+    cancel(message) {
+        if (this.done())
+            return false;
+        let cancelled = false;
+        for (const child of this.#children) {
+            if (child.cancel(message))
+                cancelled = true;
+        }
+        // Propagate the cancellation once the children are done.
+        if (cancelled)
+            this.cancelRequested = true;
+        return cancelled;
+    }
+}
+function gatherFuture(aws, returnExceptions) {
+    if (aws.length === 0) {
+        const outer = new Future();
+        outer.setResult([]);
+        return outer;
+    }
+    const children = [];
+    const doneFutures = [];
+    const seen = new Map();
+    let nfutures = 0;
+    let nfinished = 0;
+    let outer = null;
+    const onDone = (future) => {
+        nfinished++;
+        if (outer === null || outer.done())
+            return;
+        if (!returnExceptions) {
+            if (future.cancelled()) {
+                outer.setException(future._makeCancelledError());
+                return;
+            }
+            const error = future.exception();
+            if (error !== undefined) {
+                outer.setException(error);
+                return;
+            }
+        }
+        if (nfinished === nfutures) {
+            const results = children.map((child) => {
+                if (child.cancelled())
+                    return child._makeCancelledError();
+                const error = child.exception();
+                return error !== undefined ? error : child.result();
+            });
+            if (outer.cancelRequested)
+                outer.setException(future._makeCancelledError());
+            else
+                outer.setResult(results);
+        }
+    };
+    for (const aw of aws) {
+        let future = seen.get(aw);
+        if (!future) {
+            future = ensureFuture(aw);
+            nfutures++;
+            seen.set(aw, future);
+            if (future.done())
+                doneFutures.push(future);
+            else
+                future.addDoneCallback(onDone);
+        }
+        children.push(future);
+    }
+    outer = new GatheringFuture(children);
+    for (const future of doneFutures)
+        onDone(future);
+    return outer;
 }
 /**
  * asyncio.gather(*aws). Functions run as child tasks; if the caller is
  * cancelled, all children are cancelled.
  */
-export async function gather(...aws) {
-    const tasks = aws.map((aw) => toTask(aw));
-    return (await suspend((resolve, reject) => {
-        Promise.all(tasks.map((t) => t.promise)).then(resolve, reject);
-        return () => { };
-    }, () => {
-        for (const t of tasks)
-            t.cancel();
-    }));
+export function gather(...aws) {
+    return awaitFuture(gatherFuture(aws, false));
 }
 /** asyncio.gather(*aws, return_exceptions=True) */
-export async function gatherSettled(...aws) {
-    const tasks = aws.map((aw) => toTask(aw));
-    return await suspend((resolve) => {
-        Promise.allSettled(tasks.map((t) => t.promise)).then((results) => resolve(results.map((r) => (r.status === "fulfilled" ? r.value : r.reason))));
-        return () => { };
-    }, () => {
-        for (const t of tasks)
-            t.cancel();
-    });
+export function gatherSettled(...aws) {
+    return awaitFuture(gatherFuture(aws, true));
 }
 export const FIRST_COMPLETED = "FIRST_COMPLETED";
 export const FIRST_EXCEPTION = "FIRST_EXCEPTION";
@@ -439,54 +673,74 @@ export const ALL_COMPLETED = "ALL_COMPLETED";
  * asyncio.wait(tasks, timeout, return_when). Does not cancel anything on
  * timeout. Returns [done, pending].
  */
-export function wait(tasks, options = {}) {
-    const all = [...tasks];
+export async function wait(tasks, options = {}) {
+    const all = [...new Set(tasks)];
     const returnWhen = options.returnWhen ?? ALL_COMPLETED;
-    const result = () => [
-        new Set(all.filter((t) => t.done())),
-        new Set(all.filter((t) => !t.done())),
-    ];
-    return suspend((resolve) => {
-        let timer;
-        const check = () => {
-            const done = all.filter((t) => t.done());
-            const finished = done.length === all.length ||
-                (returnWhen === FIRST_COMPLETED && done.length > 0) ||
-                (returnWhen === FIRST_EXCEPTION &&
-                    done.some((t) => !t.cancelled() && t.exception() !== undefined));
-            if (finished) {
-                if (timer)
-                    clearTimeout(timer);
-                resolve(result());
-            }
-        };
-        for (const t of all)
-            t.addDoneCallback(check);
+    if (all.length > 0) {
+        const waiter = new Future();
+        let timeoutHandle = null;
         if (options.timeout !== undefined && options.timeout !== null) {
-            timer = setTimeout(() => resolve(result()), options.timeout * 1000);
-        }
-        check();
-        return () => {
-            if (timer)
-                clearTimeout(timer);
-            for (const t of all)
-                t.removeDoneCallback(check);
+            timeoutHandle = callLater(options.timeout, () => {
+                if (!waiter.done())
+                    waiter.setResult(undefined);
+            });
+        }
+        let counter = all.length;
+        const onCompletion = (future) => {
+            counter--;
+            if (counter <= 0 ||
+                returnWhen === FIRST_COMPLETED ||
+                (returnWhen === FIRST_EXCEPTION && !future.cancelled() && future.exception() !== undefined)) {
+                timeoutHandle?.cancel();
+                if (!waiter.done())
+                    waiter.setResult(undefined);
+            }
         };
-    });
-}
-/**
- * asyncio.timeout(seconds) as a scope: runs `fn` and cancels it on timeout,
- * raising TimeoutError.
- */
-export function timeout(seconds, fn) {
-    return waitFor(fn, seconds);
+        for (const future of all)
+            future.addDoneCallback(onCompletion);
+        try {
+            await waiter;
+        }
+        finally {
+            timeoutHandle?.cancel();
+            for (const future of all)
+                future.removeDoneCallback(onCompletion);
+        }
+    }
+    const done = new Set();
+    const pending = new Set();
+    for (const future of all)
+        (future.done() ? done : pending).add(future);
+    return [done, pending];
 }
 /** asyncio.shield(aw): the caller can be cancelled without cancelling `aw`. */
 export function shield(aw) {
-    const task = toTask(aw);
-    return suspend((resolve, reject) => {
-        task.promise.then(resolve, reject);
-        return () => { };
+    const inner = ensureFuture(aw);
+    if (inner.done())
+        return awaitFuture(inner);
+    const outer = new Future();
+    const onInnerDone = () => {
+        if (outer.cancelled())
+            return;
+        if (inner.cancelled()) {
+            outer.cancel();
+            return;
+        }
+        const error = inner.exception();
+        if (error !== undefined)
+            outer.setException(error);
+        else
+            outer.setResult(inner.result());
+    };
+    inner.addDoneCallback(onInnerDone);
+    outer.addDoneCallback(() => {
+        if (!inner.done())
+            inner.removeDoneCallback(onInnerDone);
     });
+    return awaitFuture(outer);
+}
+/** Whether `value` is a Future or Task (asyncio.isfuture). */
+export function isFuture(value) {
+    return value instanceof Future;
 }
 //# sourceMappingURL=primitives.js.map