ciorent 0.5.0 → 0.6.0

package/README.md

@@ -7,3 +7,178 @@ A lightweight, low-overhead concurrency library.
 - Fully type-safe.
 
 ## Examples
+
+### Pausing
+Continue the execution on next tick, allowing other asynchronous tasks to run.
+```ts
+import { nextTick } from 'ciorent';
+
+const logTime = (label: string) =>
+  console.log(`${label}: ${Math.floor(performance.now())}ms`);
+
+// Expensive sync task
+const task1 = async () => {
+  let x = 0;
+
+  // Simulate heavy operation
+  for (let i = 0, l = (Math.random() + 15) * 1e6; i < l; i++) {
+    // Yield control back occasionally to the runtime, allowing
+    // it to schedule other tasks
+    if (i % 1e5 === 0) await nextTick;
+
+    x += Math.random() * 32 + i * Math.round(Math.random() * 16);
+  }
+
+  console.log('Task 1 result:', x);
+};
+
+// Short async task
+const task2 = async (id: number) => {
+  logTime('Task 2.' + id + ' start fetching');
+  await fetch('http://localhost:3000').catch(() => {});
+  logTime('Task 2.' + id + ' done fetching');
+};
+
+task1();
+
+// Task 2 will not get blocked by task 1
+for (let i = 1; i <= 5; i++) task2(i);
+```
+
+### Sleep
+Runtime-agnostic synchronous and asynchronous sleep functions.
+```ts
+import { sleep, sleepSync } from 'ciorent';
+
+const logTime = (label: string) =>
+  console.log(`${label}: ${Math.floor(performance.now())}ms`);
+
+logTime('Start');
+
+// Non-blocking
+await 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
+sleepSync(500);
+logTime('After another 0.5s');
+```
+
+### Latches
+Latches are a type of synchronization primitive that allows one thread to wait until another thread completes an operation before continuing execution.
+```ts
+import { sleep, latch } from 'ciorent';
+
+const startFetch = latch.init();
+
+(async () => {
+  // Wait until the latch is opened
+  await latch.wait(startFetch);
+
+  const res = await fetch('http://example.com');
+  return res.text();
+})();
+
+// Fetch starts after 500ms
+await sleep(500);
+latch.open(startFetch);
+```
+
+### Semaphores
+Semaphore is a concurrency primitive used to control access to a common resource by multiple processes.
+```ts
+import { semaphore, nextTick } 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.acquire(sem);
+
+  console.log('Task', id, 'started');
+
+  // Let the main thread schedules other tasks
+  for (let i = 1; i <= 5; i++) await nextTick;
+
+  console.log('Task', id, 'end');
+
+  // Release the semaphore
+  semaphore.release(sem);
+};
+
+for (let i = 1; i <= 5; i++) task(i);
+```
+
+### Fibers
+Virtual threads with more controlled execution.
+```ts
+import { fiber, sleep } from 'ciorent';
+
+const logTime = (label: string) =>
+  console.log(`${label}: ${Math.floor(performance.now())}ms`);
+
+const f1 = fiber.fn(function* () {
+  // Wait for a promise
+  console.log('Fiber 1 waiting: 1s');
+  yield sleep(1000);
+
+  // Wait for a promise and return its result
+  const res = yield* fiber.unwrap(Promise.resolve(1));
+  console.log('Fiber 1 recieved:', res);
+
+  return Math.random();
+});
+
+{
+  // Start the fiber process on next event loop cycle
+  const main = fiber.spawn(function* (proc) {
+    // Start f1, wait for the process to complete and get the result
+    console.log('Fiber 2: joins fiber 1');
+    const res = yield* fiber.join(fiber.spawn(f1));
+    console.log('Fiber 2 recieved:', res);
+
+    // Start f1 and make its lifetime depends on current fiber
+    console.log('Fiber 2: spawns fiber 1');
+    const childProc = fiber.spawn(f1);
+    fiber.mount(childProc, proc);
+  });
+
+  console.log('Fiber 2 started:', fiber.running(main));
+
+  // Wait for the fiber process to finish
+  await fiber.complete(main);
+
+  // Check finish status
+  console.log('Fiber 2 completed:', fiber.completed(main));
+}
+
+{
+  console.log('------------------------');
+
+  const main = fiber.spawn(f1);
+  console.log('Fiber 1 started:', fiber.running(main));
+
+  // Interrupt a fiber
+  fiber.interrupt(main);
+
+  // Execution will be stopped on the last yield
+  await fiber.complete(main);
+
+  console.log('Fiber 1 interrupted:', fiber.interrupted(main));
+}
+
+{
+  console.log('------------------------');
+
+  const main = fiber.spawn(f1);
+  logTime('Fiber 1 started');
+
+  // Wait for a time period then interrupt the fiber
+  fiber.timeout(main, 500);
+  await fiber.complete(main);
+
+  logTime('Fiber 1 interrupted');
+}
+```

package/fiber.js

@@ -1 +1 @@
-import{nextTick,sleep}from"./index.js";export let running=e=>e[1]===1;export let completed=e=>e[1]===2;export let interrupted=e=>e[1]===3;let invoke=async(f,p)=>{await nextTick;try{let e=f.next();while(!e.done){let m=await e.value;if(p[1]===3)return;e=f.next(m)}p[1]=2;return e.value}finally{if(p[1]!==2)p[1]=3;p[2].forEach(interrupt)}};export let fn=e=>e;export let spawn=(e,...f)=>{let p=[null,1,[]];p[0]=invoke(e(p,...f),p);return p};export let interrupt=e=>{if(e[1]!==2)e[1]=3};export let timeout=async(e,p)=>{await sleep(p);interrupt(e)};export function*join(e){return yield e[0]}export let complete=e=>e[0];export let mount=(e,f)=>{f[2].push(e)};export let control=(e,f)=>{f.addEventListener(`abort`,()=>{interrupt(e)})};export function*unwrap(e){return yield e}
+import{nextTick,sleep}from"./index.js";export let running=e=>e[1]===1;export let completed=e=>e[1]===2;export let interrupted=e=>e[1]===3;let invoke=async(f,p)=>{await nextTick;try{let e=f.next();while(!e.done){let m=await e.value;if(p[1]===3)return;e=f.next(m)}p[1]=2;return e.value}finally{if(p[1]!==2)p[1]=3;p[2].forEach(interrupt)}};export let fn=e=>e;export let spawn=(e,...f)=>{let p=[,1,[]];p[0]=invoke(e(p,...f),p);return p};export let interrupt=e=>{if(e[1]!==2)e[1]=3};export let timeout=async(e,p)=>{await sleep(p);interrupt(e)};export function*join(e){return yield e[0]}export let complete=e=>e[0];export let mount=(e,f)=>{f[2].push(e)};export let control=(e,f)=>{f.addEventListener(`abort`,()=>{interrupt(e)})};export function*unwrap(e){return yield e}

package/index.d.ts

@@ -1,4 +1,7 @@
 /**
+* @module Other utilities
+*/
+/**
 * Continue the execution on next event loop cycle.
 *
 * You can `await` this **occasionally** in an expensive synchronous operation to avoid
@@ -26,24 +29,7 @@ export declare const timeout: <T>(promise: Promise<T>, ms: number) => Promise<T
 * @param ms - Sleep duration in milliseconds
 */
 export declare const sleepSync: (ms: number) => void;
-/**
-* Spawn n sequential task
-* @param n
-* @param task - The function to run
-*/
-export declare const sequential: <const T extends any[]>(n: number, task: (...args: [...T, id: number]) => Promise<any>, ...args: T) => Promise<void>;
-/**
-* Spawn n concurrent tasks
-* @param n
-* @param task - The function to run
-*/
-export declare const spawn: <
-	const T extends any[],
-	const R
->(n: number, task: (...args: [...T, id: number]) => Promise<R>, ...args: T) => Promise<R>[];
-/**
-* Throttle function execution for a time period
-* @param ms - The time in milliseconds
-* @param limit - The call limit in the time period
-*/
-export declare const throttle: (ms: number, limit: number) => (() => Promise<void>);
+export * as fiber from "./fiber.js";
+export * as latch from "./latch.js";
+export * as rateLimit from "./rate-limit.js";
+export * as semaphore from "./semaphore.js";

package/index.js

@@ -1 +1 @@
-export let nextTick=Promise.resolve();export let sleep=globalThis.Bun?.sleep??globalThis.process?.getBuiltinModule?.(`timers/promises`).setTimeout??(e=>new Promise(t=>{setTimeout(t,e)}));export let timeout=(e,n)=>Promise.race([e,sleep(n)]);let sharedBuf=new Int32Array(new SharedArrayBuffer(4));export let sleepSync=globalThis.Bun?.sleepSync??(e=>{Atomics.wait(sharedBuf,0,0,e)});export let sequential=async(e,t,...n)=>{for(let r=0;r<e;r++)await t(...n,r)};export let spawn=(e,t,...n)=>{let r=new Array(e);for(let i=0;i<e;i++)r[i]=t(...n,i);return r};export let throttle=(e,t)=>{let n=[null];let r=n;let i=e=>{n=n[0]=[null,e]};let a=t;let o=false;let s=()=>{a=t;if(r===n){o=false;return}do{a--;(r=r[0])[1]()}while(a>0&&r!==n);setTimeout(s,e)};return async()=>{if(a===0)return new Promise(i);if(!o){o=true;setTimeout(s,e)}a--}};
+export let nextTick=Promise.resolve();export let sleep=globalThis.Bun?.sleep??globalThis.process?.getBuiltinModule?.(`timers/promises`).setTimeout??(e=>new Promise(r=>{setTimeout(r,e)}));export let timeout=(e,i)=>Promise.race([e,sleep(i)]);let sharedBuf=new Int32Array(new SharedArrayBuffer(4));export let sleepSync=globalThis.Bun?.sleepSync??(e=>{Atomics.wait(sharedBuf,0,0,e)});export*as fiber from"./fiber.js";export*as latch from"./latch.js";export*as rateLimit from"./rate-limit.js";export*as semaphore from"./semaphore.js";

package/latch.d.ts

@@ -0,0 +1,20 @@
+/**
+* Describe a latch
+*/
+export type Latch = [p: Promise<void>, res: () => void, cb: (res: () => void) => void];
+export declare const init: <T>() => Latch;
+/**
+* Reclose the latch
+* @param c
+*/
+export declare const close: (c: Latch) => void;
+/**
+* Open the latch
+* @param c
+*/
+export declare const open: (c: Latch) => void;
+/**
+* Wait for the latch to open
+* @param c
+*/
+export declare const wait: (c: Latch) => Promise<void>;

package/latch.js

@@ -0,0 +1 @@
+export let init=()=>{let e=[,,r=>{e[1]=r}];close(e);return e};export let close=e=>{e[0]=new Promise(e[2])};export let open=e=>{e[1]()};export let wait=e=>e[0];

package/package.json

@@ -1,8 +1,7 @@
 {
 "name": "ciorent",
-"version": "0.5.0",
+"version": "0.6.0",
 "description": "A lightweight, low-overhead concurrency library",
-"homepage": "https://ciorent.netlify.app",
 "repository": {
 "type": "git",
 "url": "git+https://github.com/re-utils/ciorent.git"
@@ -12,11 +11,5 @@
 "type": "module",
 "main": "./index.js",
 "types": "./index.d.ts",
-"exports": {
-"./queue": "./queue.js",
-"./fiber": "./fiber.js",
-".": "./index.js",
-"./rate-limit": "./rate-limit.js",
-"./semaphore": "./semaphore.js"
-}
+"exports": {}
 }

package/queue.d.ts

@@ -5,7 +5,7 @@
 /**
 * Describe a queue node (singly linked list node)
 */
-export type QueueNode<T> = [next: QueueNode<T> | null, value: T];
+export type QueueNode<T> = [next: QueueNode<T> | undefined, value: T];
 /**
 * Describe an unbounded queue
 */

package/rate-limit.d.ts

@@ -4,7 +4,7 @@
 /**
 * Describe a rate limiter
 */
-export type Limiter = (calls: number, ms: number) => () => boolean;
+export type Limiter = (limit: number, ms: number) => () => boolean;
 /**
 * Fixed window strategy
 * @param limit

package/rate-limit.js

@@ -1 +1 @@
-export let fixed=(e,t)=>{let n=e;let r=()=>{n=e};return()=>{if(n===0)return false;if(n===e)setTimeout(r,t);n--;return true}};export let sliding=(e,t)=>{let n=e;let r=()=>{n++};return()=>{if(n===0)return false;n--;setTimeout(r,t);return true}};export let bucket=(e,t)=>{let n=e;t/=e;let r=()=>{n++;if(n<e)setTimeout(r,t)};return()=>{if(n===0)return false;if(n===e)setTimeout(r,t);n--;return true}};
+export let fixed=(e,t)=>{let n=e;let r=()=>{n=e};return()=>{if(n===0)return false;if(n--===e)setTimeout(r,t);return true}};export let sliding=(e,t)=>{let n=e;let r=()=>{n++};return()=>{if(n===0)return false;n--;setTimeout(r,t);return true}};export let bucket=(e,t)=>{let n=e;t/=e;let r=()=>{if(n++<e)setTimeout(r,t)};return()=>{if(n===0)return false;if(n--===e)setTimeout(r,t);return true}};

package/semaphore.d.ts

@@ -18,7 +18,3 @@ export declare const acquire: (s: Semaphore) => Promise<void>;
 * Signal to the semaphore to release access
 */
 export declare const release: (s: Semaphore) => void;
-/**
-* Bind a task to a semaphore
-*/
-export declare const bind: <T extends (...args: any[]) => Promise<any>>(f: T, s: Semaphore) => T;

package/semaphore.js

@@ -1 +1 @@
-export let init=e=>{let n=[null];let r=[n,n,e=>{r[0]=r[0][0]=[null,e]},e];return r};export let acquire=async e=>{e[3]--;if(e[3]<0)return new Promise(e[2])};export let release=e=>{if(e[3]<0)(e[1]=e[1][0])[1]();e[3]++};export let bind=(e,n)=>async(...r)=>{n[3]--;if(n[3]<0)await new Promise(n[2]);try{return await e(...r)}finally{if(n[3]<0)(n[1]=n[1][0])[1]();n[3]++}};
+export let init=e=>{let t=[,];let n=[t,t,e=>{n[0]=n[0][0]=[,e]},e];return n};export let acquire=async e=>{e[3]--;if(e[3]<0)return new Promise(e[2])};export let release=e=>{if(e[3]<0)(e[1]=e[1][0])[1]();e[3]++};