Class FakeScheduler (4.2.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
NameDescription
clockFakeClock

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
TypeDescription
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
TypeDescription
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
TypeDescription
TimeSpan

RealTimeTimeout

public TimeSpan RealTimeTimeout { get; set; }

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

Property Value
TypeDescription
TimeSpan

SimulatedTimeTimeout

public TimeSpan SimulatedTimeTimeout { get; set; }

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

Property Value
TypeDescription
TimeSpan

Methods

Delay(TimeSpan, CancellationToken)

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

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
NameDescription
delayTimeSpan

Time to delay for. Must not be negative.

cancellationTokenCancellationToken

The cancellation token that will be checked prior to completing the returned task.

Returns
TypeDescription
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
NameDescription
actionAction

The action to execute with the scheduler.

Exceptions
TypeDescription
FakeScheduler.SchedulerTimeoutException

The scheduler timed out.

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
NameDescription
funcFunc<T>

The function to execute with the scheduler.

Returns
TypeDescription
T
Type Parameter
NameDescription
T
Exceptions
TypeDescription
FakeScheduler.SchedulerTimeoutException

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
NameDescription
taskProviderFunc<Task>

A delegate providing an asynchronous action to execute with the scheduler.

Returns
TypeDescription
Task
Exceptions
TypeDescription
FakeScheduler.SchedulerTimeoutException

The scheduler timed out.

RunAsync(TimeSpan)

public async 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
NameDescription
timeTimeSpan

How long (in simulated time) to run for

Returns
TypeDescription
Task

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

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

public async 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
NameDescription
taskProviderFunc<Task<T>>

A delegate providing an asynchronous function to execute with the scheduler.

Returns
TypeDescription
Task<T>
Type Parameter
NameDescription
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
TypeDescription
FakeScheduler.SchedulerTimeoutException

The scheduler timed out.

RunForSecondsAsync(Int32)

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
NameDescription
secondsInt32

How many seconds (in simulated time) to run for

Returns
TypeDescription
Task

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