Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.archil.com/llms.txt

Use this file to discover all available pages before exploring further.

Archil caches your data at two distinct layers:
  • The Archil storage system cache is a durable, multi-Availability-Zone caching layer that runs server-side, between your clients and your data source. It’s where your active data is durably stored (a successful fsync() commits to it) and where it’s metered, and it serves data with sub-millisecond latency. See Architecture for how it fits in.
  • The client-side cache is an in-memory cache inside each Archil client — one per mount. It holds recently used data so that repeated access is served locally, without even a round-trip to the storage system.
This page is about the client-side cache: what it holds, how it’s sized and evicted, and the commands you use to warm, refresh, and tune it.

​
What the client caches

The client maintains several in-memory caches, all populated on demand as your application reads and writes:
  • File data — the contents of files. This is the bulk of the cache.
  • File and directory attributes — metadata such as size, timestamps, and permissions (the result of a stat).
  • Directory listings — the entries returned by readdir (i.e., ls), so repeated traversals of the same directory don’t round-trip to the server.
  • Extended attributes — when xattrs are enabled.
When your application requests data that isn’t in the client cache, the client fetches it from the Archil storage system — which serves it from its durable cache (sub-millisecond) or, on a miss there, from the backing data source (for Amazon S3, typically 10–30 ms) — and then caches the result in memory for future requests.

​
Cache size and eviction

The client’s in-memory data cache is bounded by two settings on archil mount:
  • --max-cache-mb — the hard ceiling on the client cache size. Default: 1/4 of available RAM or 2048 MiB, whichever is smaller.
  • --target-cache-mb — the size the client aims to keep the cache near, leaving headroom for bursts of new reads. Default: 75% of the maximum.
When the cache fills, the client evicts older entries to make room for new data. Two kinds of entries are never evicted:
  • Unflushed (dirty) writes — data you’ve written that hasn’t yet been committed to the storage system is always preserved locally, so eviction can never lose your writes.
  • Entries still in use — anything an application currently has open is kept until it’s released.
Because the client cache is bounded, reading or pre-fetching more data than --max-cache-mb can hold will evict earlier entries before you use them. Size the cache for your working set when you plan to keep a large data set hot on a client.
For example, to give a read-heavy client a larger cache: 
archil mount <disk-name> /mnt/archil --region aws-us-east-1 \
    --max-cache-mb 16384 --target-cache-mb 12288

​
Freshness and consistency

Serving reads from the client cache is what lets a client avoid contacting the storage system on every operation — which also means a client can briefly serve slightly stale data after another client changes a file. The client revalidates cached entries with the storage system so that changes become visible within seconds for file data and attributes. Directory listings are cached for longer; you can tune their lifetime per directory with archil set-cache-expiry. For the full model — including how fsync and cache flushes provide strong read-after-write consistency between connected clients — see Consistency.

​
Warming the client cache

By default the client cache fills lazily as data is read, so the first read of any file on a client pays the fetch latency. When you know which files you’ll need — loading a model, starting a database, or running a batch job over a known set of inputs — you can warm them ahead of time so the first read is already local. There are two ways to warm the client cache:
  • archil prefetch <MOUNTPOINT> <PATH>... — pre-fetch files or directories (recursively) into the cache of an already-mounted disk. The command queues the work and returns immediately; fetching continues in the background.
  • archil mount --pre-fetch <PATHS> — warm a comma-separated set of paths automatically as soon as the disk is mounted.
# Warm a model directory on an already-mounted disk
archil prefetch /mnt/archil models/llama-3

# Or warm it as part of the mount
archil mount <disk-name> /mnt/archil --region aws-us-east-1 --pre-fetch models/llama-3
Pre-fetched data shares the client cache with normal reads, so it counts against --max-cache-mb and is subject to the same eviction described above.

​
Refreshing the client cache

To force a client to drop cached entries and re-read from the storage system — for example, when another client has updated files on a --shared mount — use archil invalidate-cache. Pass the mount root to refresh everything, or a single file path to refresh just that file. In-flight (dirty) writes are always preserved. 
# Refresh the whole mount
archil invalidate-cache /mnt/archil

# Refresh a single file (siblings keep their cache)
archil invalidate-cache /mnt/archil/shared-data/report.csv

​
Controls at a glance

GoalControl
Set the maximum client cache sizemount --max-cache-mb
Set the target client cache sizemount --target-cache-mb
Warm files into the client cache after mountprefetch
Warm files into the client cache at mount timemount --pre-fetch
Drop and re-read cached datainvalidate-cache
Tune directory-listing cache lifetimeset-cache-expiry