Skip to content

[Feature]: Reclaim/evict transmission-cache ids in long-running sessions #11

Description

@hisanari-dev

Motivation

Transmission cache entries are never evicted except at VimLeavePre (or the test-only _reset()) — an idle entry's id and terminal-side pixel data are deliberately kept around so a later show() of the same file is cheap. But this means blit's reserved id pool (65,536 ids, per docs/spec/kitty-graphics.md's reserved range 0x626C0000-0x626CFFFF) is never reclaimed during a long-running session that show()s many distinct files. Documented as an accepted v0.x limitation in docs/spec/renderer-placement.md's "Transmission cache" section ("mirrors that memo's own acceptance of the range being merely 'negligible collision risk', not infinite").

Proposed Solution

Add an eviction policy for idle cache entries once the id pool nears exhaustion — e.g. LRU eviction of idle entries (freeing both the Lua-side cache entry and the terminal-side pixel data via d=I) triggered when alloc_id() is close to returning nil, err for range exhaustion. Needs a measurement first per AGENTS.md's performance rules ("every perf-motivated complexity increase must cite a measurement") — this issue should start with confirming whether any realistic session actually approaches 65,536 distinct transmitted files before designing the eviction policy itself.

Alternatives Considered

  • Do nothing (status quo): acceptable unless/until a real session hits the limit — alloc_id() already fails safely (nil, err) and show() propagates that as a normal error rather than crashing.
  • Evict eagerly (small idle-entry cap): would undermine the "cache stays warm" performance goal for the common case of showing/hiding the same handful of images repeatedly (e.g. scrolling a file back into view) — rejected as the default without evidence it's needed.

Additional Context

Lowest priority of the v1.0-milestone issues; purely a scale concern for long-running sessions with many distinct images, not a correctness bug.

Checklist

  • I have searched existing issues to make sure this is not a duplicate.
  • I have described the problem and the proposed solution clearly.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions