Flotsam: disk, memory and negative caches
Practical guide based on OpenSimulator 0.9.3.1 source: identify, configure and diagnose 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
- Understanding OpenSimulator caches
- Cache console commands: fcache
- Other internal caches: inventory, regions and textures
- Troubleshoot caches without disrupting a grid
- FSAssets and asset storage
- Inodes and disk storage
- Firestorm cache and graphics lag