Tile cache

TileCache is the shared, byte-budgeted per-channel cache backing the timestamp-based access path, with an idle TTL for freeing memory.

mef3io_server.server.tile_cache

Signal tile cache with a global byte budget.

This is the caching substrate for timestamp-based access. The client asks for any (channels, t1, t2); internally the recording is addressed as a sparse grid of tiles, where each tile holds a fixed number of samples for a single channel over a fixed time window. MEF3 stores each channel independently, so tiling per channel (rather than per channel-block) avoids read amplification when only a few of many channels are requested.

The cache is keyed by an arbitrary hashable (the FileManager uses (file_path, channel, block_index)) so a single instance can be shared across all open files under one global budget -- many open files/clients therefore share one memory ceiling instead of each holding an independent per-file cache.

Key properties:

• Value = a float32 array of samples (float32 halves memory vs float64).
• Presence vs. gaps: a key being present means the tile is loaded; genuine MEF3 discontinuities inside a loaded tile are represented as NaN values. "Not loaded" and "loaded but contains a gap" are therefore distinct.
• Byte-budgeted LRU: eviction is driven by a total byte budget, not a fixed item count, since tiles can differ in size across channels/sampling rates.
• Idle TTL: tiles that have not been accessed for ttl_seconds are discarded, so a finished session (e.g. a detector that moved on) does not pin memory even if the byte budget is never hit.
• Thread-safe: all operations are guarded by a single lock.

TileCache

TileCache(max_bytes: int, ttl_seconds=None)

A thread-safe, byte-budgeted LRU cache of signal tiles.

Parameters:

Name	Type	Description	Default
max_bytes	int	Maximum total size of cached tiles, in bytes. Must be positive. Individual tiles larger than this are never retained.	required
ttl_seconds	float or None	Discard a tile after this many seconds without an access (get/put). None or <= 0 disables idle expiry.	None

get

get(key)

Return the cached tile for key or None; a hit is marked MRU.

put

put(key, array)

Insert or replace a tile, evicting LRU tiles to honor the budget.

The array is stored as float32 (copied only if a cast is needed). Tiles larger than the whole budget are dropped rather than cached.

evict_expired

evict_expired(now=None)

Drop tiles not accessed within ttl_seconds.

A no-op when TTL is disabled. Intended to be called periodically by a background sweeper so idle sessions release memory even without traffic.

Returns:

Type	Description
int	Number of tiles evicted.

evict_matching

evict_matching(predicate)

Drop every tile whose key satisfies predicate(key).

Used to purge a file's tiles when it is closed.

Returns:

Type	Description
int	Number of tiles evicted.

contains

contains(key)

Return whether a tile is cached (without touching LRU order).

clear

clear()

Drop all cached tiles.