OpenSimulator · EN

Flotsam: disk, memory and negative caches

Practical guide based on OpenSimulator 0.9.3.1 source: identify, configure and diagnose caches.

Check the active module and loaded settings before commands. Caches may be cleared, but permanent stores like FSAssets must never be deleted as if they were caches.

Enabling the module

In the GridCommon.ini and StandaloneCommon.ini templates, [Modules] AssetCaching = FlotsamAssetCache loads the module, and Include-FlotsamCache points at config-include/FlotsamCache.ini. Cache settings belong to [AssetCache]. Make sure the include points to a real file.

Disk cache

FileCacheEnabled = true enables file caching. CacheDirectory sets its path, default ./assetcache in the template. The module resolves this to an absolute path at startup. Entries are copies: a miss normally falls back to the asset source. This store is different from FSAssets.

Memory cache

MemoryCacheEnabled defaults to false in the template. If enabled, MemoryCacheTimeout controls expiration in hours; .016 is roughly one minute. It can speed repeated requests at RAM cost. The code also keeps weak references, which are not identical to the optional memory cache.

Negative caching of missing assets

NegativeCacheEnabled = true and NegativeCacheTimeout = 120 temporarily remember missing assets so repeated failures do not hammer the asset service. Newly created or restored assets might remain invisible until expiration. fcache clearnegatives is more targeted than clearing everything.

Expiration and automated cleanup

FileCacheTimeout is in hours (48 in the template). FileCleanupTimer controls scheduled cleanup; its example value 0.0 disables periodic passes. FileCacheTimeout = 48 therefore does not by itself mean disk files are automatically deleted after 48 hours when the timer is off.

Directory layout and inodes

CacheDirectoryTiers and CacheDirectoryTierLength distribute files into subdirectories. CacheWarnAt is a warning threshold for files per directory. Layout changes require planning and testing; they do not magically solve filesystem inode exhaustion.

UpdateFileTimeOnCacheHit

UpdateFileTimeOnCacheHit defaults to false. The example warns to enable it only with a shared cache and controlled external cleanup. Updating file timestamps changes cache aging and can affect expiration strategies.

Monitoring and disk writes

fcache status reports entries and hit rates for cache layers, and can scan directories to count files. Enumeration and preloading on a huge cache cost I/O; avoid running them in a tight loop.

Example values from the source template. The include and AssetCache section may be in different files; do not duplicate [Modules] if already defined.

[Modules]
AssetCaching = "FlotsamAssetCache"
Include-FlotsamCache = "config-include/FlotsamCache.ini"

[AssetCache]
CacheDirectory = ./assetcache
FileCacheEnabled = true
MemoryCacheEnabled = false
NegativeCacheEnabled = true
NegativeCacheTimeout = 120
MemoryCacheTimeout = .016
FileCacheTimeout = 48
FileCleanupTimer = 0.0
UpdateFileTimeOnCacheHit = false

Managing this cache: practical steps

Recommended management procedure

1. Verify Flotsam and the effective FlotsamCache.ini include. 2. Run fcache status in the affected simulator console. 3. Check CacheDirectory, inodes and FileCleanupTimer. 4. For a recently restored but missing asset, try only fcache clearnegatives. 5. Reserve fcache clear file or fcache clear for justified maintenance and monitor subsequent reloads.

What not to do

Do not create cron jobs that blindly remove a guessed cache path. A cache shared by several simulators needs coordinated cleanup; disk cache is not interchangeable with FSAssets. fcache status may count very many files and cause I/O on large caches.

More cache guides

Verified sources: OpenSimulator 0.9.3.1