Class RandomAccessCache<TValue>

Represents concurrent cache optimized for random access, which keeps the entries in unmanaged memory.

Inheritance

object

Disposable

RandomAccessCache<TValue>

Implements

IDisposable

IAsyncDisposable

Epoch.INativeResourceManager

Inherited Members

Disposable.Dispose()

Disposable.Dispose(IEnumerable<IDisposable>)

Disposable.DisposeAsync(params IEnumerable<IAsyncDisposable>)

Disposable.Dispose<TDisposable>(params ReadOnlySpan<TDisposable>)

object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Namespace: DotNext.Runtime.Caching

Assembly: DotNext.Threading.dll

Syntax

public sealed class RandomAccessCache<TValue> : Disposable, IDisposable, IAsyncDisposable, Epoch.INativeResourceManager where TValue : unmanaged

Type Parameters

Name	Description
TValue	The type of the values.

Remarks

The cache entries are not visible to GC, so the size of the cache doesn't affect GC pauses. The key is a sequence of bytes copied to the cache entry. The value of the entry cannot be modified after insertion. All the sessions must be disposed. The cache evicts older records on overflow using SIEVE algorithm.

Constructors

RandomAccessCache(int)

Initializes a new cache.

Declaration

public RandomAccessCache(int capacity)

Parameters

Type	Name	Description
int	capacity	Maximum cache size.

Exceptions

Type	Condition
ArgumentOutOfRangeException	capacity is less than or equal to zero.

RandomAccessCache(int, int)

Initializes a new cache.

Declaration

public RandomAccessCache(int capacity, int concurrencyLevel)

Parameters

Type	Name	Description
int	capacity	Maximum cache size.
int	concurrencyLevel	The expected number of concurrent writers. It determines the number of internal wait queues for the writers waiting for the same bucket, and doesn't limit the number of concurrent writers.

Exceptions

Type	Condition
ArgumentOutOfRangeException	capacity is less than or equal to zero; or concurrencyLevel is less than or equal to zero.

Properties

Capacity

Gets the capacity of this cache.

Declaration

public int Capacity { get; }

Property Value

Type	Description
int

EqualityComparer

Gets or sets the hash algorithm for the key.

Declaration

public IEqualityComparer<ReadOnlySpan<byte>> EqualityComparer { get; init; }

Property Value

Type	Description
IEqualityComparer<ReadOnlySpan<byte>>

Exceptions

Type	Condition
ArgumentNullException	value is null.

Eviction

Gets or sets a callback that can be used to clean up the evicted value.

Declaration

public ReadOnlySpanAction<byte, TValue>? Eviction { get; init; }

Property Value

Type	Description
ReadOnlySpanAction<byte, TValue>

Remarks

The callback is invoked once for every cache record when the record is no longer available: it is evicted or invalidated, and all the sessions associated with the record are closed. The callback is invoked for the remaining records when the cache is disposed as well. If the cache is not disposed explicitly, the finalizer releases the memory without calling the callback. The key is valid only during the call. The callback should not throw: the exception propagates to the caller that released the record, which can be the background eviction process.

MeasurementTags

Sets a list of tags to be associated with each measurement.

Declaration

[CLSCompliant(false)]
public TagList MeasurementTags { init; }

Property Value

Type	Description
TagList

Methods

ChangeAsync<TKey>(TKey, CancellationToken)

Opens a session that can be used to insert the value associated with the key.

Declaration

public ValueTask<RandomAccessCache<TValue>.ReadWriteSession<TKey>> ChangeAsync<TKey>(TKey key, CancellationToken token = default) where TKey : ISupplier<ReadOnlySpan<byte>>

Parameters

Type	Name	Description
TKey	key	The key of the cache record.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<RandomAccessCache<TValue>.ReadWriteSession<TKey>>	The session that can be used to read or insert the cache record.

Type Parameters

Name	Description
TKey	The type of the key.

Remarks

The cache guarantees that the value cannot be evicted concurrently with the returned session. However, the value can be evicted immediately after. The caller must dispose the session.

Exceptions

Type	Condition
OperationCanceledException	The operation has been canceled.
ObjectDisposedException	The cache is disposed.

Change<TKey>(TKey, TimeSpan, CancellationToken)

Opens a session synchronously that can be used to insert the value associated with the key.

Declaration

public RandomAccessCache<TValue>.ReadWriteSession<TKey> Change<TKey>(TKey key, TimeSpan timeout, CancellationToken token = default) where TKey : ISupplier<ReadOnlySpan<byte>>

Parameters

Type	Name	Description
TKey	key	The key of the cache record.
TimeSpan	timeout	The time to wait for the cache lock.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
RandomAccessCache<TValue>.ReadWriteSession<TKey>	The session that can be used to read or insert the cache record.

Type Parameters

Name	Description
TKey	The type of the key.

Remarks

The cache guarantees that the value cannot be evicted concurrently with the returned session. However, the value can be evicted immediately after. The caller must dispose the session.

Exceptions

Type	Condition
ArgumentOutOfRangeException	timeout is negative.
TimeoutException	The internal lock cannot be acquired in timely manner.
OperationCanceledException	The operation has been canceled.
ObjectDisposedException	The cache is disposed.

Contains(ReadOnlySpan<byte>)

Determines whether the cache entry associated with the specified key exists in the cache.

Declaration

public bool Contains(ReadOnlySpan<byte> key)

Parameters

Type	Name	Description
ReadOnlySpan<byte>	key	The key to check.

Returns

Type	Description
bool	true if the cache entry associated with key exists in the cache; otherwise, false.

Dispose(bool)

Releases managed and unmanaged resources associated with this object.

Declaration

protected override void Dispose(bool disposing)

Parameters

Type	Name	Description
bool	disposing	true if called from Dispose(); false if called from finalizer ~Disposable().

Overrides

Disposable.Dispose(bool)

DisposeAsync()

Declaration

public ValueTask DisposeAsync()

Returns

Type	Description
ValueTask

DisposeAsyncCore()

Releases managed resources associated with this object asynchronously.

Declaration

protected override ValueTask DisposeAsyncCore()

Returns

Type	Description
ValueTask	The task representing asynchronous execution of this method.

Overrides

Disposable.DisposeAsyncCore()

Remarks

This method makes sense only if derived class implements IAsyncDisposable interface.

InvalidateAsync(CancellationToken)

Invalidates the entire cache.

Declaration

public ValueTask InvalidateAsync(CancellationToken token = default)

Parameters

Type	Name	Description
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask	The state of the asynchronous operation.

Exceptions

Type	Condition
OperationCanceledException	The operation has been canceled.
ObjectDisposedException	The cache is disposed.

InvalidateAsync<TKey>(TKey, CancellationToken)

Invalidates the cache record associated with the specified key.

Declaration

public ValueTask<bool> InvalidateAsync<TKey>(TKey key, CancellationToken token = default) where TKey : ISupplier<ReadOnlySpan<byte>>

Parameters

Type	Name	Description
TKey	key	The key of the cache record to be removed.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<bool>	true if the cache record associated with key is removed successfully; otherwise, false.

Type Parameters

Name	Description
TKey	The type of the key.

Exceptions

Type	Condition
OperationCanceledException	The operation has been canceled.
ObjectDisposedException	The cache is disposed.

Invalidate<TKey>(TKey, TimeSpan, CancellationToken)

Invalidates the cache record associated with the specified key synchronously.

Declaration

public bool Invalidate<TKey>(TKey key, TimeSpan timeout, CancellationToken token = default) where TKey : ISupplier<ReadOnlySpan<byte>>

Parameters

Type	Name	Description
TKey	key	The key of the cache record to be removed.
TimeSpan	timeout	The time to wait for the cache lock.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
bool	true if the cache record associated with key is removed successfully; otherwise, false.

Type Parameters

Name	Description
TKey	The type of the key.

Exceptions

Type	Condition
ArgumentOutOfRangeException	timeout is negative.
TimeoutException	The internal lock cannot be acquired in timely manner.
OperationCanceledException	The operation has been canceled.
ObjectDisposedException	The cache is disposed.

ReplaceAsync<TKey>(TKey, CancellationToken)

Replaces the cache record associated with the specified key.

Declaration

public ValueTask<RandomAccessCache<TValue>.ReadWriteSession<TKey>> ReplaceAsync<TKey>(TKey key, CancellationToken token = default) where TKey : ISupplier<ReadOnlySpan<byte>>

Parameters

Type	Name	Description
TKey	key	The key of the cache record.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<RandomAccessCache<TValue>.ReadWriteSession<TKey>>	The session that can be used to insert the cache record.

Type Parameters

Name	Description
TKey	The type of the key.

Remarks

The existing record is removed, and the returned session can be used to insert a new value. If the session is disposed without inserting a value, the cache has no record associated with the key. The caller must dispose the session.

Exceptions

Type	Condition
OperationCanceledException	The operation has been canceled.
ObjectDisposedException	The cache is disposed.

Replace<TKey>(TKey, TimeSpan, CancellationToken)

Replaces the cache record associated with the specified key synchronously.

Declaration

public RandomAccessCache<TValue>.ReadWriteSession<TKey> Replace<TKey>(TKey key, TimeSpan timeout, CancellationToken token = default) where TKey : ISupplier<ReadOnlySpan<byte>>

Parameters

Type	Name	Description
TKey	key	The key of the cache record.
TimeSpan	timeout	The time to wait for the cache lock.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
RandomAccessCache<TValue>.ReadWriteSession<TKey>	The session that can be used to insert the cache record.

Type Parameters

Name	Description
TKey	The type of the key.

Remarks

The existing record is removed, and the returned session can be used to insert a new value. If the session is disposed without inserting a value, the cache has no record associated with the key. The caller must dispose the session.

Exceptions

Type	Condition
ArgumentOutOfRangeException	timeout is negative.
TimeoutException	The internal lock cannot be acquired in timely manner.
OperationCanceledException	The operation has been canceled.
ObjectDisposedException	The cache is disposed.

TryRead(ReadOnlySpan<byte>, out ReadSession)

Tries to read the cached record.

Declaration

public bool TryRead(ReadOnlySpan<byte> key, out RandomAccessCache<TValue>.ReadSession session)

Parameters

Type	Name	Description
ReadOnlySpan<byte>	key	The key of the cache record.
RandomAccessCache<TValue>.ReadSession	session	A session that can be used to read the cached record.

Returns

Type	Description
bool	true if the record is available for reading and the session is active; otherwise, false.

Remarks

The cache guarantees that the value cannot be evicted concurrently with the session. However, the value can be evicted immediately after. The caller must dispose session.

TryRemoveAsync<TKey>(TKey, CancellationToken)

Tries to remove the cache record associated with the specified key.

Declaration

public ValueTask<RandomAccessCache<TValue>.ReadSession?> TryRemoveAsync<TKey>(TKey key, CancellationToken token = default) where TKey : ISupplier<ReadOnlySpan<byte>>

Parameters

Type	Name	Description
TKey	key	The key of the cache record to be removed.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<RandomAccessCache<TValue>.ReadSession?>	The session that can be used to read the removed cache record; or null if there is no record associated with key.

Type Parameters

Name	Description
TKey	The type of the key.

Remarks

The removed record remains available for reading until the returned session is disposed. The caller must dispose the session.

Exceptions

Type	Condition
OperationCanceledException	The operation has been canceled.
ObjectDisposedException	The cache is disposed.

TryRemove<TKey>(TKey, out ReadSession, TimeSpan, CancellationToken)

Tries to remove the cache record associated with the specified key synchronously.

Declaration

public bool TryRemove<TKey>(TKey key, out RandomAccessCache<TValue>.ReadSession session, TimeSpan timeout, CancellationToken token = default) where TKey : ISupplier<ReadOnlySpan<byte>>

Parameters

Type	Name	Description
TKey	key	The key of the cache record to be removed.
RandomAccessCache<TValue>.ReadSession	session	The session that can be used to read the removed cache record.
TimeSpan	timeout	The time to wait for the cache lock.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
bool	true if the record associated with key exists; otherwise, false.

Type Parameters

Name	Description
TKey	The type of the key.

Remarks

The removed record remains available for reading until the returned session is disposed. The caller must dispose the session.

Exceptions

Type	Condition
ArgumentOutOfRangeException	timeout is negative.
TimeoutException	The internal lock cannot be acquired in timely manner.
OperationCanceledException	The operation has been canceled.
ObjectDisposedException	The cache is disposed.

Implements

IDisposable

IAsyncDisposable

Epoch.INativeResourceManager

Extension Methods

BasicExtensions.As<T>(T)

BasicExtensions.IsBetween<T, TLowerBound, TUpperBound>(T, TLowerBound, TUpperBound)

BasicExtensions.IsOneOf<T>(T, params ReadOnlySpan<T>)