Table of Contents

Class PolledReferencedResource<TKey, TValue>

Namespace
Acuit.Pinpoint.ResourceManagement
Assembly
Acuit.Pinpoint.ResourceManagement.Abstractions.dll

A base class for implementing IReferencedResource<TKey, TValue> for resources that must be periodically polled to retrieve updated values.

public abstract class PolledReferencedResource<TKey, TValue> : ReferencedResource<TKey, TValue>, IReferencedResource<TKey, TValue>, IDisposable where TKey : notnull

Type Parameters

TKey

The type of the key used to identify different resources, which must be a non-nullable type.

TValue

The resource value type.

Inheritance
ReferencedResource<TKey, TValue>
PolledReferencedResource<TKey, TValue>
Implements
IReferencedResource<TKey, TValue>
Inherited Members

Remarks

To properly implement a derived class:

  1. Provide an override for PollValueAsync(CancellationToken) that performs the poll to retrieve the latest resource value.
  2. Provide an override for GetNextPollPeriod(bool).
  3. Call StartPolling() in the constructor to start the polling loop.

Note that this class does not perform any caching; the polling only occurs as long as there is at least on active reference to a particular resource. When all references to a particular resource are released, the polling loop still stop, and then when a new reference is created, the polling loop will start anew, with an immediate initial poll.

This class is appropriate for resources that will have long-lived references that must respond to changes in resource values, but that must be polled to retrieve the latest values to check for changes. See the remarks for ReferencedResource<TKey, TValue> for information about implementing resource providers that cache retrieved values to limit the frequency of expensive retrievals, even across referenced resource lifetimes.

Constructors

PolledReferencedResource(TKey, TimeProvider, IEqualityComparer<TValue>?)

Initializes a new instance of the DerivedReferencedResource<TKey, TValue, TSourceValue> class.

protected PolledReferencedResource(TKey key, TimeProvider timeProvider, IEqualityComparer<TValue>? equalityComparer = null)

Parameters

key TKey

The resource key.

timeProvider TimeProvider

The time provider.

equalityComparer IEqualityComparer<TValue>

The equality comparer to use to determine whether a new polled value has changed since the last poll. If not provided, the default equality comparer for TValue will be used, provided by Default.

Exceptions

ArgumentNullException

key is null.

ArgumentNullException

timeProvider is null.

Properties

PollingLoopTask

Gets the Task representing the asynchronous background polling loop, or null if the polling loop has not been started.

public Task? PollingLoopTask { get; }

Property Value

Task

Remarks

This can be observed to handle unexpected errors in the asynchronous background polling loop. Normally, this task will run to completion when this PolledReferencedResource<TKey, TValue> object is disposed (which signals the polling loop to stop, but without waiting for it to actually stop). If an unexpected error occurs in the asynchronous background polling loop, polling will stop, and this task will complete with an exception.

Methods

Dispose(bool)

Closes and releases all resources used by the ReferencedResource<TKey, TValue>.

protected override void Dispose(bool disposing)

Parameters

disposing bool

true when this is in response to a call to Dispose().

Remarks

Derived classes should override this when they have any resources that should be disposed.

GetChangeToken()

Returns a IChangeToken that can be used to observe when this resource value changes.

protected override IChangeToken GetChangeToken()

Returns

IChangeToken

A IChangeToken.

GetNextPollPeriod(bool)

Gets the time period to wait before initiating the next poll.

protected abstract TimeSpan GetNextPollPeriod(bool lastPollFailed)

Parameters

lastPollFailed bool

Whether the last poll attempt failed (i.e., PollValueAsync(CancellationToken) threw an exception). This is typically used to, upon a poll error, cause the next poll attempt to occur sooner than it normally would.

Returns

TimeSpan

A TimeSpan. If this is less than or equal to Zero, then the next poll will be initiated immediately.

GetValueAsync(CancellationToken)

Gets the resource value.

protected override Task<TValue> GetValueAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

A cancellation token that can be used to request canceling retrieving the resource.

Returns

Task<TValue>

The task object representing the asynchronous operation.

Remarks

Once the operation completes, the Result property on the returned task object contains the resource value.

This method will be called on behalf of resource references, ensuring it is never called more than once at a time. The returned value will be cached and returned to all references until the change token (retrieved via GetChangeToken() before calling GetValueAsync(CancellationToken)) signals a change.

If this method throws an exception, it will be propagated to resource references (via their call to GetValueAsync(CancellationToken)), and subsequent calls to GetValueAsync(CancellationToken) by resource references will cause this method to be called again.

Exceptions

Exception

The resource could not be retrieved. Specific exceptions depend on the implementation.

PollValueAsync(CancellationToken)

Performs the poll to retrieve the latest resource value.

protected abstract Task<TValue> PollValueAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

A cancellation token that can be used to request cancellation.

Returns

Task<TValue>

The task object representing the asynchronous operation.

Remarks

Once the operation successfully completes, the Result property on the returned task object contains the retrieved resource value. If the poll fails, the Exception property on the returned task object contains the error that occurred.

Exceptions

Exception

The resource value could not be retrieved. Specific exceptions depend on the implementation.

StartPolling()

Starts the polling loop.

protected void StartPolling()

Exceptions

InvalidOperationException

The polling loop has already been started.

ObjectDisposedException

The object has been disposed.