Module chunk_cache 

Chunk caching.

zarrs supports three types of chunk caches:

• ChunkCacheTypeDecoded: caches decoded chunks.
  • Preferred where decoding is expensive and memory is abundant.
• ChunkCacheTypeEncoded: caches encoded chunks.
  • Preferred where decoding is cheap and memory is scarce, provided that data is well compressed/sparse.
• ChunkCacheTypePartialDecoder: caches partial decoders.
  • Preferred where chunks are repeatedly partially retrieved.
  • Useful for retrieval of subchunks from sharded arrays, as the partial decoder caches shard indexes (but not subchunks).
  • Memory usage of this cache is highly dependent on the array codecs and whether the codec chain (Array::codecs) ends up decoding entire chunks or caching inputs based on their PartialDecoderCapability.

zarrs implements the following Least Recently Used (LRU) chunk caches:

• ChunkCacheDecodedLruChunkLimit: a decoded chunk cache with a fixed chunk capacity..
• ChunkCacheDecodedLruSizeLimit: a decoded chunk cache with a fixed size in bytes.
• ChunkCacheEncodedLruChunkLimit: an encoded chunk cache with a fixed chunk capacity.
• ChunkCacheEncodedLruSizeLimit: an encoded chunk cache with a fixed size in bytes.
• ChunkCachePartialDecoderLruChunkLimit: a partial decoder chunk cache with a fixed chunk capacity
• ChunkCachePartialDecoderLruSizeLimit: a partial decoder chunk cache with a fixed size in bytes.

There are also ThreadLocal suffixed variants of all of these caches that have a per-thread cache. zarrs consumers can create custom caches by implementing the ChunkCache trait.

Chunk caches implement the ChunkCache trait which has cached versions of the equivalent Array methods:

• retrieve_chunk
• retrieve_chunks
• retrieve_chunk_subset
• retrieve_array_subset

_elements and _ndarray variants are also available.

Chunk caching is likely to be effective for remote stores where redundant retrievals are costly. Chunk caching may not outperform disk caching with a filesystem store. The above caches use internal locking to support multithreading, which has a performance overhead. Prefer not to use a chunk cache if chunks are not accessed repeatedly. Aside from ChunkCacheTypePartialDecoder-based caches, caches do not use partial decoders and any intersected chunk is fully retrieved if not present in the cache.

For many access patterns, chunk caching may reduce performance. Benchmark your algorithm/data.

Structs

ChunkCacheLruChunkLimit

A chunk cache with a fixed chunk capacity.

ChunkCacheLruChunkLimitThreadLocal

A thread local chunk cache with a fixed chunk capacity per thread.

ChunkCacheLruSizeLimit

A chunk cache with a fixed size capacity.

ChunkCacheLruSizeLimitThreadLocal

A thread local chunk cache with a fixed size capacity per thread.

Traits

ChunkCache

Traits for a chunk cache.

ChunkCacheType

A chunk cache type (ChunkCacheTypeEncoded, ChunkCacheTypeDecoded, or ChunkCacheTypePartialDecoder).

Type Aliases

ChunkCacheDecodedLruChunkLimit

An LRU (least recently used) decoded chunk cache with a fixed chunk capacity.

ChunkCacheDecodedLruChunkLimitThreadLocal

An LRU (least recently used) decoded chunk cache with a fixed chunk capacity.

ChunkCacheDecodedLruSizeLimit

An LRU (least recently used) decoded chunk cache with a fixed size capacity .

ChunkCacheDecodedLruSizeLimitThreadLocal

An LRU (least recently used) decoded chunk cache with a fixed size capacity.

ChunkCacheEncodedLruChunkLimit

An LRU (least recently used) encoded chunk cache with a fixed chunk capacity.

ChunkCacheEncodedLruChunkLimitThreadLocal

An LRU (least recently used) encoded chunk cache with a fixed chunk capacity.

ChunkCacheEncodedLruSizeLimit

An LRU (least recently used) encoded chunk cache with a fixed size capacity.

ChunkCacheEncodedLruSizeLimitThreadLocal

An LRU (least recently used) encoded chunk cache with a fixed size capacity.

ChunkCachePartialDecoderLruChunkLimit

An LRU (least recently used) partial decoder chunk cache with a fixed chunk capacity.

ChunkCachePartialDecoderLruChunkLimitThreadLocal

An LRU (least recently used) partial decoder chunk cache with a fixed chunk capacity.

ChunkCachePartialDecoderLruSizeLimit

An LRU (least recently used) partial decoder chunk cache with a fixed size capacity.

ChunkCachePartialDecoderLruSizeLimitThreadLocal

An LRU (least recently used) partial decoder chunk cache with a fixed chunk capacity.

ChunkCacheTypeDecoded

The chunk type of a decoded chunk cache.

ChunkCacheTypeEncoded

The chunk type of an encoded chunk cache.

ChunkCacheTypePartialDecoder

The chunk type of a partial decoder chunk cache.