Skip to main content

AFS_AETHER_CACHE_DISK_LOW_FREE_BYTES

Deep-dive reference for:

  • AFS_AETHER_CACHE_DISK_LOW_FREE_BYTES

Status​

  • active

Audience​

  • production/user

Type and Default​

  • Type: integer bytes (u64).
  • Default: 536870912 bytes (512 MiB).

What It Does​

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

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

Runtime Behavior​

Disk-pressure block check (bytes side):

  • Block when free_bytes <= disk_free_block_bytes
  • disk_free_block_bytes is derived from this variable

Disk-pressure clear check (bytes side):

  • Clear only when free_bytes > disk_free_clear_bytes
  • disk_free_clear_bytes comes from AFS_AETHER_CACHE_DISK_HIGH_FREE_BYTES (or falls back to this value when the high threshold is unset)

Interaction with percent 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_BYTES=<bytes>
  • Config file (aether.toml):
    • [backpressure]
    • cache_disk_low_free_bytes = <bytes>

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 unsigned integer bytes (u64).
  • Unit suffixes are not accepted (512MiB is invalid; use raw bytes).
  • 0 disables this block threshold input (mount wiring maps 0 to “unset”).

Interactions and Notes​

  • Pair with AFS_AETHER_CACHE_DISK_HIGH_FREE_BYTES:
    • 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_BYTES=536870912
export AFS_AETHER_CACHE_DISK_HIGH_FREE_BYTES=805306368

This engages disk-pressure backpressure at or below 512 MiB free and clears it once free space rises above 768 MiB (subject to any configured percent 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