ciorent 0.0.8 → 0.0.11

package/README.md

@@ -1,53 +1,42 @@
-A low-overhead, cross-runtime concurrency library.
+A lightweight, low-overhead concurrency library
+
+# Examples
+## Semaphore
+Semaphore is a concurrency primitive used to control access to a common resource by multiple processes.
 
-# Usage
-Pausing to prioritize an asynchronous task:
 ```ts
+import * as semaphore from 'ciorent/semaphore';
 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)
+// Only allow 2 of these tasks to run concurrently
+const task = semaphore.task(
+  semaphore.init(2),
+  async (task: number) => {
+    for (let i = 1; i <= 5; i++) {
+      console.log('Task', task, 'iteration', i);
       await cio.pause;
+    }
 
-    x += Math.random() * 32 + i * Math.round(Math.random() * 16);
+    console.log('Task', task, 'end');
   }
-  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();
+// Try to run 6 tasks with 4 tasks running concurrently
+cio.concurrent(6, task, 4);
 ```
 
-Sleep for a duration:
-```ts
-import * as cio from 'ciorent';
-
-await cio.sleep(1000);
-console.log('Slept for about 1s');
-```
+## Channel
+Channel is a synchronization primitive via message passing. A message may be sent over a channel, and another process is able to receive messages sent over a channel it has a reference to.
 
-Go-like channels for synchronizations:
 ```ts
 import * as channel from 'ciorent/channel';
-import * as cio from 'ciorent';
 
 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 cio.sleep(10);
+    await sleep(10);
     channel.send(c, i);
     console.log('Sent', i);
   }
@@ -62,8 +51,9 @@ const log = async () => {
     // Non-blocking
     const x = await channel.recieve(c);
 
-    // If the channel has been closed
-    if (x === null) break;
+    // 'recieve' returns undefined if
+    // The channel has been closed
+    if (x == null) break;
 
     console.log('Recieved', x);
   };
@@ -77,7 +67,7 @@ console.log('Starting...');
 ```
 
 ## Latch
-A latch is a synchronization tool that allows one or more threads to wait until a specific condition is met.
+Latch is a synchronization primitive that allows one process to wait until another completes an operation before continuing execution.
 
 ```ts
 import * as latch from 'ciorent/latch';
@@ -119,62 +109,83 @@ await main();
 await main();
 ```
 
-If you don't need to close the latch again:
+## Utilities
+### Pausing
+Delay the execution of a function for other asynchronous tasks to run.
 ```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);
-}
+// Expensive sync task
+const task1 = async () => {
+  let x = 0;
+  for (let i = 0; i < (Math.random() + 15) * 1e7; i++) {
+    // Frequent pausing
+    if (i % 2e6 === 0)
+      await cio.pause;
 
-const prepare = () => {
-  console.log('Run before fetch:', performance.now().toFixed(2));
+    x += Math.random() * 32 + i * Math.round(Math.random() * 16);
+  }
+  console.log('Finish task 1:', x);
+};
 
-  // Unblock the latch
-  startFetch();
-}
+// 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);
+};
 
-const main = async () => {
-  const p = task();
-  await cio.sleep(500);
-  prepare();
+// Task 2 will not get blocked by task 1
+task1();
+task2();
+```
 
-  return p;
-}
+### Sleep
+A cross-runtime sleep function.
+```ts
+import { sleep } from 'ciorent';
 
-// Run fetch after 500ms
-await main();
+await sleep(500);
+console.log('Hi');
 ```
 
-## Semaphore
-A semaphore is a synchronization tool to control access to shared resources.
+### Concurrency
+Control how many tasks can be executed concurrently.
+```ts
+import concurrent from 'ciorent/concurrent';
+import * as cio from 'ciorent';
+
+// Allow 3 tasks to run at the same time
+const run = concurrent(3);
 
-It's essentially a counter that regulates how many threads or processes can access a particular resource or section of code.
+for (let id = 1; id <= 6; id++)
+  run(async () => {
+    await cio.sleep(Math.random() * 20 + 50);
+    console.log('Task', id, 'done');
+  });
+```
 
+### Spawning tasks
+Creating new tasks with controlled concurrency.
 ```ts
-import * as semaphore from 'ciorent/semaphore';
 import * as cio from 'ciorent';
 
-// Only allow 2 of these tasks to run concurrently
-const task = semaphore.task(
-  semaphore.init(2),
-  async (task: number) => {
-    for (let i = 1; i <= 5; i++) {
-      console.log('Task', task, 'iteration', i);
-      await cio.pause;
-    }
+const task = async (id: number) => {
+  await cio.sleep(Math.random() * 20 + 50);
+  console.log('Task', id, 'done');
+}
 
-    console.log('Task', task, 'end');
-  }
-);
+// Spawn and run 5 tasks sequentially
+console.log('Running sequentially:');
+cio.sequential(5, task);
 
-// Try to run 6 tasks with 4 tasks running concurrently
-cio.concurrent(6, task, 4);
+// Spawn and run 5 tasks concurrently
+console.log('Running 5 tasks concurrently:');
+cio.concurrent(5, task);
+
+// Spawn and run 5 tasks, with the maximum
+// tasks running concurrently set to 3
+console.log('Running each 3 tasks concurrently:');
+cio.concurrent(5, task, 3);
 ```
+

package/channel.d.ts

@@ -1,8 +1,7 @@
 /**
- * @module
- * Channels
+ * @module Channels
  */
-import type { QueueNode } from './queue';
+import type { QueueNode } from './fixed-queue';
 /**
  * Describe a channel
  */
@@ -22,11 +21,11 @@ export interface Channel<T> {
     /**
      * The head of the Promise resolve queue
      */
-    3: QueueNode<(value: T | null) => void>;
+    3: QueueNode<(value?: T) => void>;
     /**
      * The tail of the Promise resolve queue
      */
-    4: QueueNode<(value: T | null) => void>;
+    4: QueueNode<(value?: T) => void>;
 }
 /**
  * Create a channel
@@ -42,12 +41,12 @@ 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>;
+export declare const recieve: <T>(c: Channel<T>) => Promise<T | undefined>;
 /**
  * Recieve a message from a channel, return null if no message is currently in queue
  * @param c
  */
-export declare const poll: <T>(c: Channel<T>) => T | null;
+export declare const poll: <T>(c: Channel<T>) => T | undefined;
 /**
  * Close a channel
  * @param c

package/channel.js

@@ -1 +1 @@
-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];
+import{pause as resolvedPromise}from".";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]}):resolvedPromise;export let poll=(c)=>c[2][1]!==null?(c[2]=c[2][1])[0]:undefined;export let close=(c)=>{c[0]=false;while(c[4][1]!==null)(c[4]=c[4][1])[0]()};export let active=(c)=>c[0];

package/concurrent.d.ts

@@ -1,6 +1,5 @@
 /**
- * @module
- * Concurrency controls
+ * @module Concurrency controls
  */
 /**
  * Describe a concurrency controller

package/{queue/dropping.d.ts → dropping-queue.d.ts}

@@ -1,10 +1,9 @@
 /**
- * @module
- * Dropping queues
+ * @module Dropping queues
  */
-import type { FixedQueue } from '.';
-export { default as init } from '.';
-export { pop } from './sliding';
+import type { FixedQueue } from './fixed-queue';
+export { default as init } from './fixed-queue';
+export { pop } from './sliding-queue';
 /**
  * Push an item to a dropping queue
  * @param q - The queue to push to

package/dropping-queue.js

@@ -0,0 +1 @@
+export{default as init}from"./fixed-queue";export{pop}from"./sliding-queue";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 → fixed-queue.d.ts}

@@ -1,7 +1,6 @@
 /**
  * @private
- * @module
- * Queue utilities
+ * @module Queue utilities
  */
 /**
  * Describe a fixed-sized queue

package/index.d.ts

@@ -1,6 +1,5 @@
 /**
- * @module
- * Other utilities
+ * @module Other utilities
  */
 /**
  * Continue running the function on next microtask.

package/index.js

@@ -1 +1 @@
-export let pause=Promise.resolve();export let sleep=globalThis.Bun?.sleep??globalThis.process?.getBuiltinModule?.("timers/promises").setTimeout??((ms)=>new Promise((res)=>{setTimeout(res,ms)}));export let sequential=async(n,task)=>{for(let i=1;i<=n;i++)await task(i)};export let concurrent=async(n,task,concurrency)=>{if(concurrency==null){let arr=new Array(n);for(let i=0;i<n;i++)arr[i]=task(i+1);return Promise.all(arr)}let arr=new Array(concurrency);let pre=1;for(let block=n/concurrency>>>0;block>0;block--){for(let j=0;j<concurrency;j++)arr[j]=task(pre+j);await Promise.all(arr);pre+=concurrency}n-=pre;for(let i=0;i<=n;i++)arr[i]=task(pre+i);return Promise.all(arr)};
+export let pause=Promise.resolve();export let sleep=globalThis.Bun?.sleep??globalThis.process?.getBuiltinModule?.("timers/promises").setTimeout??((ms)=>new Promise((res)=>{setTimeout(res,ms)}));export let sequential=async(n,task)=>{for(let i=0;i<n;i++)await task(i)};export let concurrent=async(n,task,concurrency)=>{if(concurrency==null){let arr=new Array(n);for(let i=0;i<n;i++)arr[i]=task(i);return Promise.all(arr)}let arr=new Array(concurrency);let pre=0;for(let block=n/concurrency>>>0;block>0;block--){for(let j=0;j<concurrency;j++)arr[j]=task(pre+j);await Promise.all(arr);pre+=concurrency}n-=pre;for(let i=0;i<n;i++)arr[i]=task(pre+i);return Promise.all(arr)};

package/latch.d.ts

@@ -1,6 +1,5 @@
 /**
- * @module
- * Latches
+ * @module Latches
  */
 /**
  * Describe a latch

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ciorent",
-  "version": "0.0.8",
-  "description": "A low-overhead, lightweight concurrency library",
+  "version": "0.0.11",
+  "description": "A lightweight, low-overhead concurrency library",
   "homepage": "https://ciorent.netlify.app",
   "repository": {
     "type": "github",
@@ -10,7 +10,8 @@
   "keywords": [
     "low-overhead",
     "lightweight",
-    "concurrency"
+    "concurrency",
+    "cross-runtime"
   ],
   "license": "MIT",
   "type": "module",
@@ -22,7 +23,7 @@
     "build:publish": "bun build:test && bun task report-size && bun task publish",
     "lint": "eslint ./src",
     "lint:fix": "eslint ./src --fix",
-    "docs": "typedoc ./src/** --entryPointStrategy Expand --plugin typedoc-material-theme --skipErrorChecking"
+    "docs": "typedoc"
   },
   "devDependencies": {
     "@stylistic/eslint-plugin": "latest",
@@ -35,6 +36,7 @@
     "tsx": "latest",
     "typedoc": "^0.27.9",
     "typedoc-material-theme": "^1.3.0",
+    "typedoc-plugin-inline-sources": "^1.2.1",
     "typescript": "latest",
     "typescript-eslint": "latest"
   }

package/semaphore.d.ts

@@ -1,8 +1,7 @@
 /**
- * @module
- * Semaphores
+ * @module Semaphores
  */
-import type { QueueNode } from './queue';
+import type { QueueNode } from './fixed-queue';
 /**
  * Describe a semaphore
  */

package/{queue/sliding.d.ts → sliding-queue.d.ts}

@@ -1,9 +1,8 @@
 /**
- * @module
- * Sliding queues
+ * @module Sliding queues
  */
-import type { FixedQueue } from '.';
-export { default as init } from '.';
+import type { FixedQueue } from './fixed-queue';
+export { default as init } from './fixed-queue';
 /**
  * Push an item to a sliding queue
  * @param q - The queue to push to

package/sliding-queue.js

@@ -0,0 +1 @@
+export{default as init}from"./fixed-queue";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}};

package/queue/dropping.js

@@ -1 +0,0 @@
-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/sliding.js

@@ -1 +0,0 @@
-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}};