ciorent 0.0.7 → 0.0.9

package/README.md

@@ -1,44 +1,33 @@
 A low-overhead, cross-runtime concurrency library.
 
-# Usage
-Pausing to prioritize an asynchronous task:
+# Examples
+## 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';
 
-// 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';
+## 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.
 
-await cio.sleep(1000);
-console.log('Slept for about 1s');
-```
-
-Go-like channels for synchronizations:
 ```ts
 import * as channel from 'ciorent/channel';
 
@@ -77,7 +66,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';
@@ -95,9 +84,6 @@ const task = async () => {
 
 const prepare = () => {
   console.log('Run before fetch:', performance.now().toFixed(2));
-
-  // Unblock the latch
-  latch.open(fetchLatch);
 }
 
 const main = async () => {
@@ -105,76 +91,100 @@ const main = async () => {
   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();
 
-// Re-close the latch
-latch.close(fetchLatch);
-
 // Run fetch after another 500ms
 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++) {
-      await cio.pause;
-      console.log('Task', task, 'iteration', i);
-    }
+const task = async (id: number) => {
+  await cio.sleep(Math.random() * 20 + 50);
+  console.log('Task', id, 'done');
+}
 
-    await cio.sleep(500);
-    console.log('Task', task, 'end');
-  }
-);
+// Spawn and run 5 tasks sequentially
+console.log('Running sequentially:');
+cio.sequential(5, task);
+
+// Spawn and run 5 tasks concurrently
+console.log('Running concurrently:');
+cio.concurrent(5, task);
 
-// Try to run 5 tasks concurrently
-for (let i = 1; i <= 5; i++) task(i);
+// 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/concurrent.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @module
+ * Concurrency controls
+ */
+/**
+ * Describe a concurrency controller
+ */
+export type Controller = <T>(task: () => Promise<T>) => Promise<T>;
+/**
+ * Create a concurrency controller, allow n tasks to run concurrently
+ * @param n
+ */
+declare const _default: (n: number) => Controller;
+export default _default;

package/concurrent.js

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

package/index.d.ts

@@ -16,10 +16,15 @@ export declare const pause: Promise<void>;
  */
 export declare const sleep: (ms: number) => Promise<void>;
 /**
- * Spawn n tasks
+ * Spawn n tasks that runs sequentially
  * @param n
  * @param task - The function to run
- * @param args - The arguments to pass in the function
- * @returns
  */
-export declare const spawn: <Args extends any[], R extends Promise<any>>(n: number, task: (...args: Args) => R, ...args: Args) => R[];
+export declare const sequential: (n: number, task: (id: number) => Promise<any>) => Promise<void>;
+/**
+ * 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>;

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 spawn=(n,task,...args)=>{let a=new Array(n);while(n--!==0)a[n]=task(...args);return 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)}));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

@@ -22,6 +22,6 @@ export declare const pause: (latch: Latch) => Promise<void>;
  */
 export declare const open: (latch: Latch) => void;
 /**
- * Close a latch
+ * Re-close a latch
  */
-export declare const close: (latch: Latch) => void;
+export declare const reset: (latch: Latch) => void;

package/latch.js

@@ -1 +1 @@
-import{pause as endPromise}from".";export let init=()=>{let r;return[new Promise((res)=>{r=res}),r]};export let pause=(latch)=>latch[0];export let open=(latch)=>{latch[1]();latch[0]=endPromise};export let close=(latch)=>{if(latch[0]===endPromise){let r;latch[0]=new Promise((res)=>{r=res});latch[1]=r}};
+import{pause as endPromise}from".";export let init=()=>{let r;return[new Promise((res)=>{r=res}),r]};export let pause=(latch)=>latch[0];export let open=(latch)=>{latch[1]();latch[0]=endPromise};export let reset=(latch)=>{if(latch[0]===endPromise){let r;latch[0]=new Promise((res)=>{r=res});latch[1]=r}};

package/package.json

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

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)=>{if(s[0]===0){let r;let p=new Promise((res)=>{r=res});s[1]=s[1][1]=[r,null];return p}s[0]--;return resolvedPromise};export let signal=(s)=>{if(s[1]===s[2])s[0]++;else(s[2]=s[2][1])[0]()};export let task=(s,f)=>async(...a)=>{try{await pause(s);return 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)=>{try{await pause(s);return await f(...a)}finally{signal(s)}};