By H.Necessaire in core — 03 Jan 2025

Caching with H.Necessaire

Caching is often used in many scenarios for performance improvement and resource de-congestion.

Caching is often used in many scenarios for performance improvement and resource de-congestion. H.Necessaire offers an out-of-the-box, easy to use and easy to extend, caching mechanism with a default in-memory implementation.

Usage

dotnet add package H.Necessaire

ImACacher<SampleData> cacher = depsProvider.GetCacher<SampleData>();

SampleData data = await cacher.GetOrAdd("SomeData", id => new SampleData { Name = "My Sample Data" }.ToCacheableItem(id).AsTask());

In-memory caching in H.Necessaire

ImADependencyProvider depsProvider
    = H.Necessaire.IoC
    .NewDependencyRegistry()
    .Register<HNecessaireDependencyGroup>(() => new HNecessaireDependencyGroup())
    ;

Creating a new IoC-DI container with H.Necessaire Core dependencies

Behind the scenes

The usage, though simple, has a thread-safe implementation under the hood, presented in the following flowchart, useful to understand the extension points, marked with 🧬.

flowchart TD
    depsProvider[depsProvider : **ImADependencyProvider**] --> |GetCacher|CacherManager[CacherManager : **ImACacherFactory**]

    CacherManager --> |BuildCacher|ResolveCacher{Resolve **Cacher**}

    ResolveCacher --> |**default** to|InMemoryCacher[_InMemoryCacher⟨T⟩_ : **ImACacher⟨T⟩**]

    ResolveCacher --> |ID **not** provided|GetImACacher[🧬 **Get** registered **ImACacher⟨T⟩** from _IoC_]

    ResolveCacher --> |ID **provided**|BuildImACacher[🧬 **Build** registered **ImACacher⟨T⟩** with **ID** from _IoC_]

    GetImACacher --> |Resolved Cacher|IsResolvedCacherNull{Is NULL?}

    BuildImACacher --> |Resolved Cacher|IsResolvedCacherNull

    IsResolvedCacherNull --> |Yes|InMemoryCacher

    IsResolvedCacherNull --> |No|ConcreteCacher[_ConcreteCacher⟨T⟩_ : **ImACacher⟨T⟩**]



    InMemoryCacher --> |Add cacher to registry|CacherManagerAsRegistry[CacherManager : **ImACacherRegistry**]
    ConcreteCacher --> |Add cacher to registry|CacherManagerAsRegistry


    CacherManagerAsRegistry --> |Start Housekeeping Periodic Job|Done[✅ Return **ImACacher⟨T⟩**]

Extending

As you can see in the presented flow chart, there are two extension points (🧬) that you can leverage, in order to implement your own custom cacher:

Easiest, register your own, concrete implementation of ImACacher<T> as ImACacher<T>, thus overriding the default InMemoryCacher for the given type.
More customized, register a concrete implementation of ImACacher<T> as its own type, having a custom ID (ID attribute) or Alias (Alias attribute), which can be resolved accordingly via the cacherID parameter.

ImADependencyProvider depsProvider
    = IoC.NewDependencyRegistry()
    .Register<HNecessaireDependencyGroup>(() => new HNecessaireDependencyGroup())
    .Register<ImACacher<SampleData>>(() => new CustomCacher<SampleData>())
    ;

//cacher will be CustomCacher<SampleData>
ImACacher<SampleData> cacher = depsProvider.GetCacher<SampleData>();

Easiest extension via ImACacher<T> registration

ImADependencyProvider depsProvider
    = IoC.NewDependencyRegistry()
    .Register<HNecessaireDependencyGroup>(() => new HNecessaireDependencyGroup())
    .Register<StringCacher>(() => new StringCacher())
    ;

//cacher will be StringCacher
ImACacher<string> stringCacher = depsProvider.GetCacher<string>("string");

Customized extension via MyCustomCacher<T> :ImACacher<T> registration with ID or Alias

Custom cacher sample implementations

Below are two samples of custom cacher implementations. One generic, one non-generic.

Generic implementation

internal class CustomCacher<T> : ImADependency, ImACacher<T>
{
    #region Construct
    ImALogger logger;
    ImACacher<T> baseCacher;
    public void ReferDependencies(ImADependencyProvider dependencyProvider)
    {
        this.logger = dependencyProvider.GetLogger<CustomCacher<T>>();
        this.baseCacher = dependencyProvider.GetCacher<T>(cacherID: "InMemory");
    }
    #endregion

    public async Task<T> AddOrUpdate(string id, Func<string, Task<ImCachebale<T>>> cacheableItemFactory)
    {
        using (new TimeMeasurement(x => Log(nameof(AddOrUpdate), x)))
        {
            return await baseCacher.AddOrUpdate(id, cacheableItemFactory);
        }
    }

    public async Task Clear(params string[] ids)
    {
        using (new TimeMeasurement(x => Log(nameof(Clear), x)))
        {
            await baseCacher.Clear(ids);
        }
    }

    public async Task ClearAll()
    {
        using (new TimeMeasurement(x => Log(nameof(ClearAll), x)))
        {
            await baseCacher.ClearAll();
        }
    }

    public async Task<T> GetOrAdd(string id, Func<string, Task<ImCachebale<T>>> cacheableItemFactory)
    {
        using (new TimeMeasurement(x => Log(nameof(GetOrAdd), x)))
        {
            return await baseCacher.GetOrAdd(id, cacheableItemFactory);
        }
    }

    public async Task RunHousekeepingSession()
    {
        using (new TimeMeasurement(x => Log(nameof(RunHousekeepingSession), x)))
        {
            await baseCacher.RunHousekeepingSession();
        }
    }

    public async Task<OperationResult<T>> TryGet(string id)
    {
        using (new TimeMeasurement(x => Log(nameof(TryGet), x)))
        {
            return await baseCacher.TryGet(id);
        }
    }

    void Log(string actionName, TimeSpan duration)
    {
        logger
            .LogInfo($"{nameof(CustomCacher<T>)} operation [{actionName}] took {duration}")
            .ConfigureAwait(continueOnCapturedContext: false)
            .GetAwaiter()
            .GetResult()
            ;
    }
}

Generic custom cacher implementation

Non-Generic implementation

internal class StringCacher : ImADependency, ImACacher<string>
{
    #region Construct
    ImALogger logger;
    ImACacher<string> baseCacher;
    public void ReferDependencies(ImADependencyProvider dependencyProvider)
    {
        this.logger = dependencyProvider.GetLogger<StringCacher>();
        this.baseCacher = dependencyProvider.GetCacher<string>(cacherID: "InMemory");
    }
    #endregion

    public async Task<string> AddOrUpdate(string id, Func<string, Task<ImCachebale<string>>> cacheableItemFactory)
    {
        using (new TimeMeasurement(x => Log(nameof(AddOrUpdate), x)))
        {
            return await baseCacher.AddOrUpdate(id, cacheableItemFactory);
        }
    }

    public async Task Clear(params string[] ids)
    {
        using (new TimeMeasurement(x => Log(nameof(Clear), x)))
        {
            await baseCacher.Clear(ids);
        }
    }

    public async Task ClearAll()
    {
        using (new TimeMeasurement(x => Log(nameof(ClearAll), x)))
        {
            await baseCacher.ClearAll();
        }
    }

    public async Task<string> GetOrAdd(string id, Func<string, Task<ImCachebale<string>>> cacheableItemFactory)
    {
        using (new TimeMeasurement(x => Log(nameof(GetOrAdd), x)))
        {
            return await baseCacher.GetOrAdd(id, cacheableItemFactory);
        }
    }

    public async Task RunHousekeepingSession()
    {
        using (new TimeMeasurement(x => Log(nameof(RunHousekeepingSession), x)))
        {
            await baseCacher.RunHousekeepingSession();
        }
    }

    public async Task<OperationResult<string>> TryGet(string id)
    {
        using (new TimeMeasurement(x => Log(nameof(TryGet), x)))
        {
            return await baseCacher.TryGet(id);
        }
    }

    void Log(string actionName, TimeSpan duration)
    {
        logger
            .LogInfo($"{nameof(StringCacher)} operation [{actionName}] took {duration}")
            .ConfigureAwait(continueOnCapturedContext: false)
            .GetAwaiter()
            .GetResult()
            ;
    }
}

Non-Generic custom cacher implementation

Runtime Config

CachingHousekeepingIntervalInSeconds optional, defaults to 60 seconds.

Determines how often the internal Cache Manager runs its housekeeping tasks for each cacher.

Can be a floating point value, parsed via double.TryParse, thus parsed using system culture. If the value cannot be parsed, the default 60 seconds will be used.

Caching with H.Necessaire

Usage

Behind the scenes

Extending

Custom cacher sample implementations

Generic implementation

Non-Generic implementation

Runtime Config

Debouncing & Throttling for taming high frequency code execution

Date and Time Derivative Models

Usage

Behind the scenes

Extending

Custom cacher sample implementations

Generic implementation

Non-Generic implementation

Runtime Config

Debouncing & Throttling for taming high frequency code execution

Date and Time Derivative Models

You might also like...