Skip to main content

AFS_AETHER_CACHE_DISK_HIGH_FREE_BYTES

Deep-dive reference for:

  • AFS_AETHER_CACHE_DISK_HIGH_FREE_BYTES

Status​

  • active

Audience​

  • production/user

Type and Default​

  • Type: integer bytes (u64).
  • Default: 805306368 bytes (768 MiB).

What It Does​

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

When cache backpressure is active for disk-free reasons, it will clear only after free disk bytes rise above this threshold (and any configured percent threshold also clears).

Runtime Behavior​

Disk-pressure block check (bytes side):

  • Block when free_bytes <= disk_free_block_bytes (AFS_AETHER_CACHE_DISK_LOW_FREE_BYTES)

Disk-pressure clear check (bytes side):

  • Clear only when free_bytes > disk_free_clear_bytes
  • disk_free_clear_bytes is derived from this variable

Interaction with percent thresholds:

  • Block uses OR logic across 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.
  • 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_DISK_HIGH_FREE_BYTES=<bytes>
  • Config file (aether.toml):
    • [backpressure]
    • cache_disk_high_free_bytes = <bytes>
  • Programmatic override:
    • ConfigOverrides.cache_backpressure_disk_high_free_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 (768MiB is invalid; use raw bytes).
  • 0 disables this clear threshold input (mount wiring maps 0 to “unset”).

Interactions and Notes​

  • Pair with AFS_AETHER_CACHE_DISK_LOW_FREE_BYTES:
    • low = engage threshold
    • high = clear threshold
  • Runtime normalization ensures clear threshold is not below block threshold when both are set.
  • If high is unset, clear-bytes falls back to block-bytes.
  • 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