ciorent 0.1.0 → 0.1.1

package/README.md

@@ -1,42 +1,4 @@
 A lightweight, low-overhead concurrency library.
-## 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
-import * as channel from 'ciorent/channel';
-import * as cio from 'ciorent';
-
-const c = channel.init<number>();
-
-const run = async () => {
-  for (let i = 0; i < 5; i++) {
-    await cio.sleep(100);
-    channel.send(c, i);
-    console.log('Sent', i);
-  }
-
-  // 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) {
-    // Wait until a value is sent to the channel
-    const x = await channel.recieve(c);
-    if (x == null) break;
-
-    console.log('Recieved', x);
-  };
-}
-
-log();
-run();
-
-// This runs first
-console.log('Starting...');
-```
-
 ## Fibers
 Virtual threads with more controlled execution.
 
@@ -76,42 +38,26 @@ Latch is a synchronization primitive that allows one process to wait until anoth
 
 ```ts
 import * as latch from 'ciorent/latch';
-import * as cio from 'ciorent';
 
-const fetchLatch = latch.init();
+const startFetch = latch.init();
 
 const task = async () => {
   // Blocks until the latch is open
-  await latch.pause(fetchLatch);
+  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);
 }
 
-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();
+task();
+prepare();
 ```
 
 ## Pubsub
@@ -150,6 +96,44 @@ cio.concurrent(3, async (id: number) => {
 publisher();
 ```
 
+## 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
+import * as channel from 'ciorent/channel';
+import * as cio from 'ciorent';
+
+const c = channel.init<number>();
+
+const run = async () => {
+  for (let i = 0; i < 5; i++) {
+    await cio.sleep(100);
+    channel.send(c, i);
+    console.log('Sent', i);
+  }
+
+  // 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) {
+    // Wait until a value is sent to the channel
+    const x = await channel.recieve(c);
+    if (x == null) break;
+
+    console.log('Recieved', x);
+  };
+}
+
+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.
 
@@ -157,22 +141,26 @@ Semaphore is a concurrency primitive used to control access to a common resource
 import * as semaphore from 'ciorent/semaphore';
 import * as cio from 'ciorent';
 
-const task = semaphore.wrap(
-  async (task: number) => {
-    console.log('Task', task, 'started');
+// 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);
 
-    for (let i = 1; i <= 5; i++)
-      await cio.pause;
+  console.log('Task', id, 'started');
 
-    console.log('Task', task, 'end');
-  }
-);
+  // Let the main thread schedules other tasks
+  for (let i = 1; i <= 5; i++) await cio.pause;
 
-// Only allow 2 task to run concurrently
-const sem = semaphore.init(2);
+  console.log('Task', id, 'end');
+
+  // Release the semaphore
+  semaphore.signal(sem);
+}
 
-// Try to run 6 tasks concurrently
-cio.concurrent(6, (sem, id) => task(sem, id), sem);
+// Try to run 5 tasks concurrently
+cio.concurrent(5, task);
 ```
 
 ## Utilities
@@ -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);
 };
 
@@ -214,13 +201,18 @@ Cross-runtime synchronous and asynchronous sleep functions.
 ```ts
 import * as cio from 'ciorent';
 
+const logTime = (label: string) => console.log(label + ':', Math.floor(performance.now()) + 'ms');
+
+logTime('Start');
+
+// Non-blocking
 await cio.sleep(500);
-console.log('Hi');
+logTime('After about 0.5s');
 
-// This blocks the current thread
-// On the browser this only works in workers
+// This blocks the event loop
+// On the browser this only works in workers and blocks the worker thread
 cio.sleepSync(500);
-console.log('Hi');
+logTime('After another 0.5s');
 ```
 
 ### Spawning tasks
@@ -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

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
  */

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--;f(...a);setTimeout(call,ms)}}};export let throttle=(f,ms,limit)=>{let head=[null];let tail=head;let unlock=()=>{if(tail!==head){tail=tail[0];tail[1](f(...tail[2]));setTimeout(unlock,ms)}else limit++};return(...a)=>{if(limit===0){let r;let p=new Promise((res)=>{r=res});head=head[0]=[null,r,a];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.1.0",
+  "version": "0.1.1",
   "description": "A lightweight, low-overhead concurrency library",
   "homepage": "https://ciorent.netlify.app",
   "repository": {
@@ -18,14 +18,14 @@
   "main": "./index.js",
   "types": "./index.d.ts",
   "exports": {
-    "./fixed-queue": "./fixed-queue.js",
     "./sliding-queue": "./sliding-queue.js",
-    "./fiber": "./fiber.js",
-    "./latch": "./latch.js",
-    "./dropping-queue": "./dropping-queue.js",
-    "./topic": "./topic.js",
     "./semaphore": "./semaphore.js",
+    "./topic": "./topic.js",
     ".": "./index.js",
-    "./channel": "./channel.js"
+    "./latch": "./latch.js",
+    "./channel": "./channel.js",
+    "./fixed-queue": "./fixed-queue.js",
+    "./dropping-queue": "./dropping-queue.js",
+    "./fiber": "./fiber.js"
   }
 }