Skip to main content

AFS_AETHER_CACHE_DIRTY_HIGH_WATER_BYTES

Deep-dive reference for:

  • AFS_AETHER_CACHE_DIRTY_HIGH_WATER_BYTES

Status​

  • active

Audience​

  • production/user

Type and Default​

  • Type: integer bytes (u64).
  • Default: 67108864 bytes (64 MiB).

What It Does​

Defines the cache dirty-byte high-water threshold for cache backpressure.

When the current dirty-byte backlog reaches or exceeds this threshold, cache backpressure engages and transport status is marked blocked with source cache.

Dirty bytes here are the aggregate dirty-range byte total tracked in open handle state (unflushed modified data).

Runtime Behavior​

Backpressure trigger condition:

  • dirty_bytes >= high_water_dirty_bytes (and high-water value is > 0)

Backpressure clear condition for dirty-byte reason:

  • dirty_bytes <= low_water_dirty_bytes

AFS_AETHER_CACHE_DIRTY_LOW_WATER_BYTES is the paired hysteresis threshold used to clear.

Current integration note:

  • Cache-backpressure evaluation runs when cache snapshots are pushed into the coordinator.
  • Present call sites are cache control flows (CACHE INSPECT, CACHE CLEAR), so backpressure state updates depend on those snapshot updates.

Input Surfaces​

  • Env: AFS_AETHER_CACHE_DIRTY_HIGH_WATER_BYTES=<bytes>
  • Config file (aether.toml):
    • [backpressure]
    • cache_dirty_high_water_bytes = <bytes>
  • Programmatic override:
    • ConfigOverrides.cache_backpressure_dirty_high_bytes

No dedicated CLI flag is currently exposed for this variable.

Resolution and Override Order​

  • Defaults < aether.toml < environment < overrides.

Value Rules​

  • Must parse as unsigned integer bytes (u64).
  • Unit suffixes are not accepted (64MiB is invalid; use raw bytes).
  • 0 disables dirty-byte-triggered backpressure from this threshold.
    • Disk-free thresholds can still independently trigger cache backpressure.

Interactions and Notes​

  • Pair with AFS_AETHER_CACHE_DIRTY_LOW_WATER_BYTES to avoid flapping.
  • Runtime construction normalizes low-water to at most high-water when high-water is set.
  • This threshold is separate from:
    • AFS_AETHER_CACHE_DIRTY_MAX_BYTES (hard dirty-byte quota cap),
    • AFS_AETHER_CACHE_MAX_BYTES (clean cache cap).

Observability​

  • Dirty backlog gauge: aether_cache_dirty_bytes
  • Control-plane cache inspect output includes:
    • dirty_bytes
    • cache_block_reason (for example dirty_bytes)
    • backpressure status/source

Example​

export AFS_AETHER_CACHE_DIRTY_HIGH_WATER_BYTES=134217728
export AFS_AETHER_CACHE_DIRTY_LOW_WATER_BYTES=100663296

This sets a 128 MiB engage threshold and 96 MiB clear threshold.

Primary Implementation Sources​

  • packages/aether/src/config/types/model_defaults.rs
  • packages/aether/src/config/types/file_config_loader.rs
  • packages/aether/src/config/types/config_resolution.rs
  • packages/aether/src/config/types/apply_env.rs
  • packages/aether/src/runtime/infra/backpressure/backpressure_types.rs
  • packages/aether/src/runtime/infra/backpressure/coordinator_impl.rs
  • packages/aether/src/state/handle/handle_state_types.rs
  • packages/aether/src/mount/commands/cache.rs