Class BlobCacheConfig

java.lang.Object
io.superdurable.dex.BlobCacheConfig
public final class BlobCacheConfig extends Object
Configures the disk-backed BlobCache.

The byte capacity limits admitted cache contents; it is not a durable-storage quota or a guarantee that every offered blob will be retained.

frequencyCounters controls the requested number of 4-bit access counters in the in-memory TinyLFU sketch that approximately tracks how often blob IDs are accessed. The cache uses these estimates to prefer frequently reused blobs over one-use blobs when admitting or evicting data. It is not the maximum number of cached blobs, an exact access-history length, or part of the disk-capacity calculation.

A larger value uses more process memory but reduces collisions between unrelated blob IDs, making admission and eviction decisions more accurate. A smaller value saves memory, but scan traffic can make cold blobs appear hotter than they are and reduce the expected cache hit ratio. The value does not affect cache correctness, file integrity, or maxBytes enforcement. Access history is not preserved across cache reopenings.

Use approximately ten counters per blob that the cache is expected to hold when full. For example, if maxBytes usually holds about 1,000 blobs, 10,000 counters is a reasonable starting point. The policy uses approximately three bytes of memory per requested counter before internal rounding, so requesting 10,000 counters represents about 30 KB before rounding; actual memory use can be higher. Increase the value for a much larger expected item count or a workload with substantial one-use scan traffic. Decrease it only when policy memory matters more than admission accuracy. Passing zero uses the default of 10,000. 

BlobCacheConfig config = new BlobCacheConfig(
        "./dex-cache",
        256L * 1024 * 1024,
        10_000L);

  • Constructor Details

    • BlobCacheConfig

      public BlobCacheConfig(String directory, long maxBytes)
      Creates a configuration with 10,000 frequency counters.
      Parameters:
      directory - the nonempty directory used for cache files
      maxBytes - the positive maximum admitted payload size in bytes
      Throws:
      IllegalArgumentException - if the directory is empty or the capacity is not positive

    • BlobCacheConfig

      public BlobCacheConfig(String directory, long maxBytes, long frequencyCounters)
      Creates a configuration with an explicit admission-sketch size.
      Parameters:
      directory - the nonempty directory used for cache files
      maxBytes - the positive maximum admitted payload size in bytes
      frequencyCounters - the nonnegative TinyLFU sketch size described above; zero uses the default of 10,000
      Throws:
      IllegalArgumentException - if the directory is empty, the capacity is not positive, or frequencyCounters is negative