ciorent 0.0.12 → 0.0.14

package/README.md

@@ -1,48 +1,84 @@
-A lightweight, low-overhead concurrency library
-
-# Examples
-## 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.
+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.
 
 ```ts
-import * as channel from 'ciorent/channel';
+import * as latch from 'ciorent/latch';
 import * as cio from 'ciorent';
 
-const c = channel.init<number>();
+const fetchLatch = latch.init();
 
-const run = async () => {
-  for (let i = 0; i < 10; i++) {
-    await cio.sleep(10);
-    channel.send(c, i);
-    console.log('Sent', i);
-  }
+const task = async () => {
+  // Blocks until the latch is open
+  await latch.pause(fetchLatch);
 
-  // Send the closed signal to the reciever
-  // Or else channel.recieve will block forever
-  channel.close(c);
-};
+  const res = await fetch('http://example.com');
+  console.log('Fetch status:', res.status);
+}
 
-const log = async () => {
-  while (true) {
-    // Non-blocking
-    const x = await channel.recieve(c);
+const prepare = () => {
+  console.log('Run before fetch:', performance.now().toFixed(2));
+}
 
-    // 'recieve' returns undefined if
-    // The channel has been closed
-    if (x == null) break;
+const main = async () => {
+  const p = task();
+  await cio.sleep(500);
+  prepare();
 
-    console.log('Recieved', x);
-  };
+  // 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();
-log();
+// Run fetch after 500ms
+await main();
 
-// This runs first
-console.log('Starting...');
+// Run fetch after another 500ms
+await main();
 ```
 
-## Semaphore
+# Pubsub
+A fast, simple publish-subscribe API.
+
+```ts
+import * as topic from 'ciorent/topic';
+import * as cio from 'ciorent';
+
+const messages = topic.init<number>();
+
+// A task that publish messages
+const publisher = async () => {
+  for (let i = 0; i < 5; i++) {
+    await cio.sleep(50);
+    topic.pub(messages, i);
+  }
+
+  // Resolve all waiting promises
+  // And clear the value queue
+  topic.flush(messages);
+}
+
+// Spawn 5 tasks that recieve messages
+cio.concurrent(5, async (id: number) => {
+  const sub = topic.sub(messages);
+
+  while (true) {
+    // Block until
+    const x = await topic.next(sub);
+    if (x == null) break;
+    console.log(`Task ${id}: ${x}`);
+  }
+});
+
+publisher();
+```
+
+# Semaphore
 Semaphore is a concurrency primitive used to control access to a common resource by multiple processes.
 
 ```ts
@@ -66,51 +102,49 @@ const task = semaphore.task(
 cio.concurrent(6, task, 4);
 ```
 
-## Latch
-Latch is a synchronization primitive that allows one process to wait until another completes an operation before continuing execution.
+# 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 latch from 'ciorent/latch';
+import * as channel from 'ciorent/channel';
 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 c = channel.init<number>();
 
-const prepare = () => {
-  console.log('Run before fetch:', performance.now().toFixed(2));
-}
+const run = async () => {
+  for (let i = 0; i < 10; i++) {
+    await cio.sleep(10);
+    channel.send(c, i);
+    console.log('Sent', i);
+  }
 
-const main = async () => {
-  const p = task();
-  await cio.sleep(500);
-  prepare();
+  // Send the closed signal to the reciever
+  // Or else channel.recieve will block forever
+  channel.close(c);
+};
 
-  // Allows all previously blocked tasks to run
-  latch.open(fetchLatch);
+const log = async () => {
+  while (true) {
+    // Non-blocking
+    const x = await channel.recieve(c);
 
-  // Reclose the latch
-  // Tasks that aren't blocked yet will be blocked
-  latch.reset(fetchLatch);
+    // 'recieve' returns undefined if
+    // The channel has been closed
+    if (x == null) break;
 
-  return p;
+    console.log('Recieved', x);
+  };
 }
 
-// Run fetch after 500ms
-await main();
+run();
+log();
 
-// Run fetch after another 500ms
-await main();
+// This runs first
+console.log('Starting...');
 ```
 
-## Utilities
-### Pausing
+# Utilities
+## Pausing
 Delay the execution of a function for other asynchronous tasks to run.
 ```ts
 import * as cio from 'ciorent';
@@ -140,7 +174,7 @@ task1();
 task2();
 ```
 
-### Sleep
+## Sleep
 A cross-runtime sleep function.
 ```ts
 import { sleep } from 'ciorent';
@@ -149,7 +183,7 @@ await sleep(500);
 console.log('Hi');
 ```
 
-### Concurrency
+## Basic concurrency
 Control how many tasks can be executed concurrently.
 ```ts
 import concurrent from 'ciorent/concurrent';
@@ -165,7 +199,7 @@ for (let id = 1; id <= 6; id++)
   });
 ```
 
-### Spawning tasks
+## Spawning tasks
 Creating new tasks with controlled concurrency.
 ```ts
 import * as cio from 'ciorent';

package/dropping-queue.d.ts

@@ -2,7 +2,7 @@
  * @module Dropping queues
  */
 import type { FixedQueue } from './fixed-queue';
-export { default as init } from './fixed-queue';
+export { init } from './fixed-queue';
 export { pop } from './sliding-queue';
 /**
  * Push an item to a dropping queue

package/dropping-queue.js

@@ -1 +1 @@
-export{default as init}from"./fixed-queue";export{pop}from"./sliding-queue";export let push=(q,item)=>{if(q[0][(q[2]+1)%q[1]]!=null)return false;q[0][q[2]=(q[2]+1)%q[1]]=item;return true};
+export{init}from"./fixed-queue";export{pop}from"./sliding-queue";export let push=(q,item)=>{if(q[0][(q[2]+1)%q[1]]!=null)return false;q[0][q[2]=(q[2]+1)%q[1]]=item;return true};

package/fixed-queue.d.ts

@@ -34,5 +34,4 @@ export type QueueNode<T> = [
  * Create a fixed queue.
  * @param n - The queue size
  */
-declare const _default: <T extends {}>(n: number) => FixedQueue<T>;
-export default _default;
+export declare const init: <T extends {}>(n: number) => FixedQueue<T>;

package/fixed-queue.js

@@ -1 +1 @@
-export default (n)=>[new Array(n),n,-1,-1];
+export let init=(n)=>[new Array(n),n,-1,-1];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ciorent",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "description": "A lightweight, low-overhead 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)=>{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)}};
+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)}};

package/sliding-queue.d.ts

@@ -2,7 +2,7 @@
  * @module Sliding queues
  */
 import type { FixedQueue } from './fixed-queue';
-export { default as init } from './fixed-queue';
+export { init } from './fixed-queue';
 /**
  * Push an item to a sliding queue
  * @param q - The queue to push to

package/sliding-queue.js

@@ -1 +1 @@
-export{default as init}from"./fixed-queue";export let push=(q,item)=>{q[0][q[2]=(q[2]+1)%q[1]]=item};export let pop=(q)=>{let val=q[0][(q[3]+1)%q[1]];if(val!=null){q[0][q[3]=(q[3]+1)%q[1]]=null;return val}};
+export{init}from"./fixed-queue";export let push=(q,item)=>{q[0][q[2]=(q[2]+1)%q[1]]=item};export let pop=(q)=>{let val=q[0][(q[3]+1)%q[1]];if(val!=null){q[0][q[3]=(q[3]+1)%q[1]]=null;return val}};

package/topic.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @module Pubsub
+ */
+import type { QueueNode } from './fixed-queue';
+/**
+ * Describe a topic
+ */
+export interface Topic<T extends {}> {
+    /**
+     * The head node of the value queue
+     */
+    0: QueueNode<T>;
+    /**
+     * The waiting subscriber resolves
+     */
+    1: ((res?: T) => void)[];
+    /**
+     * The waiting subscribers
+     */
+    2: Subscriber<T>[];
+}
+/**
+ * Create a topic
+ */
+export declare const init: <T extends {}>() => Topic<T>;
+/**
+ * Describe a topic
+ */
+export interface Subscriber<T extends {}> {
+    0: Topic<T>;
+    1: QueueNode<T>;
+}
+/**
+ * Subscribe to a topic
+ * @param t
+ */
+export declare const sub: <T extends {}>(t: Topic<T>) => Subscriber<T>;
+/**
+ * Subscribe to a topic
+ * @param t
+ */
+export declare const pub: <T extends {}>(t: Topic<T>, value: T) => void;
+/**
+ * Resolve all waiting promises and clear all pending values
+ * @param t
+ */
+export declare const flush: <T extends {}>(t: Topic<T>) => void;
+/**
+ * Get the next value in the message queue.
+ *
+ * Returns `undefined` if the message queue is empty
+ * @param t
+ */
+export declare const poll: <T extends {}>(t: Subscriber<T>) => T | undefined;
+/**
+ * Get the next value in the message queue
+ *
+ * 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>;

package/topic.js

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