@camstack/shm-ring 1.0.16 → 1.0.17

package/dist/frame-ring-reader-cache.d.ts

@@ -1,4 +1,22 @@
 import { DecodedFrame, FrameHandle, IScopedLogger } from '@camstack/types';
+/**
+ * Idle grace before a cached reader whose segment stopped appearing in handles
+ * is `munmap`'d and evicted. Longer than any legitimate quiet gap between
+ * frames on a live segment (a stalled camera, a sparse occupancy-recheck poll,
+ * a keyframe wait) so a still-live segment is not churned; short enough that a
+ * rotated-out / restarted-decoder segment's mapping is reclaimed promptly
+ * instead of leaking until subscription teardown. Eviction is functionally
+ * safe (a re-appearing shmId re-opens the segment), so this only trades a rare
+ * remap syscall against how fast `/dev/shm` is reclaimed under rotation churn.
+ */
+export declare const STALE_READER_TTL_MS = 15000;
+/** Injectable knobs for the cache — all optional, all defaulted. */
+export interface FrameRingReaderCacheOptions {
+    /** Wall clock, injectable for deterministic tests. Defaults to `Date.now`. */
+    readonly now?: () => number;
+    /** Override the idle eviction grace. Defaults to {@link STALE_READER_TTL_MS}. */
+    readonly staleReaderTtlMs?: number;
+}
 /**
  * Opens (and caches) a `FrameRingReader` per `shmId` and reads the pixels a
  * `FrameHandle` refers to. Single-consumer — one cache per frame subscription.
@@ -6,8 +24,13 @@ import { DecodedFrame, FrameHandle, IScopedLogger } from '@camstack/types';
 export declare class FrameRingReaderCache {
     private readonly rings;
     private readonly logger;
+    private readonly now;
+    private readonly staleReaderTtlMs;
     private closed;
-    constructor(logger?: IScopedLogger);
+    constructor(logger?: IScopedLogger, options?: FrameRingReaderCacheOptions);
+    /** Number of shm segments currently mapped by this cache. Diagnostic — also
+     *  lets a test observe stale-reader eviction. */
+    get mappedSegmentCount(): number;
     /**
      * Read the pixels a `FrameHandle` refers to and return them as a
      * `DecodedFrame`. Returns `null` when the ring slot was recycled before the
@@ -18,4 +41,21 @@ export declare class FrameRingReaderCache {
     close(): void;
     /** Get the cached reader for a handle's segment, opening it on first use. */
     private ringFor;
+    /**
+     * Close (`munmap`) and evict every cached reader — except `keepShmId`, the
+     * one being looked up right now — whose segment stopped appearing in handles
+     * for longer than `staleReaderTtlMs`. Cheap: a no-op unless more than one
+     * segment is mapped (steady state holds exactly one per subscription), so the
+     * common per-read path does not even iterate.
+     */
+    private sweepStaleRings;
+    /**
+     * Unmap one cached segment and drop it from the map. The native `close()` is
+     * itself idempotent (see `native.ts`), and deleting from the map before the
+     * `munmap` keeps eviction idempotent even if `close()` throws — the reader is
+     * never revived. This only `munmap`s the reader's own view; it does NOT
+     * `shm_unlink` (the decoder that created the segment owns the name), which is
+     * exactly what lets the OS reclaim the backing memory once every view closes.
+     */
+    private closeRing;
 }

package/dist/index.js

@@ -570,8 +570,6 @@ var FrameRingReader = class extends FrameRingBase {
 		};
 	}
 };
-//#endregion
-//#region src/frame-ring-reader-cache.ts
 /**
 * Opens (and caches) a `FrameRingReader` per `shmId` and reads the pixels a
 * `FrameHandle` refers to. Single-consumer — one cache per frame subscription.
@@ -579,9 +577,18 @@ var FrameRingReader = class extends FrameRingBase {
 var FrameRingReaderCache = class {
 	rings = /* @__PURE__ */ new Map();
 	logger;
+	now;
+	staleReaderTtlMs;
 	closed = false;
-	constructor(logger) {
+	constructor(logger, options) {
 		this.logger = logger;
+		this.now = options?.now ?? Date.now;
+		this.staleReaderTtlMs = options?.staleReaderTtlMs ?? 15e3;
+	}
+	/** Number of shm segments currently mapped by this cache. Diagnostic — also
+	*  lets a test observe stale-reader eviction. */
+	get mappedSegmentCount() {
+		return this.rings.size;
 	}
 	/**
 	* Read the pixels a `FrameHandle` refers to and return them as a
@@ -616,28 +623,28 @@ var FrameRingReaderCache = class {
 	close() {
 		if (this.closed) return;
 		this.closed = true;
-		for (const [shmId, ring] of this.rings) try {
-			ring.segment.close();
-		} catch (err) {
-			this.logger?.warn("frame-ring reader: segment close failed", { meta: {
-				shmId,
-				error: (0, _camstack_types.errMsg)(err)
-			} });
-		}
+		for (const [shmId, ring] of this.rings) this.closeRing(shmId, ring);
 		this.rings.clear();
 	}
 	/** Get the cached reader for a handle's segment, opening it on first use. */
 	ringFor(handle) {
+		const now = this.now();
 		const cached = this.rings.get(handle.shmId);
-		if (cached) return cached;
+		if (cached) {
+			cached.lastUsedAt = now;
+			this.sweepStaleRings(now, handle.shmId);
+			return cached;
+		}
 		const slotByteLength = computeSlotByteLength(handle.width, handle.height, handle.format);
 		try {
 			const segment = openSegment(handle.shmId, computeSegmentSize(handle.slotCount, slotByteLength));
 			const ring = {
 				segment,
-				reader: new FrameRingReader(segment.buffer, handle.shmId, handle.slotCount, slotByteLength, handle.nodeId)
+				reader: new FrameRingReader(segment.buffer, handle.shmId, handle.slotCount, slotByteLength, handle.nodeId),
+				lastUsedAt: now
 			};
 			this.rings.set(handle.shmId, ring);
+			this.sweepStaleRings(now, handle.shmId);
 			return ring;
 		} catch (err) {
 			this.logger?.warn("frame-ring reader: openSegment failed", { meta: {
@@ -647,6 +654,44 @@ var FrameRingReaderCache = class {
 			return null;
 		}
 	}
+	/**
+	* Close (`munmap`) and evict every cached reader — except `keepShmId`, the
+	* one being looked up right now — whose segment stopped appearing in handles
+	* for longer than `staleReaderTtlMs`. Cheap: a no-op unless more than one
+	* segment is mapped (steady state holds exactly one per subscription), so the
+	* common per-read path does not even iterate.
+	*/
+	sweepStaleRings(now, keepShmId) {
+		if (this.rings.size <= 1) return;
+		for (const [shmId, ring] of this.rings) {
+			if (shmId === keepShmId) continue;
+			if (now - ring.lastUsedAt <= this.staleReaderTtlMs) continue;
+			this.logger?.debug("frame-ring reader: evicting stale mapping", { meta: {
+				shmId,
+				idleMs: now - ring.lastUsedAt
+			} });
+			this.closeRing(shmId, ring);
+		}
+	}
+	/**
+	* Unmap one cached segment and drop it from the map. The native `close()` is
+	* itself idempotent (see `native.ts`), and deleting from the map before the
+	* `munmap` keeps eviction idempotent even if `close()` throws — the reader is
+	* never revived. This only `munmap`s the reader's own view; it does NOT
+	* `shm_unlink` (the decoder that created the segment owns the name), which is
+	* exactly what lets the OS reclaim the backing memory once every view closes.
+	*/
+	closeRing(shmId, ring) {
+		this.rings.delete(shmId);
+		try {
+			ring.segment.close();
+		} catch (err) {
+			this.logger?.warn("frame-ring reader: segment close failed", { meta: {
+				shmId,
+				error: (0, _camstack_types.errMsg)(err)
+			} });
+		}
+	}
 };
 //#endregion
 exports.FrameRingReader = FrameRingReader;

package/dist/index.mjs

@@ -569,8 +569,6 @@ var FrameRingReader = class extends FrameRingBase {
 		};
 	}
 };
-//#endregion
-//#region src/frame-ring-reader-cache.ts
 /**
 * Opens (and caches) a `FrameRingReader` per `shmId` and reads the pixels a
 * `FrameHandle` refers to. Single-consumer — one cache per frame subscription.
@@ -578,9 +576,18 @@ var FrameRingReader = class extends FrameRingBase {
 var FrameRingReaderCache = class {
 	rings = /* @__PURE__ */ new Map();
 	logger;
+	now;
+	staleReaderTtlMs;
 	closed = false;
-	constructor(logger) {
+	constructor(logger, options) {
 		this.logger = logger;
+		this.now = options?.now ?? Date.now;
+		this.staleReaderTtlMs = options?.staleReaderTtlMs ?? 15e3;
+	}
+	/** Number of shm segments currently mapped by this cache. Diagnostic — also
+	*  lets a test observe stale-reader eviction. */
+	get mappedSegmentCount() {
+		return this.rings.size;
 	}
 	/**
 	* Read the pixels a `FrameHandle` refers to and return them as a
@@ -615,28 +622,28 @@ var FrameRingReaderCache = class {
 	close() {
 		if (this.closed) return;
 		this.closed = true;
-		for (const [shmId, ring] of this.rings) try {
-			ring.segment.close();
-		} catch (err) {
-			this.logger?.warn("frame-ring reader: segment close failed", { meta: {
-				shmId,
-				error: errMsg(err)
-			} });
-		}
+		for (const [shmId, ring] of this.rings) this.closeRing(shmId, ring);
 		this.rings.clear();
 	}
 	/** Get the cached reader for a handle's segment, opening it on first use. */
 	ringFor(handle) {
+		const now = this.now();
 		const cached = this.rings.get(handle.shmId);
-		if (cached) return cached;
+		if (cached) {
+			cached.lastUsedAt = now;
+			this.sweepStaleRings(now, handle.shmId);
+			return cached;
+		}
 		const slotByteLength = computeSlotByteLength(handle.width, handle.height, handle.format);
 		try {
 			const segment = openSegment(handle.shmId, computeSegmentSize(handle.slotCount, slotByteLength));
 			const ring = {
 				segment,
-				reader: new FrameRingReader(segment.buffer, handle.shmId, handle.slotCount, slotByteLength, handle.nodeId)
+				reader: new FrameRingReader(segment.buffer, handle.shmId, handle.slotCount, slotByteLength, handle.nodeId),
+				lastUsedAt: now
 			};
 			this.rings.set(handle.shmId, ring);
+			this.sweepStaleRings(now, handle.shmId);
 			return ring;
 		} catch (err) {
 			this.logger?.warn("frame-ring reader: openSegment failed", { meta: {
@@ -646,6 +653,44 @@ var FrameRingReaderCache = class {
 			return null;
 		}
 	}
+	/**
+	* Close (`munmap`) and evict every cached reader — except `keepShmId`, the
+	* one being looked up right now — whose segment stopped appearing in handles
+	* for longer than `staleReaderTtlMs`. Cheap: a no-op unless more than one
+	* segment is mapped (steady state holds exactly one per subscription), so the
+	* common per-read path does not even iterate.
+	*/
+	sweepStaleRings(now, keepShmId) {
+		if (this.rings.size <= 1) return;
+		for (const [shmId, ring] of this.rings) {
+			if (shmId === keepShmId) continue;
+			if (now - ring.lastUsedAt <= this.staleReaderTtlMs) continue;
+			this.logger?.debug("frame-ring reader: evicting stale mapping", { meta: {
+				shmId,
+				idleMs: now - ring.lastUsedAt
+			} });
+			this.closeRing(shmId, ring);
+		}
+	}
+	/**
+	* Unmap one cached segment and drop it from the map. The native `close()` is
+	* itself idempotent (see `native.ts`), and deleting from the map before the
+	* `munmap` keeps eviction idempotent even if `close()` throws — the reader is
+	* never revived. This only `munmap`s the reader's own view; it does NOT
+	* `shm_unlink` (the decoder that created the segment owns the name), which is
+	* exactly what lets the OS reclaim the backing memory once every view closes.
+	*/
+	closeRing(shmId, ring) {
+		this.rings.delete(shmId);
+		try {
+			ring.segment.close();
+		} catch (err) {
+			this.logger?.warn("frame-ring reader: segment close failed", { meta: {
+				shmId,
+				error: errMsg(err)
+			} });
+		}
+	}
 };
 //#endregion
 export { FrameRingReader, FrameRingReaderCache, FrameRingWriter, MAX_RING_SLOTS, MIN_RING_SLOTS, bytesPerPixel, computeSegmentSize, computeSlotByteLength, createSegment, deriveSlotCount, openSegment, unlinkSegment };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/shm-ring",
-  "version": "1.0.16",
+  "version": "1.0.17",
   "description": "CamStack shared-memory frame ring — cross-platform N-API segment mapping + seqlock ring",
   "keywords": [
     "camstack",