ciorent 0.0.26 → 0.1.1

package/README.md

@@ -1,72 +1,4 @@
 A lightweight, low-overhead concurrency library.
-## Semaphore
-Semaphore is a concurrency primitive used to control access to a common resource by multiple processes.
-
-```ts
-import * as semaphore from 'ciorent/semaphore';
-import * as cio from 'ciorent';
-
-const task = semaphore.wrap(
-  async (task: number) => {
-    for (let i = 1; i <= 5; i++) {
-      console.log('Task', task, 'iteration', i);
-      await cio.pause;
-    }
-
-    console.log('Task', task, 'end');
-  }
-);
-
-// Only allow 2 task to run concurrently
-const sem = semaphore.init(2);
-
-// Try to run 6 tasks concurrently
-cio.concurrent(6, (sem, id) => task(sem, id), sem);
-```
-
-## Latch
-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';
-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));
-}
-
-const main = async () => {
-  const p = task();
-  await cio.sleep(500);
-  prepare();
-
-  // Allows all previously blocked tasks to run
-  latch.open(fetchLatch);
-
-  // Reclose the latch
-  // Tasks that aren't blocked yet will be blocked
-  latch.reset(fetchLatch);
-
-  return p;
-}
-
-// Run fetch after 500ms
-await main();
-
-// Run fetch after another 500ms
-await main();
-```
-
 ## Fibers
 Virtual threads with more controlled execution.
 
@@ -101,6 +33,33 @@ const thread2 = fiber.fn(function* (thread) {
 fiber.spawn(thread2);
 ```
 
+## Latch
+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';
+
+const startFetch = latch.init();
+
+const task = async () => {
+  // Blocks until the latch is open
+  await latch.pause(startFetch);
+
+  console.log('Start fetching...');
+  const res = await fetch('http://example.com');
+  console.log('Fetch status:', res.status);
+}
+
+const prepare = () => {
+  // This always run first
+  console.log('Run before fetch:', performance.now().toFixed(2));
+  latch.open(startFetch);
+}
+
+task();
+prepare();
+```
+
 ## Pubsub
 A fast, simple publish-subscribe API.
 
@@ -112,7 +71,7 @@ const messages = topic.init<number>();
 
 // A task that publish messages
 const publisher = async () => {
-  for (let i = 0; i < 5; i++) {
+  for (let i = 0; i < 3; i++) {
     await cio.sleep(100);
     topic.pub(messages, i);
   }
@@ -122,15 +81,15 @@ const publisher = async () => {
   topic.flush(messages);
 }
 
-// Spawn 5 tasks that recieve messages
-cio.concurrent(5, async (id: number) => {
+// Spawn 3 tasks that recieve messages
+cio.concurrent(3, async (id: number) => {
   const sub = topic.sub(messages);
 
   while (true) {
     // Block until the value is sent
     const x = await topic.recieve(sub);
     if (x == null) break;
-    console.log(`Task ${id}: ${x}`);
+    console.log(`Task ${id} recieved: ${x}`);
   }
 });
 
@@ -147,8 +106,8 @@ import * as cio from 'ciorent';
 const c = channel.init<number>();
 
 const run = async () => {
-  for (let i = 0; i < 10; i++) {
-    await cio.sleep(10);
+  for (let i = 0; i < 5; i++) {
+    await cio.sleep(100);
     channel.send(c, i);
     console.log('Sent', i);
   }
@@ -160,7 +119,7 @@ const run = async () => {
 
 const log = async () => {
   while (true) {
-    // Wait until a value is sent
+    // Wait until a value is sent to the channel
     const x = await channel.recieve(c);
     if (x == null) break;
 
@@ -168,13 +127,42 @@ const log = async () => {
   };
 }
 
-run();
 log();
+run();
 
 // This runs first
 console.log('Starting...');
 ```
 
+## Semaphore
+Semaphore is a concurrency primitive used to control access to a common resource by multiple processes.
+
+```ts
+import * as semaphore from 'ciorent/semaphore';
+import * as cio from 'ciorent';
+
+// Only allow 2 task to run concurrently
+const sem = semaphore.init(2);
+
+const task = async (id: number) => {
+  // Acquire the semaphore or wait for the semaphore to be available
+  await semaphore.pause(sem);
+
+  console.log('Task', id, 'started');
+
+  // Let the main thread schedules other tasks
+  for (let i = 1; i <= 5; i++) await cio.pause;
+
+  console.log('Task', id, 'end');
+
+  // Release the semaphore
+  semaphore.signal(sem);
+}
+
+// Try to run 5 tasks concurrently
+cio.concurrent(5, task);
+```
+
 ## Utilities
 ### Pausing
 Delay the execution of a function for other asynchronous tasks to run.
@@ -185,9 +173,11 @@ import * as cio from 'ciorent';
 const task1 = async () => {
   let x = 0;
 
-  // Pause to let task2 to run
+  // Yield control back to the runtime, allowing it to
+  // schedule other tasks
   await cio.pause;
 
+  // Simulate heavy operation
   for (let i = 0; i < (Math.random() + 15) * 1e6; i++)
     x += Math.random() * 32 + i * Math.round(Math.random() * 16);
 
@@ -196,11 +186,8 @@ const task1 = async () => {
 
 // Short async task
 const task2 = async () => {
-  console.log('Fetch start', performance.now().toFixed(2) + 'ms');
-
-  // This will pause task2 to let task1 to continue running
+  console.log('Start fetching...');
   const txt = await fetch('http://example.com');
-
   console.log('Fetch status', txt.status);
 };
 
@@ -212,15 +199,20 @@ task2();
 ### Sleep
 Cross-runtime synchronous and asynchronous sleep functions.
 ```ts
-import { sleep, sleepSync } from 'ciorent';
+import * as cio from 'ciorent';
 
-await sleep(500);
-console.log('Hi');
+const logTime = (label: string) => console.log(label + ':', Math.floor(performance.now()) + 'ms');
 
-// This blocks the current thread
-// On the browser this only works in workers
-sleepSync(500);
-console.log('Hi');
+logTime('Start');
+
+// Non-blocking
+await cio.sleep(500);
+logTime('After about 0.5s');
+
+// This blocks the event loop
+// On the browser this only works in workers and blocks the worker thread
+cio.sleepSync(500);
+logTime('After another 0.5s');
 ```
 
 ### Spawning tasks
@@ -229,17 +221,17 @@ Utilities to create and run tasks.
 import * as cio from 'ciorent';
 
 const task = async (id: number) => {
-  await cio.sleep(Math.random() * 20 + 50);
+  await cio.sleep((10 - id) * 20 + 50);
   console.log('Task', id, 'done');
 }
 
 // Spawn and run 5 tasks sequentially
 console.log('Running 5 tasks sequentially:');
-cio.sequential(5, task);
+await cio.sequential(5, task);
 
 // Spawn and run 5 tasks concurrently
 console.log('Running 5 tasks concurrently:');
-cio.concurrent(5, task);
+await cio.concurrent(5, task);
 ```
 
 ### Debounce
@@ -263,7 +255,7 @@ import * as cio from 'ciorent';
 
 // Allow 1 call in 500ms
 const fn = cio.rateLimit((id: number) => {
-  console.log('ID:', id);
+  console.log('Call ' + id + ':', Math.floor(performance.now()) + 'ms');
 }, 500, 1);
 
 fn(1); // fn(1) gets executed
@@ -283,7 +275,6 @@ const fn = cio.throttle((id: number) => {
   console.log(id + ': ' + Math.floor(performance.now()) + 'ms');
 }, 500, 2);
 
-for (let i = 0; i < 8; i++)
-  fn(i);
+cio.concurrent(8, (id) => fn(id));
 ```
 

package/channel.js

@@ -1 +1 @@
-export let init=()=>{let qu=[null,null];let resolveQu=[null,null];return[qu,qu,resolveQu,resolveQu]};export let send=(c,t)=>{if(c[3][1]!==null)(c[3]=c[3][1])[0](t);else c[0]=c[0][1]=[t,null]};export let recieve=(c)=>c[1][1]!==null?Promise.resolve((c[1]=c[1][1])[0]):new Promise((res)=>{c[2]=c[2][1]=[res,null]});export let poll=(c)=>c[1][1]!==null?(c[1]=c[1][1])[0]:undefined;export let flush=(c)=>{while(c[3][1]!==null)(c[3]=c[3][1])[0]()};
+export let init=()=>{let qu=[null];let resolveQu=[null,null];return[qu,qu,resolveQu,resolveQu]};export let send=(c,t)=>{if(c[3][0]!==null)(c[3]=c[3][0])[1](t);else c[0]=c[0][0]=[null,t]};export let recieve=(c)=>c[1][0]!==null?Promise.resolve((c[1]=c[1][0])[1]):new Promise((res)=>{c[2]=c[2][0]=[null,res]});export let poll=(c)=>c[1][0]!==null?(c[0]=c[1][0])[1]:undefined;export let flush=(c)=>{while(c[3][0]!==null)(c[3]=c[3][0])[1]()};

package/fiber.js

@@ -1 +1 @@
-export let paused=(t)=>t[1]===0;export let running=(t)=>t[1]===1;export let done=(t)=>t[1]===2;let invoke=async(g,thread)=>{let t=g.next();while(!t.done){let v=await t.value;if(thread[1]===0){let r;let p=new Promise((res)=>{r=res});thread[2]=r;await p}if(thread[1]===2){thread[3].forEach(stop);return v}t=g.next(v)}thread[1]=2;thread[3].forEach(stop);return t.value};export let fn=(f)=>f;export let spawn=(f,...args)=>{let thread=[null,1,null,[]];thread[0]=invoke(f(thread,...args),thread);return thread};export let pause=(t)=>{if(t[1]===1)t[1]=0};export let resume=(t)=>{if(t[1]===0){t[1]=1;t[2]?.()}};export let stop=(t)=>{if(t[1]===0){t[1]=2;t[2]?.()}else t[1]=2};export function*join(t){return yield t[1]}export let finish=(t)=>t[1];export let mount=(child,parent)=>{parent[3].push(child)};export let control=(t,signal)=>{signal.addEventListener("abort",()=>{stop(t)})};export function*unwrap(t){return yield t}
+export let paused=(t)=>t[1]===0;export let running=(t)=>t[1]===1;export let done=(t)=>t[1]===2;let invoke=async(g,thread)=>{try{let t=g.next();while(!t.done){let v=await t.value;if(thread[1]===0){let r;let p=new Promise((res)=>{r=res});thread[2]=r;await p}if(thread[1]===2){thread[3].forEach(stop);return v}t=g.next(v)}thread[1]=2;return t.value}finally{thread[3].forEach(stop)}};export let fn=(f)=>f;export let spawn=(f,...args)=>{let thread=[null,1,null,[]];thread[0]=invoke(f(thread,...args),thread);return thread};export let pause=(t)=>{if(t[1]===1)t[1]=0};export let resume=(t)=>{if(t[1]===0){t[1]=1;t[2]?.()}};export let stop=(t)=>{if(t[1]===0){t[1]=2;t[2]?.()}else t[1]=2};export function*join(t){return yield t[1]}export let finish=(t)=>t[1];export let mount=(child,parent)=>{parent[3].push(child)};export let control=(t,signal)=>{signal.addEventListener("abort",()=>{stop(t)})};export function*unwrap(t){return yield t}

package/fixed-queue.d.ts

@@ -26,7 +26,7 @@ export interface FixedQueue<T extends {}> {
 /**
  * Describe a queue node (singly linked list node)
  */
-export type QueueNode<T> = [value: T, next: QueueNode<T> | null];
+export type QueueNode<T> = [next: QueueNode<T> | null, value: T];
 /**
  * Create a fixed queue.
  * @param n - The queue size

package/index.d.ts

@@ -2,7 +2,7 @@
  * @module Other utilities
  */
 /**
- * Continue running the function on next microtask.
+ * Yield back to main thread.
  *
  * You can `await` this **occasionally** in an expensive synchronous operation to avoid
  *
@@ -10,13 +10,15 @@
  */
 export declare const pause: Promise<void>;
 /**
- * Sleep for a duration
+ * Sleep for a duration.
  * @param ms - Sleep duration in milliseconds
  */
 export declare const sleep: (ms: number) => Promise<void>;
 /**
  * Sleep for a duration synchronously.
  *
+ * This method blocks the current thread.
+ *
  * On the browser it only works in workers.
  * @param ms - Sleep duration in milliseconds
  */
@@ -35,20 +37,20 @@ export declare const sequential: <const T extends any[]>(n: number, task: (...ar
 export declare const concurrent: <const T extends any[], const R>(n: number, task: (...args: [...T, id: number]) => Promise<R>, ...args: T) => Promise<R[]>;
 /**
  * Drop function calls until it doesn't get called for a specific period.
- * @param f - The target function to debounce
+ * @param f - The target function to debounce (it must not throw errors)
  * @param ms - The time period in milliseconds
  */
 export declare const debounce: <const Args extends any[]>(f: (...args: Args) => any, ms: number) => ((...args: Args) => void);
 /**
  * Drop function calls for a specific period
- * @param f - The target function to rate limit
+ * @param f - The target function to rate limit (it must not throw errors)
  * @param ms - The time period in milliseconds
  * @param limit - The call limit in the time period
  */
 export declare const rateLimit: <const Args extends any[]>(f: (...args: Args) => any, ms: number, limit: number) => ((...args: Args) => void);
 /**
  * Throttle function execution for a time period
- * @param f - The function to throttle
+ * @param f - The function to throttle (it must not throw errors)
  * @param ms - The time in milliseconds
  * @param limit - The call limit in the time period
  */

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)}));let sharedBuf=new Int32Array(new SharedArrayBuffer(4));export let sleepSync=globalThis.Bun?.sleepSync??((ms)=>{Atomics.wait(sharedBuf,0,0,ms)});export let sequential=async(n,task,...args)=>{for(let i=0;i<n;i++)await task(...args,i)};export let concurrent=(n,task,...args)=>{let arr=new Array(n);for(let i=0;i<n;i++)arr[i]=task(...args,i);return Promise.all(arr)};export let debounce=(f,ms)=>{let id;return(...a)=>{clearTimeout(id);id=setTimeout(f,ms,...a)}};export let rateLimit=(f,ms,limit)=>{let call=()=>{limit++};return(...a)=>{if(limit>0){limit--;try{f(...a)}finally{setTimeout(call,ms)}}}};export let throttle=(f,ms,limit)=>{let head=[null,null,null];let tail=head;let unlock=()=>{if(tail!==head){tail=tail[2];tail[0](f(...tail[1]));setTimeout(unlock,ms)}else limit++};return(...a)=>{if(limit===0){let r;let p=new Promise((res)=>{r=res});head=head[2]=[r,a,null];return p}limit--;setTimeout(unlock,ms);return f(...a)}};
+export let pause=Promise.resolve();export let sleep=globalThis.Bun?.sleep??globalThis.process?.getBuiltinModule?.("timers/promises").setTimeout??((ms)=>new Promise((res)=>{setTimeout(res,ms)}));let sharedBuf=new Int32Array(new SharedArrayBuffer(4));export let sleepSync=globalThis.Bun?.sleepSync??((ms)=>{Atomics.wait(sharedBuf,0,0,ms)});export let sequential=async(n,task,...args)=>{for(let i=0;i<n;i++)await task(...args,i)};export let concurrent=(n,task,...args)=>{let arr=new Array(n);for(let i=0;i<n;i++)arr[i]=task(...args,i);return Promise.all(arr)};export let debounce=(f,ms)=>{let id;return(...a)=>{clearTimeout(id);id=setTimeout(f,ms,...a)}};export let rateLimit=(f,ms,limit)=>{let cur=limit;let unlock=()=>{cur=limit};return(...a)=>{if(cur>0){if(cur===1)setTimeout(unlock,ms);cur--;f(...a)}}};export let throttle=(f,ms,limit)=>{let head=[null];let tail=head;let cur=limit;let unlock=()=>{cur=limit;while(cur>0){if(tail===head)return;cur--;tail=tail[0];tail[1](f(...tail[2]))}setTimeout(unlock,ms)};return(...a)=>{if(cur===1){setTimeout(unlock,ms)}else if(cur===0){let r;let p=new Promise((res)=>{r=res});head=head[0]=[null,r,a];return p}cur--;return f(...a)}};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ciorent",
-  "version": "0.0.26",
+  "version": "0.1.1",
   "description": "A lightweight, low-overhead concurrency library",
   "homepage": "https://ciorent.netlify.app",
   "repository": {
@@ -18,13 +18,13 @@
   "main": "./index.js",
   "types": "./index.d.ts",
   "exports": {
-    "./fixed-queue": "./fixed-queue.js",
-    "./latch": "./latch.js",
     "./sliding-queue": "./sliding-queue.js",
-    ".": "./index.js",
     "./semaphore": "./semaphore.js",
     "./topic": "./topic.js",
+    ".": "./index.js",
+    "./latch": "./latch.js",
     "./channel": "./channel.js",
+    "./fixed-queue": "./fixed-queue.js",
     "./dropping-queue": "./dropping-queue.js",
     "./fiber": "./fiber.js"
   }

package/semaphore.js

@@ -1 +1 @@
-import{pause as resolvedPromise}from"./index.js";export let init=(n)=>{let root=[null,null];return[n,root,root]};export let pause=(s)=>{s[0]--;if(s[0]<0){let r;let p=new Promise((res)=>{r=res});s[1]=s[1][1]=[r,null];return p}return resolvedPromise};export let signal=(s)=>{if(s[0]<0)(s[2]=s[2][1])[0]();s[0]++};export let wrap=(f)=>async(s,...a)=>{s[0]--;if(s[0]<0){let r;let p=new Promise((res)=>{r=res});s[1]=s[1][1]=[r,null];await p}try{return await f(...a)}finally{signal(s)}};
+import{pause as resolvedPromise}from"./index.js";export let init=(n)=>{let root=[null];return[n,root,root]};export let pause=(s)=>{s[0]--;if(s[0]<0){let r;let p=new Promise((res)=>{r=res});s[1]=s[1][0]=[null,r];return p}return resolvedPromise};export let signal=(s)=>{if(s[0]<0)(s[2]=s[2][0])[1]();s[0]++};export let wrap=(f)=>async(s,...a)=>{s[0]--;if(s[0]<0){let r;let p=new Promise((res)=>{r=res});s[1]=s[1][0]=[null,r];await p}try{return await f(...a)}finally{signal(s)}};

package/topic.js

@@ -1 +1 @@
-export let init=()=>[[null,null],[],[]];export let sub=(t)=>[t,t[0]];export let pub=(t,value)=>{let head=t[0]=t[0][1]=[value,null];for(let i=0,res=t[1],subs=t[2];i<res.length;i++){res[i](value);subs[i][1]=head}t[1]=[];t[2]=[]};export let flush=(t)=>{let head=t[0]=[null,null];for(let i=0,res=t[1],subs=t[2];i<res.length;i++){res[i]();subs[i][1]=head}t[1]=[];t[2]=[]};export let poll=(t)=>t[1][1]!==null?(t[1]=t[1][1])[0]:undefined;export let recieve=(t)=>{if(t[1][1]!==null)return Promise.resolve((t[1]=t[1][1])[0]);let topic=t[0];topic[2].push(t);return new Promise((res)=>{topic[1].push(res)})};
+export let init=()=>[[null],[],[]];export let sub=(t)=>[t,t[0]];export let pub=(t,value)=>{let head=t[0]=t[0][0]=[null,value];for(let i=0,res=t[1],subs=t[2];i<res.length;i++){res[i](value);subs[i][1]=head}t[1]=[];t[2]=[]};export let flush=(t)=>{let head=t[0]=[null];for(let i=0,res=t[1],subs=t[2];i<res.length;i++){res[i]();subs[i][1]=head}t[1]=[];t[2]=[]};export let poll=(t)=>t[1][0]!==null?(t[1]=t[1][0])[1]:undefined;export let recieve=(t)=>{if(t[1][0]!==null)return Promise.resolve((t[1]=t[1][0])[1]);let topic=t[0];topic[2].push(t);return new Promise((res)=>{topic[1].push(res)})};