chore: add the RWLock

Author: hugodutka

bun.lock

@@ -47,6 +47,7 @@
         "@opentelemetry/sdk-trace-base": "^2.1.0",
         "@opentelemetry/sdk-trace-node": "^2.1.0",
         "@opentelemetry/semantic-conventions": "^1.37.0",
+        "@rocicorp/lock": "^1.0.4",
         "@types/marked-terminal": "^6.1.1",
         "@types/react": "^19.2.2",
         "@types/ws": "^8.18.1",
@@ -710,6 +711,10 @@
 
     "@radix-ui/react-use-layout-effect": ["@radix-ui/[email protected]", "", { "peerDependencies": { "@types/react": "*", "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" }, "optionalPeers": ["@types/react"] }, "sha512-RbJRS4UWQFkzHTTwVymMTUv8EqYhOp8dOOviLj2ugtTiXRaRQS7GLGxZTLL1jWhMeoSCf5zmcZkqTl9IiYfXcQ=="],
 
+    "@rocicorp/lock": ["@rocicorp/[email protected]", "", { "dependencies": { "@rocicorp/resolver": "^1.0.2" } }, "sha512-FavTiO8ETXFXDVfA87IThGduTTTR8iqzBnr/c60gUUmbk7knGEXPmf2B+yiNuluJD0ku0fL2V2r62UXnsLXl6w=="],
+
+    "@rocicorp/resolver": ["@rocicorp/[email protected]", "", {}, "sha512-TfjMTQp9cNNqNtHFfa+XHEGdA7NnmDRu+ZJH4YF3dso0Xk/b9DMhg/sl+b6CR4ThFZArXXDsG1j8Mwl34wcOZQ=="],
+
     "@rolldown/binding-android-arm64": ["@rolldown/[email protected]", "", { "os": "android", "cpu": "arm64" }, "sha512-TP8bcPOb1s6UmY5syhXrDn9k0XkYcw+XaoylTN4cJxf0JOVS2j682I3aTcpfT51hOFGr2bRwNKN9RZ19XxeQbA=="],
 
     "@rolldown/binding-darwin-arm64": ["@rolldown/[email protected]", "", { "os": "darwin", "cpu": "arm64" }, "sha512-kuVWnZsE4vEjMF/10SbSUyzucIW2zmdsqFghYMqy+fsjXnRHg0luTU6qWF8IqJf4Cbpm9NEZRnjIEPpAbdiSNQ=="],

packages/blink/package.json

@@ -100,6 +100,7 @@
     "@opentelemetry/sdk-trace-base": "^2.1.0",
     "@opentelemetry/sdk-trace-node": "^2.1.0",
     "@opentelemetry/semantic-conventions": "^1.37.0",
+    "@rocicorp/lock": "^1.0.4",
     "@types/marked-terminal": "^6.1.1",
     "@types/react": "^19.2.2",
     "@types/ws": "^8.18.1",

packages/blink/src/local/rw-lock.test.ts

@@ -0,0 +1,107 @@
+import { expect, test } from "bun:test";
+import { RWLock } from "./rw-lock";
+
+// Note: The actual lock logic is handled by the @rocicorp/lock library.
+// These tests verify that our wrapper correctly implements Symbol.asyncDispose
+// and that basic read/write lock semantics work as expected.
+test("RWLock: write lock blocks readers", async () => {
+  const lock = new RWLock();
+  const events: string[] = [];
+
+  let writerAcquired: () => void = () => {
+    throw new Error("writerAcquired not set");
+  };
+  let releaseWriter: () => void = () => {
+    throw new Error("releaseWriter not set");
+  };
+  const writerHasAcquired = new Promise<void>((resolve) => {
+    writerAcquired = resolve;
+  });
+  const writerCanRelease = new Promise<void>((resolve) => {
+    releaseWriter = resolve;
+  });
+
+  // Acquire write lock
+  const writerPromise = (async () => {
+    using writeLock = await lock.write();
+    events.push("writer-acquired");
+    writerAcquired();
+    await writerCanRelease;
+    // give a chance for a bug to happen. it shouldn't!
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    events.push("writer-releasing");
+  })();
+
+  // Wait for writer to actually acquire the lock
+  await writerHasAcquired;
+
+  // Try to acquire read lock (should wait)
+  const readerPromise = (async () => {
+    events.push("reader-waiting");
+    using readLock = await lock.read();
+    events.push("reader-acquired");
+  })();
+
+  releaseWriter();
+
+  await Promise.all([writerPromise, readerPromise]);
+
+  // Reader should wait for writer to release
+  expect(events).toEqual([
+    "writer-acquired",
+    "reader-waiting",
+    "writer-releasing",
+    "reader-acquired",
+  ]);
+});
+
+test("RWLock: readers block write lock", async () => {
+  const lock = new RWLock();
+  const events: string[] = [];
+
+  let readerAcquired: () => void = () => {
+    throw new Error("readerAcquired not set");
+  };
+  let releaseReader: () => void = () => {
+    throw new Error("releaseReader not set");
+  };
+  const readerHasAcquired = new Promise<void>((resolve) => {
+    readerAcquired = resolve;
+  });
+  const readerCanRelease = new Promise<void>((resolve) => {
+    releaseReader = resolve;
+  });
+
+  // Acquire read lock
+  const readerPromise = (async () => {
+    using readLock = await lock.read();
+    events.push("reader-acquired");
+    readerAcquired();
+    await readerCanRelease;
+    // give a chance for a bug to happen. it shouldn't!
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    events.push("reader-releasing");
+  })();
+
+  // Wait for reader to actually acquire the lock
+  await readerHasAcquired;
+
+  // Try to acquire write lock (should wait)
+  const writerPromise = (async () => {
+    events.push("writer-waiting");
+    using writeLock = await lock.write();
+    events.push("writer-acquired");
+  })();
+
+  releaseReader();
+
+  await Promise.all([readerPromise, writerPromise]);
+
+  // Writer should wait for reader to release
+  expect(events).toEqual([
+    "reader-acquired",
+    "writer-waiting",
+    "reader-releasing",
+    "writer-acquired",
+  ]);
+});

packages/blink/src/local/rw-lock.ts

@@ -0,0 +1,64 @@
+import { RWLock as RocicorpRWLock } from "@rocicorp/lock";
+
+export class ReadLock {
+  constructor(private onRelease: () => void) {}
+
+  [Symbol.dispose](): void {
+    this.onRelease();
+  }
+}
+
+export class WriteLock {
+  constructor(private onRelease: () => void) {}
+
+  [Symbol.dispose](): void {
+    this.onRelease();
+  }
+}
+
+/**
+ * RWLock is a read/write lock that allows multiple concurrent readers
+ * or a single writer. Writers wait for all readers to finish before acquiring
+ * the lock.
+ *
+ * This is designed for in-memory, single-process synchronization using the
+ * explicit resource management pattern (Symbol.dispose).
+ *
+ * Example usage:
+ * ```typescript
+ * const lock = new RWLock();
+ *
+ * // Multiple readers can acquire the lock concurrently
+ * using readLock = await lock.read();
+ * // ... do read operations ...
+ *
+ * // Writers wait for all readers to finish
+ * using writeLock = await lock.write();
+ * // ... do write operations ...
+ * ```
+ */
+export class RWLock {
+  private _lock = new RocicorpRWLock();
+
+  /**
+   * Acquire a read lock. Multiple readers can hold the lock concurrently.
+   * If a writer is waiting, new readers will wait until the writer completes.
+   *
+   * The lock is automatically released when the returned object is disposed.
+   */
+  async read(): Promise<ReadLock> {
+    const release = await this._lock.read();
+    return new ReadLock(release);
+  }
+
+  /**
+   * Acquire a write lock. Waits for all readers to finish before acquiring.
+   * Only one writer can hold the lock at a time.
+   *
+   * The lock is automatically released when the returned object is disposed.
+   */
+  async write(): Promise<WriteLock> {
+    const release = await this._lock.write();
+    return new WriteLock(release);
+  }
+}