ossfs 2.0 caches metadata in client memory to reduce queries per second (QPS) against OSS and speed up file access. Two independent cache types serve different purposes: the file attribute cache stores positive lookup results (the file exists), and the negative cache stores negative lookup results (the file does not exist). Each cache has its own configuration parameters, use cases, and consistency implications.
How it works
Every stat call on an ossfs 2.0 mount translates into one or more OSS requests. As path depth increases, the number of requests grows exponentially. Both cache types reduce this load by serving repeated queries from memory:
File attribute cache — On the first access to a path, ossfs 2.0 fetches the file's metadata (size, modification time, file type) from OSS and stores it in memory. For the file type attribute, only regular files and folders are supported. For the duration of
attr_timeout, subsequentstatcalls on that path read from the cache instead of hitting OSS.Negative cache — When a
statcall returns a 404 Not Found response, ossfs 2.0 stores that result in memory. For the duration ofoss_negative_cache_timeout, repeated lookups for that path return "not found" immediately, without contacting OSS.
File attribute cache
When to use it
The file attribute cache is suited for read-heavy workloads where changes are controlled. Enable it in the following situations:
Read-only bucket — No writes or modifications occur, so the cache and OSS data stay consistent.
Single-writer bucket — A single ossfs 2.0 process writes to the bucket, making the source of metadata changes unique and preventing cache inconsistencies.
If multiple users write to the same bucket at the same time, enable the file attribute cache only when each user's operation path is completely isolated, with no overlapping or conflicting paths (for example, by using separate directory trees per user or task).
Configuration
| Parameter | Default | Description |
|---|---|---|
attr_timeout | 60 s | Cache TTL in seconds. After expiration, ossfs 2.0 sends a new request to OSS to fetch the latest metadata. 60 s balances performance and consistency: lower values increase OSS request frequency, while higher values extend the window during which stale metadata may be served. |
max_inode_cache_count | 0 | Maximum number of cached entries. At 0 (default), the OS manages eviction automatically. Set to a positive integer to enable active eviction: when the entry count exceeds the limit, ossfs 2.0 evicts excess entries based on specific rules. |
readdirplus | true | When true (default), ossfs 2.0 preloads file metadata (size, modification time) for all items in a folder during readdir. This uses more memory but significantly reduces latency for subsequent access. When false, readdir returns filenames only, deferring metadata fetches to individual stat calls, which increases QPS. The default value suits most workloads; set to false only when memory is constrained and per-file latency is acceptable. |
close_to_open | false | Controls whether ossfs 2.0 enforces close-to-open consistency on file open. When false (default), opening a file uses cached metadata until attr_timeout expires. When true, opening a file always sends a fresh OSS request for the latest metadata, at the cost of higher latency — particularly in workloads with many small file reads. |
Consistency
Close-to-open consistency is a POSIX file system guarantee: once a writer closes a file, all subsequent readers see the latest state. By default, close_to_open is false, meaning ossfs 2.0 does not enforce this guarantee — opening a file may return cached metadata.
With attr_timeout at the default of 60 s, a file change in OSS may take up to 60 seconds to appear when accessed through ossfs 2.0. If files in OSS change frequently and you need up-to-date metadata on every open, set close_to_open to true. This bypasses the local metadata cache on each file open and restores the close-to-open guarantee, but increases access latency.
Negative cache
When to use it
Enable the negative cache in the following situations:
Read-only bucket — No files are created during operation, so a "not found" result remains accurate for the duration of the cache.
Exploratory access before batch file creation — A program uses
statto probe multiple paths (for example, scanning for configuration files, resources, or plugins), and many of those paths may not exist. Caching 404 responses avoids repeated OSS requests for paths already confirmed as absent.
Configuration
| Parameter | Default | Description |
|---|---|---|
oss_negative_cache_timeout | 0 (disabled) | Cache TTL in seconds. At 0, negative caching is disabled. Set to a positive integer to enable it: ossfs 2.0 caches 404 responses and returns "not found" immediately for the specified duration without querying OSS. |
oss_negative_cache_size | 10,000 | Maximum number of cached entries. When the limit is exceeded, ossfs 2.0 evicts excess entries based on priority. |
Consistency
After enabling the negative cache, a path cached as "not found" remains inaccessible for the full duration of oss_negative_cache_timeout, even if the file is created on OSS during that period. Access is restored only after the cache entry expires and ossfs 2.0 re-fetches the result from OSS.
Do not enable the negative cache in workloads that require high data consistency or where files may be created and immediately accessed.