Skip to main content

AFS_AETHER_CACHE_DIRTY_LOW_WATER_BYTES

Deep-dive reference for:

  • AFS_AETHER_CACHE_DIRTY_LOW_WATER_BYTES

Status​

  • active

Audience​

  • production/user

Type and Default​

  • Type: integer bytes (u64).
  • Default: 50331648 bytes (48 MiB).

What It Does​

Defines the cache dirty-byte low-water threshold used to clear cache backpressure when the active cache block reason is dirty_bytes.

This value does not engage backpressure by itself. Engagement is controlled by AFS_AETHER_CACHE_DIRTY_HIGH_WATER_BYTES.

Runtime Behavior​

Dirty-byte backpressure engages when:

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

Dirty-byte backpressure clears when:

  • dirty_bytes <= low_water_dirty_bytes

The clear check is applied for the DirtyBytes reason path. If another reason (for example disk free space) is active, that reason’s clear logic applies.

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_LOW_WATER_BYTES=<bytes>
  • Config file (aether.toml):
    • [backpressure]
    • cache_dirty_low_water_bytes = <bytes>
  • Programmatic override:
    • ConfigOverrides.cache_backpressure_dirty_low_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 (48MiB is invalid; use raw bytes).
  • 0 is allowed.
    • With low-water 0, dirty-byte backpressure clears as soon as dirty bytes drop below the high-water re-trigger condition.

Interactions and Notes​

  • Pair with AFS_AETHER_CACHE_DIRTY_HIGH_WATER_BYTES for hysteresis.
  • At runtime, low-water is normalized to at most high-water when high-water is configured.
    • If low-water is set above high-water, it is clamped down to high-water.
    • This removes most hysteresis and can increase block/clear churn around the high threshold.
  • Separate from hard caps:
    • AFS_AETHER_CACHE_DIRTY_MAX_BYTES (hard dirty quota),
    • AFS_AETHER_CACHE_MAX_BYTES (clean cache quota).

Observability​

  • Dirty backlog gauge: aether_cache_dirty_bytes
  • Cache inspect/admin reports include:
    • dirty_bytes
    • cache_block_reason
    • 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 clears dirty-byte backpressure once dirty bytes fall to 96 MiB or lower.

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/mount/commands/cache.rs