ciorent 0.0.5 → 0.0.7

package/README.md

@@ -77,7 +77,7 @@ console.log('Starting...');
 ```
 
 ## Latch
-Latch is a synchronization tool that works like a gate, pausing tasks until the latch is opened.
+A latch is a synchronization tool that allows one or more threads to wait until a specific condition is met.
 
 ```ts
 import * as latch from 'ciorent/latch';
@@ -151,3 +151,30 @@ const main = async () => {
 // Run fetch after 500ms
 await main();
 ```
+
+## Semaphore
+A semaphore is a synchronization tool to control access to shared resources.
+
+It's essentially a counter that regulates how many threads or processes can access a particular resource or section of code.
+
+```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);
+    }
+
+    await cio.sleep(500);
+    console.log('Task', task, 'end');
+  }
+);
+
+// Try to run 5 tasks concurrently
+for (let i = 1; i <= 5; i++) task(i);
+```

package/channel.d.ts

@@ -2,7 +2,7 @@
  * @module
  * Channels
  */
-type QueueNode<T> = [T, QueueNode<T> | null];
+import type { QueueNode } from './queue';
 /**
  * Describe a channel
  */
@@ -58,4 +58,3 @@ export declare const close: <T>(c: Channel<T>) => void;
  * @param c
  */
 export declare const active: (c: Channel<any>) => boolean;
-export {};

package/index.d.ts

@@ -15,3 +15,11 @@ export declare const pause: Promise<void>;
  * @param ms - Sleep duration in milliseconds
  */
 export declare const sleep: (ms: number) => Promise<void>;
+/**
+ * Spawn n tasks
+ * @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[];

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 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};

package/package.json

@@ -1,21 +1,25 @@
 {
   "name": "ciorent",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "A low-overhead, lightweight concurrency library",
   "homepage": "https://ciorent.netlify.app",
   "repository": {
     "type": "github",
     "url": "https://github.com/re-utils/ciorent"
   },
-  "keywords": [],
+  "keywords": [
+    "low-overhead",
+    "lightweight",
+    "concurrency"
+  ],
   "license": "MIT",
   "type": "module",
   "main": "./index.js",
   "types": "./index.d.ts",
   "scripts": {
     "task": "bun scripts/task.ts",
-    "build:test": "bun task build && bun test",
-    "build:publish": "bun task build && bun task report-size && bun task publish",
+    "build:test": "bun docs && bun task build && bun test",
+    "build:publish": "bun build:test && bun task report-size && bun task publish",
     "lint": "eslint ./src",
     "lint:fix": "eslint ./src --fix",
     "docs": "typedoc ./src/** --entryPointStrategy Expand --plugin typedoc-material-theme --skipErrorChecking"

package/queue/index.d.ts

@@ -1,4 +1,5 @@
 /**
+ * @private
  * @module
  * Queue utilities
  */
@@ -23,6 +24,13 @@ export interface FixedQueue<T extends {}> {
      */
     3: number;
 }
+/**
+ * Describe a queue node (singly linked list node)
+ */
+export type QueueNode<T> = [
+    value: T,
+    next: QueueNode<T> | null
+];
 /**
  * Create a fixed queue.
  * @param n - The queue size

package/semaphore.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @module
+ * Semaphores
+ */
+import type { QueueNode } from './queue';
+/**
+ * Describe a semaphore
+ */
+export interface Semaphore {
+    /**
+     * Current remaining process allowed
+     */
+    0: number;
+    /**
+     * The head of the Promise resolve queue
+     */
+    1: QueueNode<() => void>;
+    /**
+     * The tail of the Promise resolve queue
+     */
+    2: QueueNode<() => void>;
+}
+/**
+ * Create a semaphore that allows n accesses
+ */
+export declare const init: (n: number) => Semaphore;
+/**
+ * Wait until the semaphore allows access
+ */
+export declare const pause: (s: Semaphore) => Promise<void>;
+/**
+ * Signal to the semaphore to release access
+ */
+export declare const signal: (s: Semaphore) => void;
+/**
+ * Create a task that acquire a semaphore and release the access later
+ */
+export declare const task: <F extends (...args: any[]) => Promise<any>>(s: Semaphore, f: F) => F;

package/semaphore.js

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