Account for the memory around your records

Build a budget by owner

Account for retained records, indexes, and buffers, plus temporary allocations and overlapping work. There is no single setting here that caps the tree's total bytes.

With InMemoryFileStreamProvider, add all retained file bytes to the process budget. Merging records into a RAM-backed “disk” segment changes representation; it does not move their storage outside process memory.

Size the active write set

MutableSegmentMaxItemCount defaults to 1_000_000. This limits records in the active mutable segment, not bytes in the whole tree. A million small structs and a million document objects have very different costs.

Moving a full mutable segment forward freezes it into the read-only layer. That memory remains reachable until merging and reader lifetimes permit its release. Lowering the mutable limit rotates segments sooner; it cannot compensate for a merge backlog that grows faster than storage can drain it.

Use ReadOnlySegmentsCount, ReadOnlySegmentsRecordCount, and InMemoryRecordCount to track that backlog. These count physical records, potentially including older versions and deletion markers; they are not byte measurements or live-key counts.

Include Bloom-filter rounding

When enabled, the Bloom filter requests capacity × MutableSegmentBloomFilterBitsPerItem, rounds up to a power of two, and bounds the bit array between 64 and 2^30 bits. The default is 8 requested bits per item; setting the option to 0 disables the filter.

For the default one-million-record capacity:

requested bits = 1,000,000 × 8 = 8,000,000
allocated bits = 8,388,608
bit storage    = 1,048,576 bytes = 1 MiB, plus object/array overhead

Newly frozen mutable segments retain their filters alongside their records. Include those allocations for every simultaneously retained generation. See Bloom filters for filtering behavior and recovery differences.

Disk-cache allocation scopes

These defaults are capacities or retention controls, not a shared byte allowance:

A multipart logical segment contains multiple physical parts, each with its own applicable caches. Counting only logical segment objects underestimates the allocation scopes.

Materialized-entry caching retains deserialized objects in addition to block bytes. The slot count bounds the chunks held by that cache, but it is not a byte bound: key/value types, referenced objects, filled chunks, and replacement allocations determine the cost. Setting MaterializedEntryCacheSize to 0 disables that cache; setting SearchHintPrefetchSize to 0 disables search-hint prefetch.

For a first block-byte estimate, 100 fully populated 4 MiB cached blocks account for about 400 MiB before materialized objects, indexes, other caches, and temporary buffers. Use this to check the scale of a measurement, not as a total-memory prediction.

Read compression for block-size tradeoffs and read-path caching for individual cache controls.

Give iterators a short lifetime

IteratorOptions.DiskSegmentPrefetchSize controls the prefetch capacity of low-level disk iterators. A top-level scan can merge several segment iterators, so multiply buffers by segment fan-in as well as by concurrent scans.

Iterators also lease the segments they read. A long-lived scan can keep retired segments, associated objects, and old files alive after a merge. Dispose an iterator when its scan finishes; do not keep one idle as an application-wide cursor. See iteration and range scans.

Configure retention and observe the write set

This program reduces mutable and materialized-cache capacities, configures cleanup, and prints record counts. The values illustrate the controls; measure their effect on your workload.

using ZoneTree;

using var tree = new ZoneTreeFactory<int, string>()
    .SetDataDirectory("data/memory-budget")
    .SetMutableSegmentMaxItemCount(100_000)
    .ConfigureDiskSegmentOptions(options =>
    {
        options.MaterializedEntryCacheSize = 1024;
        options.SearchHintPrefetchSize = 8;
    })
    .OpenOrCreate();
using var maintainer = tree.CreateMaintainer();

// Restart the cleanup job so its timer uses the new interval.
maintainer.EnableJobForCleaningInactiveCaches = false;
maintainer.BlockCacheLifeTime = TimeSpan.FromSeconds(30);
maintainer.InactiveBlockCacheCleanupInterval = TimeSpan.FromSeconds(10);
maintainer.EnableJobForCleaningInactiveCaches = true;

for (var key = 0; key < 1000; ++key)
    tree.Upsert(key, $"Record {key}");

Console.WriteLine($"Mutable: {tree.Maintenance.MutableSegmentRecordCount}");
Console.WriteLine($"Frozen: {tree.Maintenance.ReadOnlySegmentsRecordCount}");
Console.WriteLine($"In memory: {tree.Maintenance.InMemoryRecordCount}");

The standard maintainer starts cleanup automatically with a one-minute block lifetime and a 30-second interval. It reads BlockCacheLifeTime on each pass, but captures InactiveBlockCacheCleanupInterval when creating its timer. Changing the interval requires the stop/configure/start sequence above.

Measure steady state and peaks separately

Run a representative write/read mix, warm its caches, and observe both sustained operation and merge peaks. Then stop work, dispose scans, allow maintenance and cleanup to finish, and compare retained objects.

Use managed heap and allocation profiles alongside process counters. Working set, peak working set, and GC.GetTotalMemory() answer different questions; none is a precise ZoneTree ownership report by itself.