opensim-addon-modules-exp/modules/OpenSimConcurrentFlotsamAssetCache/README.MD

ConcurrentFlotsamAssetCache (NON-CORE DEVELOPMENT)

A high-throughput, concurrent asset cache module for OpenSimulator. It augments the classic FlotsamAssetCache with parallel I/O, multi-layer caching, and in-flight de-duplication for upstream fetches to reduce latency spikes and thundering herds.

• Project type: OpenSim region module
• Purpose: Faster asset retrieval with better concurrency and robust on-disk safety
• Status: DEV/TESTING (alpha)

Key Features

• Multi-layer caching:
  • WeakReference cache for ultra-fast hits without pinning memory
  • Optional memory cache for hot assets
  • File cache with tiered directory layout
• Robust file persistence:
  • Atomic replace/move operations
  • Optional .bak backup support and cleanup
  • Throttled LastAccessTime updates to reduce syscalls
• Concurrency controls:
  • Per-file write gating to avoid partial/corrupted files
  • Optional multi-worker writer for higher throughput
  • In-flight de-duplication (single-flight) for upstream requests
• Negative cache:
  • Bounded miss cache with TTL and pruning to prevent stampedes
• Safety and maintenance:
  • Periodic cleanup with scene-aware protection
  • Versioned binary serialization with size caps (OOM/corruption guard)
  • Console commands for status, cleanup, and cache control

When to use

• You have highly parallel workloads and want to smooth load spikes
• You run on fast storage (NVMe/SSD) and can benefit from parallel I/O
• You need to reduce redundant upstream fetches under pressure

If you prefer simplicity and minimal resources, the core FlotsamAssetCache (Core) may be a better fit.

Installation

1. Build the module along with your OpenSim environment.
2. Place the compiled assembly in your RegionModules path.
3. Enable the module in your configuration:

   ; bin/OpenSim.ini
   [Modules]
   AssetCaching = ConcurrentFlotsamAssetCache
   
   
   ; bin/config-include/ConcurrentFlotsamAssetCache.ini
   ; EXAMPLE CONFIGURATION
   [AssetCache]
   FileCacheEnabled = true
   MemoryCacheEnabled = true
   CacheDirectory = c_assetcache
   FileCacheTimeout = 48
   UpdateFileTimeOnCacheHit = true
   NegativeCacheEnabled = true
   NegativeCacheTimeout = 120
   ; Optional tuning:
   ; FileWriterConcurrencyWorker = 1
   ; FileReplaceKeepBackup = false
   ; FileMoveAllowOverwrite = true
   ; DeserializeMaxStringLenBytes = 262144
   ; DeserializeMaxDataLenMB = 64
   

4. Restart your simulator.

See MIGRATION.md for platform preconditions and configuration guidance.

Configuration Overview

• AssetCache section highlights:

  • FileCacheEnabled: enable file persistence
  • MemoryCacheEnabled: enable memory layer
  • CacheDirectory: base folder for cache tiers
  • FileCacheTimeout (hours): file expiration
  • UpdateFileTimeOnCacheHit: throttle-touched on hits
  • NegativeCacheEnabled / NegativeCacheTimeout (seconds)
  • FileWriterConcurrencyWorker: writer threads (default 1; increase cautiously)
  • FileReplaceKeepBackup (.bak) / FileMoveAllowOverwrite
  • DeserializeMaxStringLenBytes / DeserializeMaxDataLenMB: safety caps

• Advanced:

  • CacheDirectoryTiers (1–3), CacheDirectoryTierLength (1–4)
  • BackoffAttempts, BackoffInitialMs, BackoffMaxMs for contention
  • BakCleanupEnabled and BakCleanupMaxAgeHours

Console Commands

• cfcache status
• cfcache clear [file] [memory]
• cfcache clearnegatives
• cfcache assets
• cfcache expire <datetime(mm/dd/YYYY)>
• cfcache cachedefaultassets
• cfcache deletedefaultassets
• cfcache cleanbak

Performance Tips

• Start conservative: keep FileWriterConcurrencyWorker at 1; scale only after storage validation.
• Keep NegativeCache enabled with moderate timeouts to prevent upstream stampedes.
• Use default serialization caps unless your assets regularly exceed them.
• Monitor hit-rate output and logs to tune backoff and cache sizes.

Safety Notes

• Ensure the cache directory is on reliable storage that supports atomic renames/replaces.
• Verify permissions for read/write/create/delete on the cache path.
• If your filesystem ignores LastAccessTime, rely on periodic cleanup and deep scans.

Documentation

• COMPARISON.md: Side-by-side comparison to core FlotsamAssetCache
• MIGRATION.md: Preconditions, migration guidance, and operational considerations