@nxtedition/lib 26.4.8 → 26.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nxtedition/lib",
-  "version": "26.4.8",
+  "version": "26.6.0",
   "license": "MIT",
   "author": "Robert Nagy <robert.nagy@boffins.se>",
   "type": "module",
@@ -24,6 +24,7 @@
     "deepstream.js",
     "deepstream.d.ts",
     "sequence.js",
+    "shared.js",
     "logger.js",
     "logger.d.ts",
     "mime.js",

package/shared.js

@@ -0,0 +1,367 @@
+// By placing the read and write indices far apart (multiples of a common
+// cache line size, 64 bytes), we prevent "false sharing". This is a
+// low-level CPU optimization where two cores writing to different variables
+// that happen to be on the same cache line would otherwise constantly
+// invalidate each other's caches, hurting performance.
+// Int32 is 4 bytes, so an index of 16 means 16 * 4 = 64 bytes offset.
+const WRITE_INDEX = 0
+const READ_INDEX = 16
+
+// High-Water Mark for batching operations to reduce the frequency
+// of expensive atomic writes.
+const HWM_BYTES = 256 * 1024 // 256 KiB
+const HWM_COUNT = 1024 // 1024 items
+
+/**
+ * Allocates the shared memory buffers.
+ * @param {number} size The size of the main data buffer in bytes.
+ * @returns {{sharedState: SharedArrayBuffer, sharedBuffer: SharedArrayBuffer}}
+ */
+export function alloc(size) {
+  return {
+    // A small buffer for sharing state (read/write pointers).
+    sharedState: new SharedArrayBuffer(128),
+    // The main buffer for transferring data.
+    sharedBuffer: new SharedArrayBuffer(size),
+  }
+}
+
+/**
+ * Creates a reader for the ring buffer.
+ * @param {{ sharedState: SharedArrayBuffer, sharedBuffer: SharedArrayBuffer, hwmItems?: number }} options
+ * @returns {{ readSome: function }}
+ */
+export function reader({ sharedState, sharedBuffer }) {
+  const state = new Int32Array(sharedState)
+  const size = sharedBuffer.byteLength
+  const buffer = Buffer.from(sharedBuffer)
+  const view = new DataView(sharedBuffer)
+
+  // This object is reused to avoid creating new objects in a hot path.
+  // This helps V8 maintain a stable hidden class for the object,
+  // which is a key optimization (zero-copy read).
+  const data = { buffer, view, offset: 0, length: 0 }
+
+  // Local copies of the pointers. The `| 0` is a hint to the V8 JIT
+  // compiler that these are 32-bit integers, enabling optimizations.
+  let readPos = Atomics.load(state, READ_INDEX) | 0
+  let writePos = Atomics.load(state, WRITE_INDEX) | 0
+
+  /**
+   * Reads a batch of messages from the buffer.
+   * @param {(data: {buffer: Buffer, view: DataView, offset: number, length: number}) => void} next Callback to process a message.
+   * @returns {number} The number of messages read.
+   */
+  function readSome(next) {
+    let count = 0
+    let bytes = 0
+
+    // First, check if the local writePos matches the readPos.
+    // If so, refresh it from shared memory in case the writer has added data.
+    if (readPos === writePos) {
+      writePos = Atomics.load(state, WRITE_INDEX) | 0
+    }
+
+    // Process messages in a batch to minimize loop and atomic operation overhead.
+    while (count < HWM_COUNT && bytes < HWM_BYTES && readPos !== writePos) {
+      const dataPos = readPos + 4
+      const dataLen = view.getInt32(dataPos - 4, true) | 0
+
+      // A length of -1 is a special marker indicating the writer has
+      // wrapped around to the beginning of the buffer.
+      if (dataLen === -1) {
+        bytes += 4
+        readPos = 0
+        // After wrapping, we must re-check against the writer's position.
+        // It's possible the writer is now at a position > 0.
+        writePos = Atomics.load(state, WRITE_INDEX) | 0
+      } else {
+        if (dataLen < 0) {
+          throw new Error('Invalid data length')
+        }
+        if (dataPos + dataLen > size) {
+          throw new Error('Data exceeds buffer size')
+        }
+
+        bytes += dataLen
+        readPos += 4 + dataLen
+        count += 1
+
+        // This is a "zero-copy" operation. We don't copy the data out.
+        // Instead, we pass a "view" into the shared buffer.
+        data.offset = dataPos
+        data.length = dataLen
+        next(data)
+
+        if (readPos === writePos) {
+          // If we reach the end of the buffer, we must re-check the writer's position.
+          writePos = Atomics.load(state, WRITE_INDEX) | 0
+        }
+      }
+    }
+
+    // IMPORTANT: The reader only updates its shared `readPos` after a batch
+    // is processed. This significantly reduces atomic write contention.
+    if (bytes > 0) {
+      Atomics.store(state, READ_INDEX, readPos)
+    }
+
+    return count
+  }
+
+  return { readSome }
+}
+
+/**
+ * @param {{ sharedState: SharedArrayBuffer, sharedBuffer: SharedArrayBuffer }} param0
+ * @param {{ yield?: function, logger?: import('pino').Logger }} param1
+ * @returns {{ write: function, cork: function(function) }}
+ */
+export function writer({ sharedState, sharedBuffer }, { yield: onYield, logger } = {}) {
+  const state = new Int32Array(sharedState)
+  const size = sharedBuffer.byteLength
+  const buffer = Buffer.from(sharedBuffer)
+  const view = new DataView(sharedBuffer)
+
+  // This object is reused to avoid creating new objects in a hot path.
+  // This helps V8 maintain a stable hidden class for the object,
+  // which is a key optimization (zero-copy read).
+  const data = { buffer, view, offset: 0, length: 0 }
+
+  // Local copies of the pointers. The `| 0` is a hint to the V8 JIT
+  // compiler that these are 32-bit integers, enabling optimizations.
+  let readPos = Atomics.load(state, READ_INDEX) | 0
+  let writePos = Atomics.load(state, WRITE_INDEX) | 0
+
+  let yielding = false
+  let corked = 0
+  let pending = 0
+
+  if (onYield != null && typeof onYield !== 'function') {
+    throw new TypeError('onYield must be a function')
+  }
+
+  /**
+   * Pauses the writer thread to wait for the reader to catch up.
+   * @param {number} delay The timeout for Atomics.wait.
+   */
+  function _yield(delay) {
+    if (yielding) {
+      throw new Error('Cannot yield while yielding')
+    }
+
+    // First, ensure the very latest write position is visible to the reader.
+    _flush()
+
+    if (onYield) {
+      yielding = true
+      try {
+        // Call the user-provided yield function, if any. This can be important
+        // if the writer is waiting for the reader to process data which would
+        // otherwise deadlock.
+        onYield()
+      } finally {
+        yielding = false
+      }
+    }
+
+    // Atomics.wait is the most efficient way to pause. It puts the thread
+    // to sleep, consuming no CPU, until the reader changes the READ_INDEX.
+    if (delay > 0) {
+      Atomics.wait(state, READ_INDEX, readPos, delay)
+    }
+
+    // After waking up, refresh the local view of the reader's position.
+    readPos = Atomics.load(state, READ_INDEX) | 0
+  }
+
+  /**
+   * Tries to acquire enough space in the buffer for a new message.
+   * @param {number} len The length of the data payload to be written.
+   * @returns {boolean} True if space was acquired, false otherwise.
+   */
+  function _acquire(len) {
+    // Total space required: payload + its 4-byte length header + a potential
+    // 4-byte header for the *next* message (for wrap-around check).
+    const required = len + 4 + 4
+
+    if (required < 0) {
+      throw new Error(`Required length ${required} is negative, expected at least 0`)
+    }
+    if (required > size) {
+      throw new Error(`Required length ${required} exceeds buffer size ${size}`)
+    }
+
+    if (writePos >= readPos) {
+      // Case 1: The writer is ahead of the reader. [ 0 ---- R ... W ---- S ]
+      // There is free space from W to the end (S) and from 0 to R.
+      if (size - writePos >= required) {
+        // Enough space at the end of the buffer.
+        return true
+      }
+
+      // Not enough space at the end. Check if there's space at the beginning.
+      if (readPos === 0) {
+        // Reader is at the very beginning, so no space to wrap around into.
+        return false
+      }
+
+      // Mark the current position with a wrap-around signal (-1).
+      view.setInt32(writePos, -1, true)
+
+      // Reset writer position to the beginning.
+      writePos = 0
+
+      if (writePos + 4 > size) {
+        throw new Error(`Write position ${writePos} with next header exceeds buffer size ${size}`)
+      }
+      if (writePos === readPos) {
+        throw new Error(`Write position ${writePos} cannot equal read position ${readPos}`)
+      }
+
+      Atomics.store(state, WRITE_INDEX, writePos)
+    }
+
+    // Case 2: The writer has wrapped around. [ 0 ... W ---- R ... S ]
+    // The only free space is between W and R.
+    return readPos - writePos >= required
+  }
+
+  /**
+   * "Uncorks" the stream by publishing the pending write position.
+   * This is called from a microtask to batch atomic stores.
+   */
+  function _uncork() {
+    corked -= 1
+    if (corked === 0) {
+      _flush()
+    }
+  }
+
+  /**
+   * Performs the actual write into the buffer after space has been acquired.
+   * @param {number} len The exact length of the payload.
+   * @param {({ buffer, view, offset, length }) => number} fn The callback that writes the data.
+   * @returns {void}
+   */
+  function _write(len, fn) {
+    const dataPos = writePos + 4
+
+    data.offset = dataPos
+    data.length = len
+
+    // The user-provided function writes the data and returns the final position.
+    // We calculate the actual bytes written from that.
+    const dataLen = fn(data) - dataPos
+
+    if (dataLen < 0) {
+      throw new Error(`Data length ${dataLen} is negative`)
+    }
+    if (dataLen > len) {
+      throw new Error(`Data length ${dataLen} exceeds expected length ${len}`)
+    }
+    if (dataPos + dataLen > size) {
+      throw new Error(`Data position ${dataPos} with length ${dataLen} exceeds buffer size ${size}`)
+    }
+
+    // Write the actual length of the data into the 4-byte header.
+    view.setInt32(writePos, dataLen, true)
+    writePos += 4 + dataLen
+
+    if (writePos + 4 > size) {
+      throw new Error(`Write position ${writePos} with next header exceeds buffer size ${size}`)
+    }
+    if (writePos === readPos) {
+      throw new Error(`Write position ${writePos} cannot equal read position ${readPos}`)
+    }
+
+    // This is the "corking" optimization. Instead of calling Atomics.store
+    // on every write, we batch them. We either write when a certain
+    // amount of data is pending (HWM_BYTES) or at the end of the current
+    // JS microtask. This drastically reduces atomic operation overhead.
+    if (pending >= HWM_BYTES) {
+      Atomics.store(state, WRITE_INDEX, writePos)
+      pending = 0
+    } else {
+      pending += 4 + dataLen
+      if (corked === 0) {
+        corked += 1
+        setImmediate(_uncork)
+      }
+    }
+  }
+
+  /**
+   * Public write method. Acquires space and writes data.
+   * @param {number} len The maximum expected length of the payload.
+   * @param {({ buffer, view, offset, length }) => number} fn The callback that writes the data.
+   */
+  function writeSync(len, fn) {
+    if (len < 0) {
+      throw new Error(`Length ${len} is negative`)
+    }
+    if (len >= 2 ** 31 || len > size - 8) {
+      throw new Error(`Length ${len} exceeds maximum allowed size`)
+    }
+
+    if (!_acquire(len)) {
+      readPos = Atomics.load(state, READ_INDEX) | 0
+      if (!_acquire(len)) {
+        const startTime = performance.now()
+        logger?.warn({ readPos, writePos }, 'yield started')
+        _yield(0)
+        while (!_acquire(len)) {
+          _yield(3)
+        }
+        const elapsedTime = performance.now() - startTime
+        logger?.warn({ readPos, writePos, elapsedTime }, 'yield completed')
+      }
+    }
+
+    _write(len, fn)
+
+    if (writePos === readPos) {
+      throw new Error(`Write position ${writePos} cannot equal read position ${readPos}`)
+    }
+  }
+
+  function tryWrite(len, fn) {
+    if (len < 0) {
+      throw new Error(`Length ${len} is negative`)
+    }
+    if (len >= 2 ** 31 || len > size - 8) {
+      throw new Error(`Length ${len} exceeds maximum allowed size`)
+    }
+
+    if (!_acquire(len)) {
+      readPos = Atomics.load(state, READ_INDEX) | 0
+      if (!_acquire(len)) {
+        return false
+      }
+    }
+
+    _write(len, fn)
+
+    if (writePos === readPos) {
+      throw new Error(`Write position ${writePos} cannot equal read position ${readPos}`)
+    }
+  }
+
+  function _flush() {
+    if (pending > 0) {
+      Atomics.store(state, WRITE_INDEX, writePos)
+      pending = 0
+    }
+  }
+
+  function cork(callback) {
+    corked += 1
+    try {
+      return callback()
+    } finally {
+      _uncork()
+    }
+  }
+
+  return { tryWrite, writeSync, cork }
+}