Resource Caching System
Relevant source files
The following files were used as context for generating this wiki page:
The Resource Caching System in Kaleidux is a multi-tiered architecture designed to minimize CPU overhead, reduce disk I/O, and ensure smooth transitions between wallpapers. It manages various types of data, ranging from persistent filesystem metadata stored in a local database to transient GPU resources like textures and render pipelines.
The system's primary goal is to support high-performance rendering by caching file discovery results, user-specific selection statistics (the "Loveit" system), and compiled GLSL shaders. By leveraging persistent storage via redb and in-memory LRU (Least Recently Used) caches for GPU objects, the daemon maintains a "near-zero CPU overhead" aesthetic during active use.
Sources: README.md, kaleidux-daemon/src/cache.rs:1-25, kaleidux-daemon/src/renderer.rs:55-70
Persistent Metadata and File Cache
Kaleidux utilizes an embedded key-value store, redb, to persist wallpaper metadata, playlists, and playback history. This ensures that subsequent starts of the daemon do not require a full recursive scan of wallpaper directories.
Database Schema
The persistent cache is organized into several distinct tables within cache.redb, located in the user's cache directory (typically ~/.cache/kaleidux/).
| Table Name | Key Type | Value Type | Description |
|---|---|---|---|
file_cache | &[u8] (Path) | FileMetadata | Stores mtime, size, and content type (Image/Video). |
file_stats | &[u8] (Path) | FileStats | Tracks play counts and "Love" multipliers. |
playlists | &str (Name) | Playlist | Stores user-defined wallpaper collections. |
blacklist | &[u8] (Path) | bool | Files excluded from discovery. |
history | &str (Output) | Vec<PathBuf> | Recent wallpapers per monitor output. |
Sources: kaleidux-daemon/src/cache.rs:10-45, kaleidux-daemon/src/queue.rs:25-45
Directory Watching and Invalidation
To maintain cache integrity, the system employs a DirectoryWatcher based on the notify crate. It monitors watched directories for filesystem events (Create, Modify, Remove) and invalidates specific entries in the file_cache table to force a re-scan of changed files.
The process_events function asynchronously processes these notifications, ensuring the cache stays synchronized with the physical filesystem without blocking the main rendering loop.
Sources: kaleidux-daemon/src/cache.rs:242-285, kaleidux-daemon/src/main.rs:256-270
GPU Resource Caching (WGPU)
High-performance rendering is achieved through the reuse of expensive GPU objects. The WgpuContext acts as the central coordinator for these pooled resources.
Texture Pooling
Instead of allocating and deallocating GPU memory for every video frame or image switch, the system maintains a texture_pool. Textures are keyed by their dimensions (width, height).
- Acquisition: The renderer requests a texture from the pool via
get_texture_from_pool. - Recycling: When a transition completes or a frame is no longer needed, the texture is returned to the pool using
return_texture_to_pool. - Cleanup: A periodic cleanup task runs every 3 seconds to evict textures older than 10 seconds or when the pool exceeds its global limit of 50 textures.
Sources: kaleidux-daemon/src/renderer.rs:166-225, kaleidux-daemon/src/main.rs:770-776
Pipeline LRU Cache
Shader compilation is a heavy operation. The system uses a PipelineLRU structure to cache wgpu::RenderPipeline objects. This cache stores up to 50 compiled transition shaders.
Smart Queue and Statistics
The SmartQueue leverages the cache to implement weighted random selection based on user preference and recency.
The "Loveit" System
Selection weights are calculated using data stored in the file_stats table. The scoring formula balances three factors:
- Love Multiplier: Explicitly set by the user (e.g.,
kldctl love). - Selection Count: Inversely weighted to prevent overplaying the same file.
- Recency: Favors files that haven't been seen recently.
Sources: kaleidux-daemon/src/queue.rs:340-370, kldctl/src/main.rs:105-115
Batch Updates
To prevent excessive disk writes, statistics updates are buffered in a pending_stats_updates HashMap. These are flushed to the redb database in batches every 5 seconds.
Sources: kaleidux-daemon/src/queue.rs:380-405, kaleidux-daemon/src/main.rs:778-782
Performance Metrics and Monitoring
The PerformanceMetrics module tracks the efficiency of the caching system. It records hit/miss rates for the texture pool and the metadata cache, which are then logged periodically for diagnostic purposes.
Resource Leak Detection
The metrics system monitors the growth of cached resources to detect potential leaks:
- Texture Count: Warns if textures grow by >50 over 60 seconds.
- Pipeline Count: Warns if unique pipelines grow by >20 over 60 seconds.
- Channel Backpressure: Monitors
frame_channel_sizeandimage_channel_sizeto ensure consumers are keeping up with producers.
Sources: kaleidux-daemon/src/metrics.rs:270-330, kaleidux-daemon/src/main.rs:788-805
Conclusion
The Resource Caching System provides a robust foundation for the Kaleidux wallpaper daemon. By combining persistent metadata storage with sophisticated GPU resource pooling and LRU caching, it ensures that high-fidelity transitions and video playback remain performant and resource-efficient over long-running sessions. The system's self-monitoring capabilities further safeguard against resource exhaustion, maintaining the project's goal of "Aesthetic Excellence" without sacrificing system stability.
Sources: CONTRIBUTING.md, kaleidux-daemon/src/main.rs:820-830