admin/opensim-addon-modules-exp
1
0
Fork 0
mirror of https://github.com/jamenai/opensim-addon-modules-exp.git synced 2026-08-14 08:53:10 +00:00
Code Issues Packages Projects Releases Wiki Activity

added MIGRATION.MD and updated README.MD and COMPARISON.MD

Browse Source
This commit is contained in:
Lordfox
2025-10-04 19:59:52 +02:00
parent e6f470df72
commit 1b063c297b
3 changed files with 273 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files
modules/OpenSimConcurrentFlotsamAssetCache/COMPARISON.MD
+30 -28
View File
@@ -4,40 +4,42 @@
| Aspect | ConcurrentFlotsamAssetCache | FlotsamAssetCache (Core) |
|---|---|---|
| Parallelism | High parallelism for reads/writes with contention backoff; lock-free maps where possible | Lower parallelism; centralized locks and single-writer patterns |
| Latency under load | Lower at peaks; background writer and non-blocking reads reduce head-of-line blocking | Higher at peaks due to serialization and lock contention |
| Thundering herd handling | In-flight write detection for same file; optional exponential backoff on readers | Simpler; may trigger redundant fetches and waits |
| Consistency/ordering | Careful ordering for touch/replace; atomic replace/move on disk to avoid partials | More deterministic single-path writes; simpler ordering |
| Debugging/maintenance | More complex (multiple caches: weak/memory/file, negative cache, timers) | Simpler (single-path logic) |
| Resource usage | Higher (job engine, timers, concurrent structures) | Lower (fewer moving parts) |
| Memory footprint | Slightly higher (WeakReference map + optional memory cache) | Lower |
| Concurrency risk | More tuning required (starvation/livelock mitigated by backoff caps) | Lower risk by design |
| I/O behavior | Parallel I/O; atomic replace (with optional .bak) and overwrite moves | Serialized I/O; predictable but lower throughput |
| Expire/cleanup | Periodic timer with scene-aware protection and optional .bak cleanup; LastAccessTime updates throttled | Simpler periodic cleanup; fewer edge cases |
| Negative cache | Bounded negative cache with pruning (expiry + oldest sampling) | Typically unbounded/simple or absent |
| Serialization format | Versioned binary format with size caps to guard corruption/OOM | Simpler/legacy formats |
| Fit – large load/cluster | Very good (scales, smooths spikes) | Limited |
| Parallelism | High parallelism for reads/writes; per-file write gate; optional multi-writer background engine; in-flight upstream de-duplication | Lower parallelism; centralized locks and single-writer patterns |
| Latency under load | Lower at peaks; non-blocking fast paths (weak/memory/file); short wait on in-flight writes | Higher at peaks due to serialization and lock contention |
| Thundering herd handling | In-flight de-duplication for upstream fetches; negative cache with pruning and TTL; small delay if write in progress | Simpler; may trigger redundant fetches and waits |
| Consistency/ordering | Atomic file replace/move; throttled LastAccessTime updates; scene-aware cleanup; guarded write finalization | Deterministic single-path writes; simpler ordering guarantees |
| Debugging/maintenance | More moving parts (weak/memory/file cache, negative cache, background writers, timers, in-flight map) | Simpler (single-path logic) |
| Resource usage | Higher (job engine, concurrent maps, timers; optional parallel file writes) | Lower (fewer components) |
| Memory footprint | Slightly higher (WeakReference map + optional memory cache + transient in-flight map) | Lower |
| Concurrency risk | Requires tuning (backoff, writer concurrency); mitigations in place (per-file gate, de-dup, capped negatives) | Lower risk by design |
| I/O behavior | Parallel I/O; atomic replace with optional .bak; overwrite moves where available; tiered directories | Serialized I/O; predictable, lower throughput |
| Expire/cleanup | Periodic cleanup; scene-aware keep-list; optional .bak cleanup; size-capped negative cache pruning | Simpler periodic cleanup; fewer edge cases |
| Negative cache | Bounded with expiry and sampling-based pruning to avoid unbounded growth | Typically simple/unbounded or absent |
| Serialization format | Versioned binary format with size caps to prevent corruption/OOM | Simpler/legacy formats |
| Upstream fetch | Integrated upstream fetch with single-flight (in-flight de-dup); fallback to negatives on miss | Usually direct or not integrated with cache layer |
| Fit – large load/cluster | Very good (scales, smooths spikes, reduces redundant upstream) | Limited |
| Fit – small setups | Possibly overkill | Very good (simple, frugal) |
| Overall | Optimized for throughput and concurrency with higher complexity | Optimized for simplicity and predictability |
| Overall | Optimized for throughput, concurrency, and reduced duplication at the cost of complexity | Optimized for simplicity and predictability |
## Vergleich zu FlotsamAssetCache (DEU)
| Aspekt | ConcurrentFlotsamAssetCache | FlotsamAssetCache (Core) |
|---|---|---|
| Parallelität | Hohe Parallelität bei Reads/Writes; Backoff bei Contention; lock-arme Strukturen | Geringere Parallelität; zentrale Locks/Single-Writer |
| Latenz unter Last | Niedriger bei Peaks; Writer-Worker und non-blocking Reads | Höher bei Peaks durch Serialisierung und Locks |
| Thundering-Herd | Erkennung paralleler Writes je Datei; optionaler Exponential-Backoff für Leser | Einfacher; kann zu redundanten Fetches führen |
| Konsistenz/Ordnung | Sorgfältige Ordnung von Touch/Replace; atomare Replace/Move-Strategien | Deterministischer; einfacher zu überblicken |
| Fehlersuche/Wartung | Komplexer (Weak/Mem/File-Cache, Negative-Cache, Timer) | Einfacher (ein Pfad) |
| Ressourcenverbrauch | Höher (Job-Engine, Timer, Concurrent-Maps) | Geringer |
| Speicherbedarf | Etwas höher (WeakReference-Map + optionaler Memory-Cache) | Niedriger |
| Risiko Concurrency-Bugs | Höher, aber durch begrenzten Backoff/Überwachung mitigiert | Geringer |
| I/O-Verhalten | Paralleler I/O; atomare Replace-Option (.bak optional) und Overwrite-Move | Serieller I/O; planbarer, begrenzter Durchsatz |
| Expire/Cleanup | Periodischer Timer; szenenbewusste Schonung; optionale .bak-Bereinigung; gedrosselte LastAccessTime-Updates | Einfachere Periodik; weniger Randfälle |
| Negative-Cache | Begrenzter Miss-Cache mit Pruning (Ablauf + Sampling der Ältesten) | Einfach/unbegrenzt oder nicht vorhanden |
| Parallelität | Hohe Parallelität; per-Datei-Schreibsperre; optional mehrere Writer; De-Dup bei Upstream-Anfragen | Geringere Parallelität; zentrale Locks/Single-Writer |
| Latenz unter Last | Niedriger bei Peaks; schnelle Pfade (Weak/Mem/File) ohne Blockieren; kurzer Wait bei laufendem Write | Höher bei Peaks durch Serialisierung und Locks |
| Thundering-Herd | Single-Flight für Upstream; Negative-Cache mit TTL/Pruning; kleine Verzögerung bei in-flight Writes | Einfacher; kann redundante Fetches verursachen |
| Konsistenz/Ordnung | Atomare Replace/Move-Strategien; gedrosselte LastAccessTime; szenenbewusste Bereinigung; abgesicherte Finalisierung | Deterministischer; einfacher zu überblicken |
| Fehlersuche/Wartung | Komplexer (mehr Caches, Writer, Timer, In-Flight-Map) | Einfacher (ein Pfad) |
| Ressourcenverbrauch | Höher (Job-Engine, Concurrent-Maps, Timer; optional parallele Datei-Writes) | Geringer |
| Speicherbedarf | Etwas höher (WeakReference-Map, optionaler Memory-Cache, temporäre In-Flight-Einträge) | Niedriger |
| Risiko Concurrency-Bugs | Erhöht, aber durch Backoff, per-Datei-Gate, De-Dup und begrenzten Negative-Cache mitigiert | Geringer |
| I/O-Verhalten | Paralleler I/O; atomare Replace-Option (.bak optional) und Overwrite-Move; stufige Verzeichnisse | Serieller I/O; planbarer, begrenzter Durchsatz |
| Expire/Cleanup | Periodisch; szenenbewusstes Schonverhalten; optionale .bak-Bereinigung; negatives Pruning mit Größenlimit | Einfachere Periodik; weniger Randfälle |
| Negative-Cache | Begrenzter Miss-Cache mit Ablauf/Pruning (Sampling der Ältesten) | Einfach/unbegrenzt oder nicht vorhanden |
| Serialisierungsformat | Versioniertes Binärformat mit Größenlimits (Schutz vor Korruption/OOM) | Einfacher/älter |
| Eignung – hohe Last/Cluster | Sehr gut (Skalierung, Peak-Glättung) | Eingeschränkt |
| Upstream-Fetch | Integrierter Upstream mit Single-Flight-De-Dup; Negative bei Miss | Meist direkt oder nicht im Cache integriert |
| Eignung – hohe Last/Cluster | Sehr gut (Skalierung, Spike-Glättung, weniger Doppel-Fetches) | Eingeschränkt |
| Eignung – kleine Setups | Mitunter Overkill | Sehr gut (einfach, sparsam) |
| Gesamtfazit | Auf Durchsatz und Parallelität optimiert bei höherer Komplexität | Auf Einfachheit und Vorhersagbarkeit optimiert |
| Gesamtfazit | Auf Durchsatz, Parallelität und Vermeidung doppelter Upstream-Last optimiert, mit höherer Komplexität | Auf Einfachheit und Vorhersagbarkeit optimiert |
Hinweis: Wähle Concurrent für stark parallelisierte Workloads und schnelle Datenträger; nutze Core, wenn Einfachheit, geringer Ressourcenbedarf und Wartbarkeit im Vordergrund stehen.
Hinweis: Nutze die Concurrent-Variante für stark parallelisierte Workloads, schnelle Datenträger und reduzierten Upstream-Druck; wähle Core, wenn Einfachheit, geringer Ressourcenbedarf und Wartbarkeit wichtiger sind.
modules/OpenSimConcurrentFlotsamAssetCache/MIGRATION.MD
+129
View File
@@ -0,0 +1,129 @@
# MIGRATION
This document highlights conditions and considerations when migrating to ConcurrentFlotsamAssetCache. It focuses on cache behavior, configuration, and operational impacts.
## English
## 1. Preconditions and Compatibility
- Runtime: Requires a modern .NET/Mono environment matching your OpenSim build. Ensure File.Replace and optional overwrite move behavior are supported on your platform.
- Storage: Ensure the cache directory is on a filesystem that supports reliable atomic renames/replaces. On networked storage, semantics may differ.
- Permissions: The process must have read/write/create/delete permissions for the cache directory (including subfolders and temporary files).
- Time attributes: LastAccessTime updates are used (throttled). If your filesystem mounts with noatime or ignores access time updates, cleanup behavior will rely more on periodic scans.
## 2. Cache Directory Layout
- Tiered structure: Files are distributed into tiered subdirectories based on ID prefixes. Ensure:
- CacheDirectoryTiers ≥ 1 and ≤ 3.
- CacheDirectoryTierLength between 1 and 4.
- Moving from Core: If you have an existing core cache, you can:
- Keep the directory but allow the new module to repopulate progressively, or
- Start with a clean directory to avoid mixing formats.
- Backups: If enabling atomic replace backups (.bak), allow extra disk space and optionally schedule cleanup.
## 3. File Format and Serialization
- Versioned binary format with size caps for strings and data to guard against corruption and out-of-memory.
- Existing files in unknown/old formats will be skipped and may be deleted upon read failure to allow fresh caching.
- Ensure Deserialize caps (max string length, max data size) fit your asset profile. Too small values may reject valid assets; too large may increase memory pressure.
## 4. Memory and Weak Reference Cache
- WeakReference layer avoids strong memory retention of assets but speeds repeated hits.
- Optional memory cache increases RAM usage but reduces I/O latency. Size is indirectly controlled by expiration.
- Garbage Collection: Weak references can expire at any time; logic assumes this and falls back gracefully.
## 5. Negative (Miss) Cache
- Enabled by default to reduce upstream/load on repeated misses.
- Bounded with pruning. Tune NegativeCacheMaxEntries and NegativeCacheTimeout for your workload.
- If you expect assets to appear shortly after a miss, consider shorter timeouts to reduce false negatives.
## 6. In-flight De-duplication (Upstream Single-Flight)
- Concurrent requests for the same missing asset will share one upstream fetch.
- If upstream is unstable/slow, consider monitoring and shorter negative TTL on failures to avoid request stampedes.
- Ensure upstream IAssetService is not self-referential to avoid loops.
## 7. Write Behavior and Disk Load
- Per-file write gate prevents concurrent writes to the same asset file.
- Optional multi-worker writer can increase throughput but may spike IOPS. Validate your storage performance before increasing concurrency.
- Atomic replace/move minimizes partial files. On platforms not supporting overwrite move, a delete+move fallback is used.
## 8. Cleanup and Expiration
- Periodic cleaner removes files based on LastAccessTime and optionally cleans stale .bak files.
- Scene-aware protection prevents deletion of assets referenced by active scenes or defined as default assets.
- If your environment disables access times, ensure FileCacheTimeout is appropriate and consider manual “touch” commands.
## 9. Configuration Migration Tips
- Start conservatively:
- Keep FileWriterConcurrencyWorker at 1 initially.
- Use default deserialize caps unless you know your asset size profile.
- Enable NegativeCache with moderate limits.
- Observe logs and hit-rate reports; adjust:
- Backoff attempts/delays if you see contention on writes.
- Negative cache size/timeouts if you see persistent misses or late arrivals.
- Commands are available to inspect status, clear caches, and trigger cleanup.
## 10. Operational Safety
- Always test on a staging region with a copy of your cache directory.
- Ensure reliable backups when enabling FileReplaceKeepBackup; monitor .bak cleanup schedules.
- Monitor “in-flight joins” (if exposed) to detect stampedes and upstream pressure.
---
## Deutsch
## 1. Voraussetzungen und Kompatibilität
- Laufzeit: Moderne .NET/Mono-Umgebung entsprechend dem OpenSim-Build. Prüfen, ob File.Replace und optionales Overwrite-Move auf Ihrer Plattform unterstützt werden.
- Storage: Der Cache-Ordner sollte auf einem Dateisystem liegen, das atomare Umbenennungen/Ersetzungen zuverlässig unterstützt. Auf Netzwerkshares können sich Semantiken unterscheiden.
- Berechtigungen: Lese/Schreib/Erstell-/Löschrechte für Cache-Verzeichnis inkl. Unterordnern und temporären Dateien sind erforderlich.
- Zeitstempel: LastAccessTime-Updates werden (gedrosselt) genutzt. Bei noatime/ignorierten Access-Times stützt sich die Bereinigung stärker auf periodische Scans.
## 2. Cache-Verzeichnisstruktur
- Gestufte Struktur: Dateien werden anhand von ID-Präfixen in Unterordner verteilt. Sicherstellen:
- CacheDirectoryTiers ≥ 1 und ≤ 3.
- CacheDirectoryTierLength zwischen 1 und 4.
- Migration vom Core:
- Entweder vorhandenes Verzeichnis beibehalten und neu befüllen lassen oder
- Mit leerem Verzeichnis starten, um Formatmischungen zu vermeiden.
- Backups: Bei aktivierten .bak-Backups atomarer Replaces genügend Speicherplatz einplanen und Cleanup einrichten.
## 3. Dateiformat und Serialisierung
- Versioniertes Binärformat mit Größenlimits für Strings und Daten (Schutz vor Korruption/OOM).
- Unbekannte/alte Dateien werden ggf. übersprungen und bei Lesefehler gelöscht, damit sie neu gecacht werden können.
- Deserialize-Limits (max. Stringlänge, max. Datengröße) an das Asset-Profil anpassen. Zu klein -> valide Assets abgelehnt; zu groß -> mehr Speicherlast.
## 4. Memory- und Weak-Reference-Cache
- WeakReference-Schicht verhindert harte Speicherbindung und beschleunigt wiederholte Zugriffe.
- Optionaler Memory-Cache erhöht RAM-Bedarf, reduziert aber I/O-Latenz. Größe indirekt über Ablaufzeit gesteuert.
- GC: Weak-Referenzen können jederzeit verfallen; Logik fällt sauber auf andere Ebenen zurück.
## 5. Negative-(Miss)-Cache
- Standardmäßig aktiv zur Entlastung des Upstreams bei wiederholten Misses.
- Begrenzt und mit Pruning. NegativeCacheMaxEntries und NegativeCacheTimeout passend zum Workload wählen.
- Erwarten Sie kurzzeitige Verfügbarkeit nach einem Miss, wählen Sie kürzere Timeouts, um falsche Negative zu reduzieren.
## 6. In-Flight-De-Dup (Upstream-Single-Flight)
- Gleichzeitige Anfragen für dasselbe fehlende Asset teilen sich einen Upstream-Fetch.
- Bei instabilem/slow Upstream Monitoring einplanen und ggf. kürzere Negative-TTL bei Fehlern, um Stampedes zu vermeiden.
- Sicherstellen, dass der Upstream-IAssetService nicht auf sich selbst verweist (Loop vermeiden).
## 7. Schreibverhalten und Plattenlast
- Pro-Datei-Schreibsperre verhindert parallele Writes derselben Datei.
- Optional mehrere Writer möglich, erhöht Durchsatz, kann aber IOPS-Spitzen verursachen. Speichertauglichkeit vorab prüfen.
- Atomare Replace/Moves minimieren Teil-Dateien. Falls Overwrite-Move nicht unterstützt, wird Delete+Move als Fallback genutzt.
## 8. Bereinigung und Ablauf
- Periodische Bereinigung entfernt Dateien anhand LastAccessTime und optional alte .bak-Dateien.
- Szenenbewusster Schutz verhindert Löschen aktiv referenzierter oder als Default definierter Assets.
- Wenn Access-Times deaktiviert sind, FileCacheTimeout passend wählen und ggf. manuelles „Touch“ nutzen.
## 9. Konfigurations-Migrationstipps
- Konservativ starten:
- FileWriterConcurrencyWorker anfangs auf 1 belassen.
- Standard-Deserialize-Limits verwenden, sofern das Asset-Größenprofil unbekannt ist.
- Negative-Cache aktiviert mit moderaten Grenzen.
- Logs und Hit-Rate-Reports beobachten; anpassen:
- Backoff/Delays bei Write-Contention.
- Negative-Cache-Größe/Timeouts bei häufigen Misses oder verspäteten Assets.
- Befehle stehen zur Statusprüfung, Cache-Leerung und Bereinigung bereit.
## 10. Betriebssicherheit
- Migration zunächst auf Staging-Region mit Kopie des Cache-Verzeichnisses testen.
- Bei aktivierten FileReplaceKeepBackup verlässliche Backups und .bak-Cleanup überwachen.
- „In-flight joins“ (falls verfügbar) beobachten, um Stampedes und Upstream-Druck zu erkennen.****
modules/OpenSimConcurrentFlotsamAssetCache/README.MD
+114 -1
View File
@@ -1,2 +1,115 @@
# OpenSimConcurrentFlotsamAssetCache
# 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