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

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

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:

The action completes successfully
The action completes with an exception
RealTimeTimeout of real time has elapsed
SimulatedTimeTimeout of simulated time has elapsed

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:

The action completes successfully
The action completes with an exception
RealTimeTimeout of real time has elapsed
SimulatedTimeTimeout of simulated time has elapsed

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:

The task completes successfully
The task completes with an exception
RealTimeTimeout of real time has elapsed
SimulatedTimeTimeout of simulated time has elapsed

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:

The action completes successfully
The action completes with an exception
RealTimeTimeout of real time has elapsed
SimulatedTimeTimeout of simulated time has elapsed

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

SchedulerExtensions.Sleep(IScheduler, TimeSpan, CancellationToken)