ciorent 0.0.2 → 0.0.4

package/README.md

@@ -1,7 +1,6 @@
-# Ciorent
-A concurrency library.
+A low-overhead, cross-runtime concurrency library.
 
-## Example usage
+# Usage
 Pausing to prioritize an asynchronous task:
 ```ts
 import * as cio from 'ciorent';
@@ -10,7 +9,7 @@ import * as cio from 'ciorent';
 const task1 = async () => {
   let x = 0;
   for (let i = 0; i < (Math.random() + 15) * 1e7; i++) {
-    // Frequent pausing
+    // Occasional pausing
     if (i % 2e6 === 0)
       await cio.pause;
 
@@ -31,6 +30,14 @@ task1();
 task2();
 ```
 
+Sleep for a duration:
+```ts
+import * as cio from 'ciorent';
+
+await cio.sleep(1000);
+console.log('Slept for about 1s');
+```
+
 Go-like channels for synchronizations:
 ```ts
 import * as channel from 'ciorent/channel';
@@ -51,12 +58,15 @@ const run = async () => {
 };
 
 const log = async () => {
-  do {
+  while (true) {
     // Non-blocking
     const x = await channel.recieve(c);
-    if (x === channel.closed) break;
+
+    // If the channel has been closed
+    if (x === null) break;
+
     console.log('Recieved', x);
-  } while (true);
+  };
 }
 
 run();
@@ -65,3 +75,79 @@ log();
 // This runs first
 console.log('Starting...');
 ```
+
+## Latch
+Latch is a synchronization tool that works like a gate, pausing tasks until the latch is opened.
+
+```ts
+import * as latch from 'ciorent/latch';
+import * as cio from 'ciorent';
+
+const fetchLatch = latch.init();
+
+const task = async () => {
+  // Blocks until the latch is open
+  await latch.pause(fetchLatch);
+
+  const res = await fetch('http://example.com');
+  console.log('Fetch status:', res.status);
+}
+
+const prepare = () => {
+  console.log('Run before fetch:', performance.now().toFixed(2));
+
+  // Unblock the latch
+  latch.open(fetchLatch);
+}
+
+const main = async () => {
+  const p = task();
+  await cio.sleep(500);
+  prepare();
+
+  return p;
+}
+
+// Run fetch after 500ms
+await main();
+
+// Re-close the latch
+latch.close(fetchLatch);
+
+// Run fetch after another 500ms
+await main();
+```
+
+If you don't need to close the latch again:
+```ts
+import * as latch from 'ciorent/latch';
+import * as cio from 'ciorent';
+
+const [pauseFetch, startFetch] = latch.init();
+
+const task = async () => {
+  // Blocks until the latch is open
+  await pauseFetch;
+
+  const res = await fetch('http://example.com');
+  console.log('Fetch status:', res.status);
+}
+
+const prepare = () => {
+  console.log('Run before fetch:', performance.now().toFixed(2));
+
+  // Unblock the latch
+  startFetch();
+}
+
+const main = async () => {
+  const p = task();
+  await cio.sleep(500);
+  prepare();
+
+  return p;
+}
+
+// Run fetch after 500ms
+await main();
+```

package/channel.d.ts

@@ -14,46 +14,47 @@ export interface Channel<T> {
     /**
      * The head of the value queue
      */
-    1: QueueNode<Promise<T | typeof closed>>;
+    1: QueueNode<T>;
     /**
      * The tail of the value queue
      */
-    2: QueueNode<Promise<T | typeof closed>>;
+    2: QueueNode<T>;
     /**
      * The head of the Promise resolve queue
      */
-    3: QueueNode<(value: Promise<T | typeof closed> | T | typeof closed) => void>;
+    3: QueueNode<(value: T | null) => void>;
     /**
      * The tail of the Promise resolve queue
      */
-    4: QueueNode<(value: Promise<T | typeof closed> | T | typeof closed) => void>;
+    4: QueueNode<(value: T | null) => void>;
 }
-/**
- * A signal that means the channel has closed
- */
-export declare const closed: unique symbol;
 /**
  * Create a channel
  */
-export declare const init: <T>() => Channel<T>;
+export declare const init: <T extends {}>() => Channel<T>;
 /**
  * Send a message to a channel
  * @param c - The channel to send to
  * @param t - The message to send
  */
-export declare const send: <T>(c: Channel<T>, t: Promise<T> | T) => void;
+export declare const send: <T>(c: Channel<T>, t: T) => void;
+/**
+ * Recieve a message from a channel, return null if the channel is closed
+ * @param c
+ */
+export declare const recieve: <T>(c: Channel<T>) => Promise<T | null>;
 /**
- * Recieve a message from a channel
+ * Recieve a message from a channel, return null if no message is currently in queue
  * @param c
  */
-export declare const recieve: <T>(c: Channel<T>) => Promise<T | typeof closed>;
+export declare const poll: <T>(c: Channel<T>) => T | null;
 /**
  * Close a channel
  * @param c
  */
 export declare const close: <T>(c: Channel<T>) => void;
 /**
- * Check whether a channel is still open yet
+ * Check whether a channel is still open
  * @param c
  */
 export declare const active: (c: Channel<any>) => boolean;

package/channel.js

@@ -1 +1 @@
-export let closed=Symbol();let closedPromise=Promise.resolve(closed);export let init=()=>{let qu=[null,null];let resolveQu=[null,null];return[true,qu,qu,resolveQu,resolveQu]};export let send=(c,t)=>{if(c[0]){if(c[4][1]!==null)(c[4]=c[4][1])[0](t);else c[1]=c[1][1]=[t instanceof Promise?t:Promise.resolve(t),null]}};export let recieve=(c)=>c[2][1]!==null?(c[2]=c[2][1])[0]:c[0]?new Promise((res)=>{c[3]=c[3][1]=[res,null]}):closedPromise;export let close=(c)=>{c[0]=false;while(c[4][1]!==null)(c[4]=c[4][1])[0](closed)};export let active=(c)=>c[0];
+let resolvedNull=Promise.resolve(null);export let init=()=>{let qu=[null,null];let resolveQu=[null,null];return[true,qu,qu,resolveQu,resolveQu]};export let send=(c,t)=>{if(c[0]){if(c[4][1]!==null)(c[4]=c[4][1])[0](t);else c[1]=c[1][1]=[t,null]}};export let recieve=(c)=>c[2][1]!==null?Promise.resolve((c[2]=c[2][1])[0]):c[0]?new Promise((res)=>{c[3]=c[3][1]=[res,null]}):resolvedNull;export let poll=(c)=>c[2][1]!==null?(c[2]=c[2][1])[0]:null;export let close=(c)=>{c[0]=false;while(c[4][1]!==null)(c[4]=c[4][1])[0](null)};export let active=(c)=>c[0];

package/index.d.ts

@@ -1,8 +1,17 @@
 /**
  * @module
- * Utilities for concurrency
+ * Other utilities
  */
 /**
- * Pause to run other tasks
+ * Continue running the function on next microtask.
+ *
+ * You can `await` this **occasionally** in an expensive synchronous operation to avoid
+ *
+ * blocking the main thread and let other asynchronous task to run.
  */
 export declare const pause: Promise<void>;
+/**
+ * Sleep for a duration
+ * @param ms - Sleep duration in milliseconds
+ */
+export declare const sleep: (ms: number) => Promise<void>;

package/index.js

@@ -1 +1 @@
-export let pause=Promise.resolve();
+export let pause=Promise.resolve();export let sleep=globalThis.Bun?.sleep??globalThis.process?.getBuiltinModule?.("timers/promises").setTimeout??((ms)=>new Promise((res)=>{setTimeout(res,ms)}));

package/latch.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @module
+ * Latches
+ */
+/**
+ * Describe a latch
+ */
+export interface Latch {
+    0: Promise<void>;
+    1: () => void;
+}
+/**
+ * Create a latch
+ */
+export declare const init: () => Latch;
+/**
+ * Pause until a latch is opened
+ */
+export declare const pause: (latch: Latch) => Promise<void>;
+/**
+ * Open a latch
+ */
+export declare const open: (latch: Latch) => void;
+/**
+ * Close a latch
+ */
+export declare const close: (latch: Latch) => void;

package/latch.js

@@ -0,0 +1 @@
+import{pause as endPromise}from".";export let init=()=>{let r;return[new Promise((res)=>{r=res}),r]};export let pause=(latch)=>latch[0];export let open=(latch)=>{latch[1]();latch[0]=endPromise};export let close=(latch)=>{if(latch[0]===endPromise){let r;latch[0]=new Promise((res)=>{r=res});latch[1]=r}};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ciorent",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "A concurrency library",
   "keywords": [],
   "license": "MIT",
@@ -12,7 +12,8 @@
     "build:test": "bun task build && bun test",
     "build:publish": "bun task build && bun task report-size && bun task publish",
     "lint": "eslint ./src",
-    "lint:fix": "eslint ./src --fix"
+    "lint:fix": "eslint ./src --fix",
+    "docs": "typedoc ./src/** --entryPointStrategy Expand --plugin typedoc-material-theme --skipErrorChecking"
   },
   "devDependencies": {
     "@stylistic/eslint-plugin": "latest",
@@ -23,6 +24,8 @@
     "mitata": "latest",
     "terser": "^5.39.0",
     "tsx": "latest",
+    "typedoc": "^0.27.9",
+    "typedoc-material-theme": "^1.3.0",
     "typescript": "latest",
     "typescript-eslint": "latest"
   }

package/queue/dropping.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @module
+ * Dropping queues
+ */
+import type { FixedQueue } from '.';
+export { default as init } from '.';
+export { pop } from './sliding';
+/**
+ * Push an item to a dropping queue
+ * @param q - The queue to push to
+ * @param item
+ */
+export declare const push: <T extends {}>(q: FixedQueue<T>, item: T) => boolean;

package/queue/dropping.js

@@ -0,0 +1 @@
+export{default as init}from".";export{pop}from"./sliding";export let push=(q,item)=>{if(q[0][(q[2]+1)%q[1]]!=null)return false;q[0][q[2]=(q[2]+1)%q[1]]=item;return true};

package/queue/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @module
+ * Queue utilities
+ */
+/**
+ * Describe a fixed-sized queue
+ */
+export interface FixedQueue<T extends {}> {
+    /**
+     * Pre-allocated queue
+     */
+    readonly 0: (T | undefined | null)[];
+    /**
+     * Queue capacity
+     */
+    readonly 1: number;
+    /**
+     * Head pointer
+     */
+    2: number;
+    /**
+     * Tail pointer
+     */
+    3: number;
+}
+/**
+ * Create a fixed queue.
+ * @param n - The queue size
+ */
+declare const _default: <T extends {}>(n: number) => FixedQueue<T>;
+export default _default;

package/queue/index.js

@@ -0,0 +1 @@
+export default (n)=>[new Array(n),n,-1,-1];

package/queue/sliding.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @module
+ * Sliding queues
+ */
+import type { FixedQueue } from '.';
+export { default as init } from '.';
+/**
+ * Push an item to a sliding queue
+ * @param q - The queue to push to
+ * @param item
+ */
+export declare const push: <T extends {}>(q: FixedQueue<T>, item: T) => void;
+/**
+ * Pop an item from the queue
+ * @param q - The queue to pull from
+ */
+export declare const pop: <T extends {}>(q: FixedQueue<T>) => T | undefined;

package/queue/sliding.js

@@ -0,0 +1 @@
+export{default as init}from".";export let push=(q,item)=>{q[0][q[2]=(q[2]+1)%q[1]]=item};export let pop=(q)=>{let val=q[0][(q[3]+1)%q[1]];if(val!=null){q[0][q[3]=(q[3]+1)%q[1]]=null;return val}};