@gmod/tabix 3.5.7 → 3.6.0

package/src/tabixIndexedFile.ts

@@ -1,10 +1,10 @@
-import AbortablePromiseCache from '@gmod/abortable-promise-cache'
 import { unzip, unzipChunkSlice } from '@gmod/bgzf-filehandle'
+import { SharedReadCache } from '@gmod/shared-read-cache'
 import { LocalFile, RemoteFile } from 'generic-filehandle2'
 
 import CSI from './csi.ts'
 import TBI from './tbi.ts'
-import { optimizeChunks } from './util.ts'
+import { optimizeChunks, throwIfAborted } from './util.ts'
 
 import type Chunk from './chunk.ts'
 import type IndexFile from './indexFile.ts'
@@ -29,105 +29,28 @@ const MAX_READ_AHEAD_CHUNKS = 6
 // a dense VCF (test/data/1kg.chr1.subset.vcf.gz — 213MB over 600kb of chr1)
 // has single index bins of 17MB compressed, 120MB decompressed. Panning it
 // under the old 80-entry cache peaked at 2GB RSS.
-const DEFAULT_CHUNK_CACHE_BYTES = 100 * 2 ** 20
-
-// The entry type AbortablePromiseCache stores in its backing cache. Not exported
-// by the package, so it is recovered from the constructor signature rather than
-// restated (and left to drift) here.
-type CacheEntry = NonNullable<
-  ReturnType<
-    ConstructorParameters<
-      typeof AbortablePromiseCache<Chunk, ReadChunk>
-    >[0]['cache']['get']
-  >
->
-
-interface CachedChunk {
-  entry: CacheEntry
-  /** 0 until the read settles and the decompressed size is known */
-  bytes: number
-}
-
-/**
- * Backing store for the chunk cache, bounded by the decompressed size of the
- * chunks it holds rather than by entry count.
- *
- * A chunk's size is only known once its read settles, so `set` records the
- * entry immediately and charges it to the budget later. Unsettled entries are
- * therefore free, which is what we want: they are reads a query is waiting on.
- */
-class ByteBoundedChunkCache {
-  private entries = new Map<string, CachedChunk>()
-  private bytes = 0
-  private maxBytes: number
-
-  constructor(maxBytes: number) {
-    this.maxBytes = maxBytes
-  }
-
-  get byteSize() {
-    return this.bytes
-  }
-
-  get size() {
-    return this.entries.size
-  }
-
-  has(key: string) {
-    return this.entries.has(key)
-  }
-
-  get(key: string) {
-    const cached = this.entries.get(key)
-    if (cached) {
-      // re-insert so Map iteration order stays least-recently-used first
-      this.entries.delete(key)
-      this.entries.set(key, cached)
-    }
-    return cached?.entry
-  }
-
-  set(key: string, entry: CacheEntry) {
-    this.delete(key)
-    const cached = { entry, bytes: 0 }
-    this.entries.set(key, cached)
-    void entry.promise
-      .then(chunk => {
-        // a later set() may have replaced this key while the read was in
-        // flight; charging these bytes to it would then double-count
-        if (this.entries.get(key) === cached) {
-          cached.bytes = chunk.buffer.byteLength
-          this.bytes += cached.bytes
-          this.evict()
-        }
-      })
-      .catch(() => {
-        // a failed or aborted read caches nothing and costs nothing
-      })
-  }
-
-  delete(key: string) {
-    const cached = this.entries.get(key)
-    if (cached) {
-      this.entries.delete(key)
-      this.bytes -= cached.bytes
-    }
-  }
-
-  keys() {
-    return this.entries.keys()
-  }
+//
+// That 120MB figure is also why this is no longer 100MB. A budget below one
+// query's working set does not cache less, it caches NOTHING: each entry is
+// evicted before the next pan can reuse it, so the hit rate is zero and the
+// decompress is paid again every time. On that same fixture, a six-window 50kb
+// pan measured 17 refills out of 17 — a total miss — at 100MB, against 0 at
+// 800MB, and 2596ms against 600ms. The working set plateaus at 497MB held, so
+// 1GB clears it with headroom and nothing above 800MB buys anything.
+//
+// Affordable as a ceiling only because of the idle timeout below: it is a peak
+// under panning, not a level a parked consumer holds. A small file is
+// unaffected either way, this being a ceiling and not an allocation.
+const DEFAULT_CHUNK_CACHE_BYTES = 1024 * 2 ** 20
 
-  // Evict from the least-recently-used end. The size > 1 guard means a single
-  // chunk larger than the whole budget is still kept: the caller needs it for
-  // the query in flight, and dropping it would only force a re-decompress.
-  private evict() {
-    const lru = this.entries.keys()
-    while (this.bytes > this.maxBytes && this.entries.size > 1) {
-      this.delete(lru.next().value!)
-    }
-  }
-}
+// SYNC: ~/src/gmod/bam-js/src/bamFile.ts DEFAULT_CACHE_IDLE_TIMEOUT_MS
+//
+// Drop a chunk nothing has looked at for three minutes. The budget above is
+// only applied when a read settles, so it does nothing at all for a consumer
+// sitting still — and a genome browser holds one of these per track for as long
+// as the track is open. Timed from the last read, not the fetch, so panning
+// back and forth over one region never expires it.
+const DEFAULT_CHUNK_CACHE_IDLE_TIMEOUT_MS = 3 * 60 * 1000
 
 type GetLinesCallback = (
   line: string,
@@ -353,8 +276,15 @@ function parseIntFromBytes(buffer: Uint8Array, start: number, end: number) {
 export default class TabixIndexedFile {
   private filehandle: GenericFilehandle
   private index: IndexFile
-  private chunkCache: AbortablePromiseCache<Chunk, ReadChunk>
+  public chunkCache: SharedReadCache<Chunk, ReadChunk>
   private headerP?: Promise<{ header: string; skippedLines: string[] }>
+  /**
+   * The signal `headerP` was started under, while it is still in flight. The
+   * header is parsed once and shared by every caller, so without this the first
+   * one to arrive would own a read all the others depend on — see
+   * {@link getParsedHeader}.
+   */
+  private headerSignal?: AbortSignal
 
   constructor({
     path,
@@ -367,6 +297,7 @@ export default class TabixIndexedFile {
     csiUrl,
     csiFilehandle,
     chunkCacheSize = DEFAULT_CHUNK_CACHE_BYTES,
+    chunkCacheIdleTimeoutMs = DEFAULT_CHUNK_CACHE_IDLE_TIMEOUT_MS,
   }: {
     path?: string
     filehandle?: GenericFilehandle
@@ -377,8 +308,24 @@ export default class TabixIndexedFile {
     csiPath?: string
     csiUrl?: string
     csiFilehandle?: GenericFilehandle
-    /** budget for the decompressed chunk cache, in bytes */
+    /**
+     * Budget for the decompressed chunk cache, in bytes. Default 1GB.
+     *
+     * A retention bound, not a bound on peak memory: reads in flight are never
+     * evicted and the last settled entry is kept whatever the budget. Size it
+     * to hold several queries — below one query's working set the hit rate
+     * drops to zero while the memory is retained anyway, so a number between
+     * the two is the worst available choice.
+     */
     chunkCacheSize?: number
+    /**
+     * Drop a cached chunk once nothing has read it for this many milliseconds.
+     * Default 3 minutes; `0` keeps chunks until `chunkCacheSize` evicts them.
+     *
+     * The only thing that lowers the cache while nothing is happening, and what
+     * makes the budget above a peak rather than a resting level.
+     */
+    chunkCacheIdleTimeoutMs?: number
   }) {
     this.filehandle = resolveFilehandle(filehandle, path, url)
     this.index = resolveIndex({
@@ -392,13 +339,29 @@ export default class TabixIndexedFile {
       url,
     })
 
-    this.chunkCache = new AbortablePromiseCache<Chunk, ReadChunk>({
-      cache: new ByteBoundedChunkCache(chunkCacheSize),
-      fill: (args: Chunk, signal?: AbortSignal) =>
-        this.readChunk(args, { signal }),
+    this.chunkCache = new SharedReadCache<Chunk, ReadChunk>({
+      maxSize: chunkCacheSize,
+      // decompressed bytes, not entry count: we fetch compressed and cache
+      // decompressed, and an entry is a whole chunk
+      sizeOf: read => read.buffer.byteLength,
+      cacheKey: chunk => chunk.toString(),
+      idleTimeoutMs: chunkCacheIdleTimeoutMs,
+      fill: (chunk, signal) => this.readChunk(chunk, { signal }),
     })
   }
 
+  /**
+   * Drops every decompressed chunk held by the cache, and stops the idle sweep
+   * until something is cached again.
+   *
+   * `chunkCacheIdleTimeoutMs` reclaims a view the user has wandered away from;
+   * this is for a consumer that knows it is finished — a closed track, a
+   * changed assembly — and should not have to wait it out.
+   */
+  clearChunkCache() {
+    this.chunkCache.clear()
+  }
+
   /**
    * Estimates the compressed byte size of the index chunks covering the given
    * regions. Useful for byte budgeting before issuing a `getLines` call to
@@ -505,7 +468,7 @@ export default class TabixIndexedFile {
     const ensureReadsStarted = (count: number) => {
       while (reads.length < Math.min(count, chunks.length)) {
         const c = chunks[reads.length]!
-        const read = this.chunkCache.get(c.toString(), c, signal)
+        const read = this.chunkCache.get(c, signal)
         void read.catch(() => {
           // a prefetch the early return skips is never awaited, so swallow its
           // rejection here rather than let it surface unhandled
@@ -670,12 +633,66 @@ export default class TabixIndexedFile {
     }
   }
 
-  private async getParsedHeader(opts: Options = {}) {
-    this.headerP ??= this.parseHeader(opts).catch((error: unknown) => {
-      this.headerP = undefined
-      throw error
-    })
-    return this.headerP
+  /**
+   * Parse the header, or join the parse already running.
+   *
+   * `parseHeader` threads `opts` into both `getMetadata` and the header read,
+   * so memoizing it on the first caller's opts put that caller's signal in
+   * charge of a read every later caller joins: when it aborted, they failed
+   * with its cancellation, their own signals untouched.
+   *
+   * A caller that joined someone else's parse and saw it fail because *they*
+   * aborted starts over rather than inheriting the failure — once, then
+   * propagates. Same bounded retry, and the same reasoning, as
+   * `IndexFile.parse`.
+   *
+   * SYNC: ~/src/gmod/bam-js/src/bamFile.ts getHeader — same shape for the same
+   * reason, on the header rather than the index.
+   */
+  private async getParsedHeader(
+    opts: Options = {},
+    retried = false,
+  ): Promise<{ header: string; skippedLines: string[] }> {
+    throwIfAborted(opts.signal)
+    const pending = this.headerP
+    if (!pending) {
+      return this.startHeaderParse(opts)
+    }
+
+    // read before awaiting: the owner is forgotten as soon as the parse settles
+    const ownerSignal = this.headerSignal
+    try {
+      return await pending
+    } catch (e) {
+      if (retried || !ownerSignal?.aborted || opts.signal?.aborted) {
+        throw e
+      }
+      return this.getParsedHeader(opts, true)
+    }
+  }
+
+  private startHeaderParse(opts: Options) {
+    const pending = this.parseHeader(opts)
+    this.headerP = pending
+    this.headerSignal = opts.signal
+    // Drop a rejection rather than keeping it, so one transient failure does not
+    // poison the header for the lifetime of the file. Both branches are
+    // identity-checked so a retry started after this settles is not cleared by
+    // the attempt it already replaced.
+    pending.then(
+      () => {
+        if (this.headerP === pending) {
+          this.headerSignal = undefined
+        }
+      },
+      () => {
+        if (this.headerP === pending) {
+          this.headerP = undefined
+          this.headerSignal = undefined
+        }
+      },
+    )
+    return pending
   }
 
   /**

package/src/util.ts

@@ -5,36 +5,10 @@ import { longFromBytesToUnsigned } from './long.ts'
 import VirtualOffset from './virtualOffset.ts'
 
 // SYNC: ~/src/gmod/bam-js/src/util.ts optimizeChunks
-/**
- * `signal.throwIfAborted()`, without requiring either that method or `reason`.
- *
- * Two reasons not to call the built-in directly. It assumes a *real*
- * `AbortSignal`, and callers pass duck-typed ones, where calling a missing
- * method is a `TypeError` rather than the cancellation the caller asked for —
- * a strictly worse failure.
- *
- * And it sets a browser floor. `AbortSignal.prototype.throwIfAborted` and
- * `AbortSignal.reason` are Safari 15.4 / Chrome 100 / Firefox 97 (March 2022),
- * higher than anything else here needs: this package otherwise touches only
- * `.aborted`, and `generic-filehandle2` only forwards a signal to `fetch`.
- *
- * Faithful to the spec otherwise: an aborted signal throws its `reason`
- * whatever that is, and only synthesizes an `AbortError` when there is none.
- * Kept in sync with the copy in `@gmod/bam`'s `src/util.ts`.
- */
-export function throwIfAborted(signal?: AbortSignal) {
-  if (signal?.aborted) {
-    const reason: unknown = signal.reason
-    // Spec-faithful: throwIfAborted throws `reason` verbatim, and `reason` is
-    // whatever the caller passed to abort() — `controller.abort('too slow')`
-    // makes it a string. Coercing it to an Error here would hide that from a
-    // consumer who set it deliberately.
-    // eslint-disable-next-line @typescript-eslint/only-throw-error
-    throw reason === undefined
-      ? new DOMException('This operation was aborted', 'AbortError')
-      : reason
-  }
-}
+// Re-exported so the internal import path stays './util.ts'. The
+// implementation moved to @gmod/shared-read-cache, which needs it anyway --
+// every consumer of that package was carrying an identical copy.
+export { throwIfAborted } from '@gmod/shared-read-cache'
 
 export function optimizeChunks(chunks: Chunk[], lowest?: VirtualOffset) {
   const n = chunks.length