ciorent 0.0.8 → 0.0.9

package/README.md

@@ -1,53 +1,42 @@
 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';
-
-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);
   }
@@ -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';
@@ -119,62 +108,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 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/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/package.json

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