ciorent 0.0.1 → 0.0.3

package/README.md

@@ -1,2 +1,103 @@
 # Ciorent
-A concurrency library.
+A low-overhead, cross-runtime concurrency library.
+
+## Example usage
+Pausing to prioritize an asynchronous task:
+```ts
+import * as cio from 'ciorent';
+
+// Expensive sync task
+const task1 = async () => {
+  let x = 0;
+  for (let i = 0; i < (Math.random() + 15) * 1e7; i++) {
+    // Occasional pausing
+    if (i % 2e6 === 0)
+      await cio.pause;
+
+    x += Math.random() * 32 + i * Math.round(Math.random() * 16);
+  }
+  console.log('Finish task 1:', x);
+};
+
+// Short async task
+const task2 = async () => {
+  console.log('Fetch start', performance.now().toFixed(2) + 'ms');
+  const txt = await fetch('http://example.com');
+  console.log('Fetch status', txt.status);
+};
+
+// Task 2 will not get blocked by task 1
+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';
+
+const c = channel.init<number>();
+const sleep = (ms: number) => new Promise((res) => setTimeout(res, ms));
+
+const run = async () => {
+  for (let i = 0; i < 10; i++) {
+    await sleep(10);
+    channel.send(c, i);
+    console.log('Sent', i);
+  }
+
+  // Send the closed signal to the reciever
+  // Or else channel.recieve will block forever
+  channel.close(c);
+};
+
+const log = async () => {
+  while (true) {
+    // Non-blocking
+    const x = await channel.recieve(c);
+
+    // If the channel has been closed
+    if (x === null) break;
+
+    console.log('Recieved', x);
+  };
+}
+
+run();
+log();
+
+// This runs first
+console.log('Starting...');
+```
+
+Latches:
+```ts
+import latch from 'ciorent/latch';
+
+const [startFetch, pauseFetch] = latch();
+
+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');
+
+  // Unblock the latch
+  startFetch();
+}
+
+task();
+setTimeout(prepare, 500);
+```

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,9 @@
+/**
+ * @module
+ * Latches
+ */
+/**
+ * Create a latch
+ */
+declare const _default: () => [resolve: () => void, promise: Promise<void>];
+export default _default;

package/latch.js

@@ -0,0 +1 @@
+export default ()=>{let r;let p=new Promise((res)=>{r=res});return[r,p]};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ciorent",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "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",
@@ -21,9 +22,11 @@
     "eslint": "latest",
     "eslint-plugin-jsdoc": "latest",
     "mitata": "latest",
+    "terser": "^5.39.0",
     "tsx": "latest",
+    "typedoc": "^0.27.9",
+    "typedoc-material-theme": "^1.3.0",
     "typescript": "latest",
-    "typescript-eslint": "latest",
-    "uglify-js": "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}};