Skip to main content

AFS_AETHER_CACHE_DISK_LOW_FREE_PERCENT

Deep-dive reference for:

  • AFS_AETHER_CACHE_DISK_LOW_FREE_PERCENT

Status​

  • active

Audience​

  • production/user

Type and Default​

  • Type: floating-point percent (f64).
  • Default: 5.0 (% free space).

What It Does​

Defines the disk-free engage threshold (percent) for cache disk-pressure backpressure.

When free disk percent drops to or below this threshold, cache backpressure engages with reason disk_free.

Runtime Behavior​

Disk-pressure block check (percent side):

  • Block when free_percent <= disk_free_block_percent
  • disk_free_block_percent is derived from this variable

Disk-pressure clear check (percent side):

  • Clear only when free_percent > disk_free_clear_percent
  • disk_free_clear_percent comes from AFS_AETHER_CACHE_DISK_HIGH_FREE_PERCENT (or falls back to this value when the high threshold is unset)

Interaction with byte thresholds:

  • Block uses OR logic across configured bytes/percent thresholds.
  • Clear uses AND logic across configured bytes/percent thresholds.
  • If both byte and percent thresholds are configured, both must recover for clear.

Current integration note:

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

Input Surfaces​

  • Env: AFS_AETHER_CACHE_DISK_LOW_FREE_PERCENT=<percent>
  • Config file (aether.toml):
    • [backpressure]
    • cache_disk_low_free_percent = <percent>

No dedicated CLI flag is currently exposed for this variable. No ConfigOverrides field currently exists for this specific threshold.

Resolution and Override Order​

  • Defaults < aether.toml < environment.

Value Rules​

  • Must parse as f64.
  • Mount wiring treats values <= 0 as disabled/unset for this threshold.
  • Negative values parse, but are effectively disabled by mount wiring.

Interactions and Notes​

  • Pair with AFS_AETHER_CACHE_DISK_HIGH_FREE_PERCENT:
    • low = engage threshold
    • high = clear threshold
  • Runtime normalization ensures clear threshold is not below block threshold when both are set.
  • This variable is independent from dirty-byte thresholds:
    • AFS_AETHER_CACHE_DIRTY_HIGH_WATER_BYTES
    • AFS_AETHER_CACHE_DIRTY_LOW_WATER_BYTES

Observability​

  • aether_cache_disk_free_bytes
  • aether_cache_disk_total_bytes
  • aether_cache_disk_free_ratio
  • aether_cache_disk_free_percent
  • Cache inspect/admin output includes:
    • disk_free_bytes
    • disk_total_bytes
    • disk_free_percent
    • cache_block_reason

Example​

export AFS_AETHER_CACHE_DISK_LOW_FREE_PERCENT=5.0
export AFS_AETHER_CACHE_DISK_HIGH_FREE_PERCENT=8.0

This engages disk-pressure backpressure at or below 5% free and clears it once free space rises above 8% (subject to any configured byte thresholds).

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/mount/mount_main.rs
  • packages/aether/src/runtime/infra/backpressure/backpressure_types.rs
  • packages/aether/src/runtime/infra/backpressure/coordinator_impl.rs
  • packages/aether/src/runtime/infra/backpressure/disk_metrics_helpers.rs
  • packages/aether/src/mount/commands/cache.rs