ciorent 0.0.14 → 0.0.15

package/README.md

@@ -1,48 +1,29 @@
 A lightweight, low-overhead concurrency library.
-# Latch
-Latch is a synchronization primitive that allows one process to wait until another completes an operation before continuing execution.
+## Semaphore
+Semaphore is a concurrency primitive used to control access to a common resource by multiple processes.
 
 ```ts
-import * as latch from 'ciorent/latch';
+import * as semaphore from 'ciorent/semaphore';
 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;
-}
+// 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;
+    }
 
-// Run fetch after 500ms
-await main();
+    console.log('Task', task, 'end');
+  }
+);
 
-// Run fetch after another 500ms
-await main();
+// Try to run 6 tasks with 4 tasks running concurrently
+cio.concurrent(6, task, 4);
 ```
 
-# Pubsub
+## Pubsub
 A fast, simple publish-subscribe API.
 
 ```ts
@@ -54,7 +35,7 @@ const messages = topic.init<number>();
 // A task that publish messages
 const publisher = async () => {
   for (let i = 0; i < 5; i++) {
-    await cio.sleep(50);
+    await cio.sleep(100);
     topic.pub(messages, i);
   }
 
@@ -68,8 +49,8 @@ cio.concurrent(5, async (id: number) => {
   const sub = topic.sub(messages);
 
   while (true) {
-    // Block until
-    const x = await topic.next(sub);
+    // Block until the value is sent
+    const x = await topic.recieve(sub);
     if (x == null) break;
     console.log(`Task ${id}: ${x}`);
   }
@@ -78,31 +59,7 @@ cio.concurrent(5, async (id: number) => {
 publisher();
 ```
 
-# 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 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;
-    }
-
-    console.log('Task', task, 'end');
-  }
-);
-
-// Try to run 6 tasks with 4 tasks running concurrently
-cio.concurrent(6, task, 4);
-```
-
-# Channel
+## 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.
 
 ```ts
@@ -118,18 +75,15 @@ const run = async () => {
     console.log('Sent', i);
   }
 
-  // Send the closed signal to the reciever
-  // Or else channel.recieve will block forever
-  channel.close(c);
+  // Resolve all waiting promises with `undefined`
+  // This is a way to tell the reciever to not listen to more data
+  channel.flush(c);
 };
 
 const log = async () => {
   while (true) {
-    // Non-blocking
+    // Block until x is recieved
     const x = await channel.recieve(c);
-
-    // 'recieve' returns undefined if
-    // The channel has been closed
     if (x == null) break;
 
     console.log('Recieved', x);
@@ -143,8 +97,51 @@ log();
 console.log('Starting...');
 ```
 
-# Utilities
-## Pausing
+## 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();
+```
+
+## Utilities
+### Pausing
 Delay the execution of a function for other asynchronous tasks to run.
 ```ts
 import * as cio from 'ciorent';
@@ -174,7 +171,7 @@ task1();
 task2();
 ```
 
-## Sleep
+### Sleep
 A cross-runtime sleep function.
 ```ts
 import { sleep } from 'ciorent';
@@ -183,23 +180,7 @@ await sleep(500);
 console.log('Hi');
 ```
 
-## Basic 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);
-
-for (let id = 1; id <= 6; id++)
-  run(async () => {
-    await cio.sleep(Math.random() * 20 + 50);
-    console.log('Task', id, 'done');
-  });
-```
-
-## Spawning tasks
+### Spawning tasks
 Creating new tasks with controlled concurrency.
 ```ts
 import * as cio from 'ciorent';
@@ -210,16 +191,11 @@ const task = async (id: number) => {
 }
 
 // Spawn and run 5 tasks sequentially
-console.log('Running sequentially:');
+console.log('Running 5 tasks sequentially:');
 cio.sequential(5, task);
 
 // 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

@@ -6,26 +6,22 @@ import type { QueueNode } from './fixed-queue';
  * Describe a channel
  */
 export interface Channel<T> {
-    /**
-     * Opening state of the channel
-     */
-    0: boolean;
     /**
      * The head of the value queue
      */
-    1: QueueNode<T>;
+    0: QueueNode<T>;
     /**
      * The tail of the value queue
      */
-    2: QueueNode<T>;
+    1: QueueNode<T>;
     /**
      * The head of the Promise resolve queue
      */
-    3: QueueNode<(value?: T) => void>;
+    2: QueueNode<(value?: T) => void>;
     /**
      * The tail of the Promise resolve queue
      */
-    4: QueueNode<(value?: T) => void>;
+    3: QueueNode<(value?: T) => void>;
 }
 /**
  * Create a channel
@@ -48,12 +44,7 @@ export declare const recieve: <T>(c: Channel<T>) => Promise<T | undefined>;
  */
 export declare const poll: <T>(c: Channel<T>) => T | undefined;
 /**
- * Close a channel
- * @param c
- */
-export declare const close: <T>(c: Channel<T>) => void;
-/**
- * Check whether a channel is still open
+ * Resolves all pending promises of a channel
  * @param c
  */
-export declare const active: (c: Channel<any>) => boolean;
+export declare const flush: <T>(c: Channel<T>) => void;

package/channel.js

@@ -1 +1 @@
-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];
+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]()};

package/concurrent.d.ts

@@ -2,12 +2,10 @@
  * @module Concurrency controls
  */
 /**
- * Describe a concurrency controller
+ * Describe an async task
  */
-export type Controller = <T>(task: () => Promise<T>) => Promise<T>;
+export type Task<T = unknown> = () => Promise<T>;
 /**
- * Create a concurrency controller, allow n tasks to run concurrently
- * @param n
+ * Describe a concurrency controller
  */
-declare const _default: (n: number) => Controller;
-export default _default;
+export type Controller = <T>(task: Task<T>) => Promise<T>;

package/index.d.ts

@@ -24,6 +24,5 @@ export declare const sequential: (n: number, task: (id: number) => Promise<any>)
  * Spawn n tasks that runs concurrently
  * @param n
  * @param task - The function to run
- * @param concurrency - The amount of task to run concurrently
  */
-export declare const concurrent: (n: number, task: (id: number) => Promise<any>, concurrency?: number) => Promise<any>;
+export declare const concurrent: (n: number, task: (id: number) => Promise<any>) => Promise<any>;

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=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)};
+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=(n,task)=>{let arr=new Array(n);for(let i=0;i<n;i++)arr[i]=task(i);return Promise.all(arr)};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ciorent",
-  "version": "0.0.14",
+  "version": "0.0.15",
   "description": "A lightweight, low-overhead concurrency library",
   "homepage": "https://ciorent.netlify.app",
   "repository": {

package/semaphore.d.ts

@@ -32,6 +32,6 @@ export declare const pause: (s: Semaphore) => Promise<void>;
  */
 export declare const signal: (s: Semaphore) => void;
 /**
- * Create a task that acquire a semaphore and release the access later
+ * Create a task that acquire a semaphore and release the access when it's finished
  */
 export declare const task: <F extends (...args: any[]) => Promise<any>>(s: Semaphore, f: F) => F;

package/semaphore.js

@@ -1 +1 @@
-import{pause as resolvedPromise}from".";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 task=(s,f)=>async(...a)=>{await pause(s);try{return await f(...a)}finally{signal(s)}};
+import{pause as resolvedPromise}from".";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 task=(s,f)=>async(...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)}};

package/topic.d.ts

@@ -58,4 +58,4 @@ export declare const poll: <T extends {}>(t: Subscriber<T>) => T | undefined;
  * Returns a promise that resolves when the message queue is not empty
  * @param t
  */
-export declare const next: <T extends {}>(t: Subscriber<T>) => Promise<T | undefined>;
+export declare const recieve: <T extends {}>(t: Subscriber<T>) => Promise<T | undefined>;

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 next=(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,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)})};

package/concurrent.js

@@ -1 +0,0 @@
-export default (n)=>{let pending=new Array(n);let cnt=0;return async(f)=>{if(cnt<n)return pending[cnt++]=f();await Promise.allSettled(pending);cnt=0;return pending[0]=f()}};