mirror of
https://github.com/jamenai/opensim-addon-modules-exp.git
synced 2026-07-28 05:12:50 +00:00
116 lines
4.2 KiB
Markdown
116 lines
4.2 KiB
Markdown
# 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:
|
||
```ini
|
||
; 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
|