Class FakeScheduler (4.8.0) 

public sealed class FakeScheduler : IScheduler

Experimental - please read remarks. Fake implementation of IScheduler, designed to work with FakeClock.

Inheritance

object > FakeScheduler

Implements

IScheduler

Namespace

Google.Api.Gax.Testing

Assembly

Google.Api.Gax.Testing.dll

Remarks

This class is currently hard to use robustly, and cancellation in particular is hard. The API and behavior may change in future versions without a major version bump - in other words, this is not considered part of the stable API of the package.

Constructors

FakeScheduler()

public FakeScheduler()

Constructs a fake scheduler with a new fake clock starting at 0 ticks.

FakeScheduler(FakeClock)

public FakeScheduler(FakeClock clock)

Constructs a fake scheduler which works with the given clock.

Parameter
Name Description
clock FakeClock

Fake clock to observe for timing purposes.

Properties

Clock

public FakeClock Clock { get; }

The clock associated with this scheduler. The clock is advanced as the scheduler runs.

Property Value
Type Description
FakeClock

IdleTimeBeforeAdvancing

public TimeSpan IdleTimeBeforeAdvancing { get; set; }

When running the scheduler, we pause until no more tasks have been scheduled for a certain time, to allow continuations to execute before the clock is advanced. By default this is 10ms, but tests which expect a greater amount of processing may increase this.

Property Value
Type Description
TimeSpan

PostLoopSettleTime

public TimeSpan PostLoopSettleTime { get; set; }

Time to allow test code to execute continuations after the scheduler loop has completed. This is a one-time delay per RunAsync/RunAndPause call, to reduce flakiness.

Property Value
Type Description
TimeSpan

RealTimeTimeout

public TimeSpan RealTimeTimeout { get; set; }

How long the scheduler can run in real time before timing out.

Property Value
Type Description
TimeSpan

SimulatedTimeTimeout

public TimeSpan SimulatedTimeTimeout { get; set; }

How long the scheduler can run in simulated time before timing out.

Property Value
Type Description
TimeSpan

Methods

Delay(TimeSpan, CancellationToken)

public Task Delay(TimeSpan delay, CancellationToken cancellationToken = default)

Returns a task which will complete after the given delay. Whether the returned awaitable is configured to capture the current context or not is implementation-specific. (A test implementation may capture the current context to enable reliable testing.)

Parameters
Name Description
delay TimeSpan

Time to delay for. Must not be negative.
cancellationToken CancellationToken

The cancellation token that will be checked prior to completing the returned task.
Returns
Type Description
Task

A task which will complete after the given delay.

Run(Action)

public void Run(Action action)

Invokes the given action in a separate thread, and then runs the scheduler until one of four conditions is met:

Only the first of these results in the method completing normally; otherwise, an exception is thrown. If the action completes with an exception, that exception is the result of the method. If the action has effectively hung, the thread is not terminated; it is expected that the test will fail without the broken method causing any more harm.

Parameter
Name Description
action Action

The action to execute with the scheduler.
Exceptions
Type Description
FakeSchedulerSchedulerTimeoutException

The scheduler timed out.

RunAsync(Func<Task>)

public Task RunAsync(Func<Task> taskProvider)

Invokes the given action in a separate thread, and then runs the scheduler until one of four conditions is met:

Only the first of these results in the method completing normally; otherwise, an exception is thrown. If the action completes with an exception, that exception is the result of the method. If the action has effectively hung, the thread is not terminated; it is expected that the test will fail without the broken method causing any more harm.

Parameter
Name Description
taskProvider FuncTask

A delegate providing an asynchronous action to execute with the scheduler.
Returns
Type Description
Task
Exceptions
Type Description
FakeSchedulerSchedulerTimeoutException

The scheduler timed out.

RunAsync(TimeSpan)

public Task RunAsync(TimeSpan time)

Runs the scheduler for the given amount of time. If the task completes normally, the clock should have advanced by the given TimeSpan. Any timers scheduled for a later time will still be queued, and can be triggered by running the fake scheduler further.

Parameter
Name Description
time TimeSpan

How long (in simulated time) to run for
Returns
Type Description
Task

A task which will complete when scheduler has processed tasks up until the given time.

RunAsync<T>(Func<Task<T>>)

public Task<T> RunAsync<T>(Func<Task<T>> taskProvider)

Runs a task in a separate thread, and the scheduler alongside it to simulate sleeping and delaying.

Parameter
Name Description
taskProvider FuncTask

A delegate providing an asynchronous function to execute with the scheduler.
Returns
Type Description
Task
Type Parameter
Name Description
T
Remarks

The task provider is run in a separate thread, so that even synchronous task providers (e.g. using FromResult<TResult>(TResult)) work appropriately. The scheduler is run until one of four conditions is met:

Only the first of these results in the method completing normally; otherwise, an exception is thrown. If the task completes with an exception, that exception is the result of the method. If the task has effectively hung, the thread is not terminated; it is expected that the test will fail without the broken method causing any more harm.

Exceptions
Type Description
FakeSchedulerSchedulerTimeoutException

The scheduler timed out.

RunForSecondsAsync(int)

public Task RunForSecondsAsync(int seconds)

Runs the scheduler for the given number of seconds. If the task completes normally, the clock should have advanced by the given number of seconds. Any timers scheduled for a later time will still be queued, and can be triggered by running the fake scheduler further.

Parameter
Name Description
seconds int

How many seconds (in simulated time) to run for
Returns
Type Description
Task

A task which will complete when scheduler has processed tasks up until the given time.

Run<T>(Func<T>)

public T Run<T>(Func<T> func)

Invokes the given action in a separate thread, and then runs the scheduler until one of four conditions is met:

Only the first of these results in the method completing normally; otherwise, an exception is thrown. If the action completes with an exception, that exception is the result of the method. If the action has effectively hung, the thread is not terminated; it is expected that the test will fail without the broken method causing any more harm.

Parameter
Name Description
func Func

The function to execute with the scheduler.
Returns
Type Description
T
Type Parameter
Name Description
T
Exceptions
Type Description
FakeSchedulerSchedulerTimeoutException

The scheduler timed out.

Extension Method