DOCSEARCHbyAlgolia
Submit Docs

FusionCache Documentation

repository·main·Indexed 26 days ago

https://github.com/ziggycreatures/fusioncache

A high-performance, resilient hybrid caching library for .NET supporting multi-level (L1/L2) caching. It features cache stampede protection, fail-safe mechanisms, auto-recovery, and backplane synchronization for multi-node environments. FusionCache targets .NET Standard 2.0 and provides native support for OpenTelemetry, Dependency Injection, and Microsoft's HybridCache abstraction.

Tokens
36.7K
Snippets
70
Records
184
Agent score
84%

What's inside FusionCache

  1. Overview of FusionCache

    main

    FusionCache is a high-performance, robust hybrid cache for .NET. It supports both single-level memory caching (L1) and multi-level caching (L1+L2). The second level (L2) can be any implementation of the standard IDistributedCache interface, providing better cold starts, horizontal scalability, and resiliency.

    Key capabilities include:

    • Resiliency: Cache stampede protection, fail-safe mechanisms, and auto-recovery.
    • Performance: L1+L2 multi-level caching, backplane for multi-node synchronization, soft/hard timeouts, and eager refresh.
    • Flexibility: Named caches, tagging, support for null caching, and native Dependency Injection support.
    • Observability: Full support for OpenTelemetry, structured logging via ILogger, and comprehensive events.
    • Compatibility: Works with Microsoft's HybridCache and targets .NET Standard 2.0.

  2. Overview of FusionCache features

    main

    FusionCache is a high-performance, resilient hybrid cache for .NET. It provides advanced features grouped into four main categories:

    Resiliency

    • Cache Stampede Protection: Automatic protection against stampedes at both local (single node) and distributed (multi-node) levels.
    • Fail-Safe: Reuses expired entries as temporary fallbacks to avoid transient failures.
    • Auto-Recovery: Automatic self-healing for the entire cache.

    Performance & Scalability

    • L1+L2 Caching: Transparently uses any IDistributedCache implementation as a second level of caching.
    • Backplane: Synchronizes cache changes across multiple nodes.
    • Soft/Hard Timeouts: Prevents slow factories or distributed caches from blocking your application.
    • Eager Refresh: Performs non-blocking background refreshes before expiration.
    • Conditional Refresh: Supports refresh logic similar to HTTP Conditional Requests.
    • Background Distributed Operations: Executes distributed operations in the background for improved performance.

    Flexibility

    • Named Caches: Manage multiple independently configured caches.
    • Tagging: Associate tags with entries to expire groups of entries simultaneously.
    • Clear: Wipe entire caches, including shared L2 or specific key prefixes.
    • Microsoft HybridCache Support: Acts as an implementation for Microsoft's HybridCache abstraction.
    • Adaptive Caching: Dynamically determine entry options (like Duration) based on the cached value.
    • Dependency Injection & Builder: Native DI support with a fluent builder interface.
    • Auto-Clone: Ensures cached values can be safely modified by callers.
    • Sync/Async Support: Full support for both synchronous and asynchronous programming models.
    • Plugins: Extend functionality with metrics, statistics, and more.

    Observability

    • OpenTelemetry: Native support for distributed tracing and metrics.
    • Logging: Structured, customizable logging via ILogger.
    • Events: High-level and low-level (memory/distributed) event hooks.

  6. Understand FusionCache Core Concepts

    main

    FusionCache is a hybrid cache that operates at two levels:

    • L1 (Memory Cache): A fast, in-memory cache for high-locality, frequently accessed data. It can use any IMemoryCache implementation.
    • L2 (Distributed Cache): An optional second level using any IDistributedCache implementation. It helps ease cold starts and shares data across multiple nodes/pods.

    Key Resiliency Features:

    • Backplane: A shared message bus to synchronize L1 caches across multiple nodes.
    • Fail-Safe: Allows using expired cache entries if the factory (data source) fails.
    • Cache Stampede Prevention: Ensures only one factory execution per key occurs concurrently.
    • Soft/Hard Timeouts: Allows reusing expired entries if the factory takes too long.
    • Auto-Recovery: Automatically handles transient errors in distributed components.
    • Tagging: Allows evicting multiple entries at once using RemoveByTag.

  7. Use Redis for distributed locking in FusionCache

    main
    The ZiggyCreatures.FusionCache.Locking.Distributed.Redis package provides a distributed locker implementation for Redis. It is built upon the DistributedLock library and allows FusionCache to coordinate locks across multiple instances using a Redis backend, which is essential for preventing cache stampedes in distributed environments.

  9. Understand the FusionCache GetOrSet flow with L1 only

    main
    When using only the L1 (in-memory) cache, the GetOrSet method follows a simple path: it checks if the value exists in L1. If it does, it returns the value immediately. If not, it executes the provided factory, saves the result to L1, and returns it. Note that cache stampede protection is always active internally, even if not explicitly shown in simplified diagrams.

  10. Use Neuecc MessagePack for FusionCache serialization

    main
    This package provides a specialized serializer implementation for FusionCache. It is designed to be used with the optional distributed cache level of FusionCache, leveraging the performance of Neuecc's MessagePack to handle data serialization/deserialization when moving items between the local memory cache and a distributed cache provider.

  11. Understand FusionCache Auto-Recovery

    main

    FusionCache includes an Auto-Recovery feature designed to handle transient errors in distributed components (the distributed cache and the backplane) automatically.

    When a transient error occurs during operations like Set, Remove, or GetOrSet, FusionCache detects the failure and places the operation into an internal auto-recovery queue. This queue is processed periodically to ensure that the global state (distributed cache and all local memory caches) remains synchronized without requiring manual intervention or developer code to handle retries.

    Key benefits:

    • Automatic Retries: Automatically retries failed distributed cache writes or backplane notifications.
    • Implementation Agnostic: Works with any distributed cache or backplane implementation used with FusionCache.
    • Resiliency: Ensures that even if a node loses connectivity briefly, it will eventually sync its state once connectivity is restored.