Caches tile processors so that repeated decompress calls on the same codec can reuse SOT metadata, packet data, and decompressed images. More...

#include <TileCache.h>

Public Member Functions
	TileCache ()
	~TileCache ()
void	init (uint16_t numTiles)
bool	empty () const
void	setStrategy (uint32_t strategy)
uint32_t	getStrategy () const
void	setMaxActiveTiles (uint16_t maxActive)
	Set the maximum number of tiles that can hold decompressed data simultaneously.
uint16_t	getMaxActiveTiles () const
void	setTruncated (void)
void	setDirty (bool dirty)
void	setDirty (uint16_t tileIndex, bool dirty)
bool	isDirty (uint16_t tileIndex)
TileCacheEntry *	put (uint16_t tile_index, ITileProcessor *processor)
TileCacheEntry *	get (uint16_t tile_index)
void	release (uint16_t tileIndex)
void	releaseForSwath (uint16_t tileIndex)
	Release tile data unconditionally (swath consumer path).
void	resetSOTParsing ()
bool	allSlatedSOTMarkersParsed (const std::set< uint16_t > &tilesSlatedForDecompression)
bool	setProgressionState (grk_progression_state state)
grk_progression_state	getProgressionState (uint16_t tileIndex)

Private Member Functions
void	promoteLRU (uint16_t tileIndex)
	Move a tile to the front of the LRU list (most recently used).
void	evictLRU ()
	Evict least-recently-used tiles when over the active limit.

Private Attributes
std::vector< TileCacheEntry * >	cache_
std::list< uint16_t >	lruList_
uint32_t	strategy_
bool	initialized_
uint16_t	maxActiveTiles_

Detailed Description

Caches tile processors so that repeated decompress calls on the same codec can reuse SOT metadata, packet data, and decompressed images.

See also: doc/TileCache.md for architecture overview and cache strategies.

Tile lifecycle

First encounter (SOT parsed) — getTileProcessor() creates a TileProcessor, and the SOT handler populates its tilePartSeq_ (tile-part offsets/lengths) and increments numSOTsParsed_. At this stage the entry is dirty with no decompressed image.
Packet parsing + decompression — parseTilePart() caches raw packet data, then T2+T1 decompression produces a GrkImage. The entry is marked clean (dirty_ = false).
Cache hit on subsequent decode — decompressTile() finds an entry with getImage() && !dirty_ and returns immediately.
SOT-cached fast path — When a tile's SOTs were parsed on a prior decode but the tile was not slated for decompression, its tilePartSeq_ already contains the byte offsets of every tile part. On a later decode targeting that tile, decompressFromCachedTileParts() seeks directly to each tile part using these cached offsets — no sequential codestream re-walk needed.
LRU eviction — When maxActiveTiles_ is set, exceeding the limit evicts the least-recently-used tile's decompressed data via release(GRK_TILE_CACHE_LRU). The processor (with SOT metadata) survives so the tile can be re-decompressed from the CompressedChunkCache without re-parsing the codestream.
Best-effort decompression — A tile marked isBestEffortDecompressed() was decompressed from a truncated or corrupt codestream. It is never re-decompressed or reset, since re-parsing would produce the same (or worse) result.

resetSOTParsing

Called before a sequential codestream re-walk. Resets numSOTsParsed_, tilePartCounter_, and tilePartSeq_ so that the SOT handler can re-populate them. Tiles that already have a decompressed image or are best-effort are skipped — their cached state is preserved.

Constructor & Destructor Documentation

◆ TileCache()

grk::TileCache::TileCache ( )

inline

References GRK_TILE_CACHE_NONE, initialized_, maxActiveTiles_, and strategy_.

◆ ~TileCache()

grk::TileCache::~TileCache ( )

inline

References cache_.

Member Function Documentation

◆ allSlatedSOTMarkersParsed()

bool grk::TileCache::allSlatedSOTMarkersParsed ( const std::set< uint16_t > & tilesSlatedForDecompression )

inline

◆ empty()

bool grk::TileCache::empty ( ) const

inline

References cache_.

◆ evictLRU()

void grk::TileCache::evictLRU ( )

inlineprivate

Evict least-recently-used tiles when over the active limit.

Eviction releases the tile's decompressed data via GRK_TILE_CACHE_LRU but keeps the processor for potential re-decompression.

References cache_, GRK_TILE_CACHE_LRU, lruList_, and maxActiveTiles_.

Referenced by put().

◆ get()

TileCacheEntry * grk::TileCache::get ( uint16_t tile_index )

inline

References cache_, and promoteLRU().

Referenced by getProgressionState(), grk::TLMMarker::seekNextSlated(), and setProgressionState().

◆ getMaxActiveTiles()

uint16_t grk::TileCache::getMaxActiveTiles ( ) const

inline

References maxActiveTiles_.

◆ getProgressionState()

grk_progression_state grk::TileCache::getProgressionState ( uint16_t tileIndex )

inline

References get().

◆ getStrategy()

uint32_t grk::TileCache::getStrategy ( ) const

inline

References strategy_.

◆ init()

void grk::TileCache::init ( uint16_t numTiles )

inline

References cache_, and initialized_.

◆ isDirty()

bool grk::TileCache::isDirty ( uint16_t tileIndex )

inline

References cache_.

◆ promoteLRU()

void grk::TileCache::promoteLRU ( uint16_t tileIndex )

inlineprivate

Move a tile to the front of the LRU list (most recently used).

References lruList_, and maxActiveTiles_.

Referenced by get(), and put().

◆ put()

TileCacheEntry * grk::TileCache::put	(	uint16_t	tile_index,
		ITileProcessor *	processor )

inline

References cache_, evictLRU(), grk::grklog, and promoteLRU().

◆ release()

void grk::TileCache::release ( uint16_t tileIndex )

inline

References cache_, and strategy_.

◆ releaseForSwath()

void grk::TileCache::releaseForSwath ( uint16_t tileIndex )

inline

Release tile data unconditionally (swath consumer path).

Called by TileCompletion when the swath consumer has moved past a tile row. Frees both image_ and tile_ regardless of cache strategy, since the consumer has explicitly acknowledged it no longer needs the data.

References cache_.

◆ resetSOTParsing()

void grk::TileCache::resetSOTParsing ( )

inline

References cache_.

◆ setDirty() [1/2]

void grk::TileCache::setDirty ( bool dirty )

inline

References cache_.

◆ setDirty() [2/2]

void grk::TileCache::setDirty	(	uint16_t	tileIndex,
		bool	dirty )

inline

References cache_.

◆ setMaxActiveTiles()

void grk::TileCache::setMaxActiveTiles ( uint16_t maxActive )

inline

Set the maximum number of tiles that can hold decompressed data simultaneously.

0 means no limit (all tiles stay active).

References maxActiveTiles_.

◆ setProgressionState()

bool grk::TileCache::setProgressionState ( grk_progression_state state )

inline

References get().

◆ setStrategy()

void grk::TileCache::setStrategy ( uint32_t strategy )

inline

References strategy_.

◆ setTruncated()

void grk::TileCache::setTruncated ( void )

inline

References cache_.

Member Data Documentation

◆ cache_

std::vector<TileCacheEntry*> grk::TileCache::cache_

private

Referenced by empty(), evictLRU(), get(), init(), isDirty(), put(), release(), releaseForSwath(), resetSOTParsing(), setDirty(), setDirty(), setTruncated(), and ~TileCache().

◆ initialized_

bool grk::TileCache::initialized_

private

Referenced by init(), and TileCache().

◆ lruList_

std::list<uint16_t> grk::TileCache::lruList_

private

Referenced by evictLRU(), and promoteLRU().

◆ maxActiveTiles_

uint16_t grk::TileCache::maxActiveTiles_

private

Referenced by evictLRU(), getMaxActiveTiles(), promoteLRU(), setMaxActiveTiles(), and TileCache().

◆ strategy_

uint32_t grk::TileCache::strategy_

private

Referenced by getStrategy(), release(), setStrategy(), and TileCache().

The documentation for this class was generated from the following file:

TileCache.h

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Tile lifecycle

resetSOTParsing

Constructor & Destructor Documentation

◆ TileCache()

◆ ~TileCache()

Member Function Documentation

◆ allSlatedSOTMarkersParsed()

◆ empty()

◆ evictLRU()

◆ get()

◆ getMaxActiveTiles()

◆ getProgressionState()

◆ getStrategy()

◆ init()

◆ isDirty()

◆ promoteLRU()

◆ put()

◆ release()

◆ releaseForSwath()

◆ resetSOTParsing()

◆ setDirty() [1/2]

◆ setDirty() [2/2]

◆ setMaxActiveTiles()

◆ setProgressionState()

◆ setStrategy()

◆ setTruncated()

Member Data Documentation

◆ cache_

◆ initialized_

◆ lruList_

◆ maxActiveTiles_

◆ strategy_