Class IndividualLifetimeCache<TKey, TValue>

Namespace

LfrlAnvil.Chrono.Caching

Assembly

LfrlAnvil.Chrono.dll

Represents a generic cache of keyed entries with a limited lifetime, where each entry can have its own individual lifetime.

public sealed class IndividualLifetimeCache<TKey, TValue> : IIndividualLifetimeCache<TKey, TValue>, ILifetimeCache<TKey, TValue>, IReadOnlyLifetimeCache<TKey, TValue>, ICache<TKey, TValue>, IReadOnlyCache<TKey, TValue>, IReadOnlyDictionary<TKey, TValue>, IReadOnlyCollection<KeyValuePair<TKey, TValue>>, IEnumerable<KeyValuePair<TKey, TValue>>, IEnumerable where TKey : notnull

Type Parameters

TKey

Entry key (identifier) type.

TValue

Entry value type.

Inheritance

object

IndividualLifetimeCache<TKey, TValue>

Implements

IIndividualLifetimeCache<TKey, TValue>

ILifetimeCache<TKey, TValue>

IReadOnlyLifetimeCache<TKey, TValue>

ICache<TKey, TValue>

IReadOnlyCache<TKey, TValue>

IReadOnlyDictionary<TKey, TValue>

IReadOnlyCollection<KeyValuePair<TKey, TValue>>

IEnumerable<KeyValuePair<TKey, TValue>>

IEnumerable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

LifetimeCacheExtensions.MoveTo<TKey, TValue>(ILifetimeCache<TKey, TValue>, Timestamp)

Remarks

Reading entries resets their lifetime.

Constructors

IndividualLifetimeCache(Timestamp, Duration, int, Action<CachedItemRemovalEvent<TKey, TValue>>?)

Creates a new IndividualLifetimeCache<TKey, TValue> instance that uses the Default key comparer.

public IndividualLifetimeCache(Timestamp startTimestamp, Duration lifetime, int capacity = 2147483647, Action<CachedItemRemovalEvent<TKey, TValue>>? removeCallback = null)

Parameters

startTimestamp Timestamp

Timestamp of the creation of this cache.

lifetime Duration

Lifetime of added entries.

capacity int

An optional maximum capacity. Equal to MaxValue by default.

removeCallback Action<CachedItemRemovalEvent<TKey, TValue>>

An optional callback which gets invoked every time an entry is removed from this cache.

Exceptions

ArgumentOutOfRangeException

When capacity is less than 1 or when lifetime is less than 1 tick.

IndividualLifetimeCache(IEqualityComparer<TKey>, Timestamp, Duration, int, Action<CachedItemRemovalEvent<TKey, TValue>>?)

Creates a new IndividualLifetimeCache<TKey, TValue> instance.

public IndividualLifetimeCache(IEqualityComparer<TKey> keyComparer, Timestamp startTimestamp, Duration lifetime, int capacity = 2147483647, Action<CachedItemRemovalEvent<TKey, TValue>>? removeCallback = null)

Parameters

keyComparer IEqualityComparer<TKey>

Custom key equality comparer.

startTimestamp Timestamp

Timestamp of the creation of this cache.

lifetime Duration

Lifetime of added entries.

capacity int

An optional maximum capacity. Equal to MaxValue by default.

removeCallback Action<CachedItemRemovalEvent<TKey, TValue>>

An optional callback which gets invoked every time an entry is removed from this cache.

Exceptions

ArgumentOutOfRangeException

When capacity is less than 1 or when lifetime is less than 1 tick.

Properties

Capacity

Maximum capacity of this cache. Adding entries to caches whose capacity have been reached will cause their Oldest entry to be removed.

public int Capacity { get; }

Property Value

int

Comparer

IEqualityComparer<T> instance used for key equality comparison.

public IEqualityComparer<TKey> Comparer { get; }

Property Value

IEqualityComparer<TKey>

Count

Gets the number of elements in the collection.

public int Count { get; }

Property Value

int

The number of elements in the collection.

CurrentTimestamp

Timestamp at which this cache currently is.

public Timestamp CurrentTimestamp { get; }

Property Value

Timestamp

this[TKey]

Gets or sets the entry that has the specified key.

public TValue this[TKey key] { get; set; }

Parameters

key TKey

The key of the entry to get or set.

Property Value

TValue

Remarks

See AddOrUpdate(TKey, TValue) for more information about the setter's behavior.

Exceptions

KeyNotFoundException

Entry with the provided key does not exist.

Keys

Gets an enumerable collection that contains the keys in the read-only dictionary.

public IEnumerable<TKey> Keys { get; }

Property Value

IEnumerable<TKey>

An enumerable collection that contains the keys in the read-only dictionary.

Lifetime

Lifetime of added entries.

public Duration Lifetime { get; }

Property Value

Duration

Oldest

Currently oldest cache entry.

public KeyValuePair<TKey, TValue>? Oldest { get; }

Property Value

KeyValuePair<TKey, TValue>?

Remarks

This entry will be removed when new entry addition causes Count to exceed Capacity.

RemoveCallback

An optional callback which gets invoked every time an entry is removed from this cache.

public Action<CachedItemRemovalEvent<TKey, TValue>>? RemoveCallback { get; }

Property Value

Action<CachedItemRemovalEvent<TKey, TValue>>

StartTimestamp

Timestamp of the creation of this cache.

public Timestamp StartTimestamp { get; }

Property Value

Timestamp

Values

Gets an enumerable collection that contains the values in the read-only dictionary.

public IEnumerable<TValue> Values { get; }

Property Value

IEnumerable<TValue>

An enumerable collection that contains the values in the read-only dictionary.

Methods

AddOrUpdate(TKey, TValue)

Adds a new entry or updates an existing one if key already exists.

public AddOrUpdateResult AddOrUpdate(TKey key, TValue value)

Parameters

key TKey

Entry's key.

value TValue

Entry's value.

Returns

AddOrUpdateResult

Added when new entry has been added (provided key did not exist), otherwise Updated.

Remarks

When new entry addition causes Count to exceed Capacity, then the Oldest entry will be removed automatically.

AddOrUpdate(TKey, TValue, Duration)

Adds a new entry or updates an existing one if key already exists.

public AddOrUpdateResult AddOrUpdate(TKey key, TValue value, Duration lifetime)

Parameters

key TKey

Entry's key.

value TValue

Entry's value.

lifetime Duration

Entry's lifetime.

Returns

AddOrUpdateResult

Added when new entry has been added (provided key did not exist), otherwise Updated.

Remarks

When new entry addition causes Count to exceed Capacity, then the Oldest entry will be removed automatically.

Clear()

Removes all entries from the collection.

public void Clear()

ContainsKey(TKey)

Determines whether the read-only dictionary contains an element that has the specified key.

[Pure]
public bool ContainsKey(TKey key)

Parameters

key TKey

The key to locate.

Returns

bool

true if the read-only dictionary contains an element that has the specified key; otherwise, false.

Exceptions

ArgumentNullException

key is null.

GetEnumerator()

Returns an enumerator that iterates through the collection.

[Pure]
public IEnumerator<KeyValuePair<TKey, TValue>> GetEnumerator()

Returns

IEnumerator<KeyValuePair<TKey, TValue>>

An enumerator that can be used to iterate through the collection.

GetRemainingLifetime(TKey)

Gets the remaining lifetime of an entry with the specified key.

[Pure]
public Duration GetRemainingLifetime(TKey key)

Parameters

key TKey

Key to check.

Returns

Duration

Entry's lifetime or Zero when key does not exist.

Move(Duration)

Moves this cache forward in time and removes entries with elapsed lifetimes.

public void Move(Duration delta)

Parameters

delta Duration

Duration to add to the CurrentTimestamp.

Remove(TKey)

Attempts to remove an entry with the specified key.

public bool Remove(TKey key)

Parameters

key TKey

Key of an entry to remove.

Returns

bool

true when entry has been removed, otherwise false.

Remove(TKey, out TValue)

Attempts to remove an entry with the specified key and to return a value associated with that key.

public bool Remove(TKey key, out TValue removed)

Parameters

key TKey

Key of an entry to remove.

removed TValue

An out parameter that returns a value associated with the key, if it exists.

Returns

bool

true when entry has been removed, otherwise false.

Restart(TKey)

Attempts to restart an entry associated with the specified key by e.g. moving it to the top of the cache.

public bool Restart(TKey key)

Parameters

key TKey

Key of an entry to restart.

Returns

bool

true when entry has been restarted (provided key exists), otherwise false.

TryAdd(TKey, TValue)

Attempts to add a new entry.

public bool TryAdd(TKey key, TValue value)

Parameters

key TKey

Entry's key.

value TValue

Entry's value.

Returns

bool

true when entry has been added (provided key did not exist), otherwise false.

Remarks

When new entry addition causes Count to exceed Capacity, then the Oldest entry will be removed automatically.

TryAdd(TKey, TValue, Duration)

Attempts to add a new entry.

public bool TryAdd(TKey key, TValue value, Duration lifetime)

Parameters

key TKey

Entry's key.

value TValue

Entry's value.

lifetime Duration

Entry's lifetime.

Returns

bool

true when entry has been added (provided key did not exist), otherwise false.

Remarks

When new entry addition causes Count to exceed Capacity, then the Oldest entry will be removed automatically.

TryGetValue(TKey, out TValue)

Gets the value that is associated with the specified key.

public bool TryGetValue(TKey key, out TValue value)

Parameters

key TKey

The key to locate.

value TValue

When this method returns, the value associated with the specified key, if the key is found; otherwise, the default value for the type of the value parameter. This parameter is passed uninitialized.

Returns

bool

true if the object that implements the IReadOnlyDictionary<TKey, TValue> interface contains an element that has the specified key; otherwise, false.

Exceptions

ArgumentNullException

key is null.