reactor.test.scheduler

Class VirtualTimeScheduler

java.lang.Object

reactor.test.scheduler.VirtualTimeScheduler

All Implemented Interfaces:

Disposable, Scheduler

public class VirtualTimeScheduler
extends Object
implements Scheduler

A Scheduler that uses a virtual clock, allowing to manipulate time (eg. in tests). Can replace the default reactor schedulers by using the getOrSet() / set(VirtualTimeScheduler) methods.

Author:

Stephane Maldini

Nested Class Summary

Nested classes/interfaces inherited from interface reactor.core.scheduler.Scheduler

Scheduler.Worker

Nested classes/interfaces inherited from interface reactor.core.Disposable

Disposable.Composite, Disposable.Swap

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	VirtualTimeScheduler(boolean defer)

Method Summary

Modifier and Type	Method and Description
void	advanceTime() Triggers any tasks that have not yet been executed and that are scheduled to be executed at or before this VirtualTimeScheduler's present time.
void	advanceTimeBy(Duration delayTime) Moves the VirtualTimeScheduler's clock forward by a specified amount of time.
void	advanceTimeTo(Instant instant) Moves the VirtualTimeScheduler's clock to a particular moment in time.
static VirtualTimeScheduler	create() Create a new VirtualTimeScheduler without enabling it.
static VirtualTimeScheduler	create(boolean defer) Create a new VirtualTimeScheduler without enabling it.
reactor.test.scheduler.VirtualTimeScheduler.VirtualTimeWorker	createWorker() Creates a worker of this Scheduler.
void	dispose() Instructs this Scheduler to release all resources and reject any new tasks to be executed.
static VirtualTimeScheduler	get() The current VirtualTimeScheduler assigned in Schedulers
static VirtualTimeScheduler	getOrSet() Assign a newly created VirtualTimeScheduler to all Schedulers.Factory factories ONLY if no VirtualTimeScheduler is currently set.
static VirtualTimeScheduler	getOrSet(boolean defer) Assign a newly created VirtualTimeScheduler to all Schedulers.Factory factories ONLY if no VirtualTimeScheduler is currently set.
static VirtualTimeScheduler	getOrSet(VirtualTimeScheduler scheduler) Assign an externally created VirtualTimeScheduler to the relevant Schedulers.Factory factories, depending on how it was created (see create() and create()).
long	getScheduledTaskCount() Get the number of scheduled tasks.
boolean	isDisposed() Optionally return true when the resource or task is disposed.
static boolean	isFactoryEnabled() Return true if there is a VirtualTimeScheduler currently used by the Schedulers factory (ie it has been enabled), false otherwise (ie it has been reset).
long	now(TimeUnit unit) Returns the "current time" notion of this scheduler.
static void	reset() Re-activate the global Schedulers and potentially customized Schedulers.Factory that were active prior to last activation of VirtualTimeScheduler factories.
Disposable	schedule(Runnable task) Schedules the non-delayed execution of the given task on this scheduler.
Disposable	schedule(Runnable task, long delay, TimeUnit unit) Schedules the execution of the given task with the given delay amount.
Disposable	schedulePeriodically(Runnable task, long initialDelay, long period, TimeUnit unit) Schedules a periodic execution of the given task with the given initial delay and period.
static VirtualTimeScheduler	set(VirtualTimeScheduler scheduler) Assign an externally created VirtualTimeScheduler to the relevant Schedulers.Factory factories, depending on how it was created (see create() and create()).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface reactor.core.scheduler.Scheduler

disposeGracefully, init, start

Constructor Detail

VirtualTimeScheduler

protected VirtualTimeScheduler(boolean defer)

Method Detail

create

public static VirtualTimeScheduler create()

Create a new VirtualTimeScheduler without enabling it. Call getOrSet(VirtualTimeScheduler) to enable it on Schedulers.Factory factories.

Returns:

a new VirtualTimeScheduler intended for timed-only Schedulers factories.

create

public static VirtualTimeScheduler create(boolean defer)

Create a new VirtualTimeScheduler without enabling it. Call getOrSet(VirtualTimeScheduler) to enable it on Schedulers.Factory factories.

Parameters:

defer - true to defer all clock move operations until there are tasks in queue

Returns:

a new VirtualTimeScheduler intended for timed-only Schedulers factories.

getOrSet

public static VirtualTimeScheduler getOrSet()

Assign a newly created VirtualTimeScheduler to all Schedulers.Factory factories ONLY if no VirtualTimeScheduler is currently set. In case of scheduler creation, there is no deferring of time operations (see create(boolean). Note that prior to replacing the factories, a snapshot will be performed. Resetting the factory will restore said snapshot.

While this methods makes best effort to be thread safe, it is usually advised to perform such wide-impact setup serially and BEFORE all test code runs (setup/beforeAll/beforeClass...). The created Scheduler is returned.

Returns:

the VirtualTimeScheduler that was created and set through the factory

getOrSet

public static VirtualTimeScheduler getOrSet(boolean defer)

Assign a newly created VirtualTimeScheduler to all Schedulers.Factory factories ONLY if no VirtualTimeScheduler is currently set. In case of scheduler creation, there is opt-in deferring of time related operations (see create(boolean). Note that prior to replacing the factories, a snapshot will be performed. Resetting the factory will restore said snapshot.

While this methods makes best effort to be thread safe, it is usually advised to perform such wide-impact setup serially and BEFORE all test code runs (setup/beforeAll/beforeClass...). The created Scheduler is returned.

Parameters:

defer - true to defer all clock move operations until there are tasks in queue, if a scheduler is created

Returns:

the VirtualTimeScheduler that was created and set through the factory

See Also:

create(boolean)

getOrSet

public static VirtualTimeScheduler getOrSet(VirtualTimeScheduler scheduler)

Assign an externally created VirtualTimeScheduler to the relevant Schedulers.Factory factories, depending on how it was created (see create() and create()). Note that the returned scheduler should always be captured and used going forward, as the provided scheduler can be superseded by a matching scheduler that has already been enabled. Note also that prior to replacing the factories, a snapshot will be performed. Resetting the factory will restore said snapshot.

While this methods makes best effort to be thread safe, it is usually advised to perform such wide-impact setup serially and BEFORE all test code runs (setup/beforeAll/beforeClass...). The actual enabled Scheduler is returned.

Parameters:

scheduler - the VirtualTimeScheduler to use in factories.

Returns:

the enabled VirtualTimeScheduler (can be different from the provided one)

set

public static VirtualTimeScheduler set(VirtualTimeScheduler scheduler)

Assign an externally created VirtualTimeScheduler to the relevant Schedulers.Factory factories, depending on how it was created (see create() and create()). Contrary to getOrSet(VirtualTimeScheduler), the provided scheduler is always used, even if a matching scheduler is currently enabled. Note that prior to replacing the factories, a snapshot will be performed. Resetting the factory will restore said snapshot.

While this methods makes best effort to be thread safe, it is usually advised to perform such wide-impact setup serially and BEFORE all test code runs (setup/beforeAll/beforeClass...).

Parameters:

scheduler - the VirtualTimeScheduler to use in factories.

Returns:

the enabled VirtualTimeScheduler (same as provided), for chaining

get

public static VirtualTimeScheduler get()

The current VirtualTimeScheduler assigned in Schedulers

Returns:

current VirtualTimeScheduler assigned in Schedulers

Throws:

IllegalStateException - if no VirtualTimeScheduler has been found

isFactoryEnabled

public static boolean isFactoryEnabled()

Return true if there is a VirtualTimeScheduler currently used by the Schedulers factory (ie it has been enabled), false otherwise (ie it has been reset).

reset

public static void reset()

Re-activate the global Schedulers and potentially customized Schedulers.Factory that were active prior to last activation of VirtualTimeScheduler factories. (ie the last set or getOrSet).

While this methods makes best effort to be thread safe, it is usually advised to perform such wide-impact setup serially and AFTER all tested code has been run (teardown/afterAll/afterClass...).

advanceTime

public void advanceTime()

Triggers any tasks that have not yet been executed and that are scheduled to be executed at or before this VirtualTimeScheduler's present time.

advanceTimeBy

public void advanceTimeBy(Duration delayTime)

Moves the VirtualTimeScheduler's clock forward by a specified amount of time.

Parameters:

delayTime - the amount of time to move the VirtualTimeScheduler's clock forward

advanceTimeTo

public void advanceTimeTo(Instant instant)

Moves the VirtualTimeScheduler's clock to a particular moment in time.

Parameters:

instant - the point in time to move the VirtualTimeScheduler's clock to

getScheduledTaskCount

public long getScheduledTaskCount()

Get the number of scheduled tasks.

This count includes tasks that have already performed as well as ones scheduled in future. For periodical task, initial task is first scheduled and counted as one. Whenever subsequent repeat happens this count gets incremented for the one that is scheduled for the next run.

Returns:

number of tasks that have scheduled on this scheduler.

createWorker

public reactor.test.scheduler.VirtualTimeScheduler.VirtualTimeWorker createWorker()

Description copied from interface: Scheduler

Creates a worker of this Scheduler.

Once the Worker is no longer in use, one should call dispose() on it to release any resources the particular Scheduler may have used. It depends on the implementation, but Scheduler Workers should usually run tasks in FIFO order. Some implementations may entirely delegate the scheduling to an underlying structure (like an ExecutorService).

Specified by:

createWorker in interface Scheduler

Returns:

the Worker instance.

now

public long now(TimeUnit unit)

Description copied from interface: Scheduler

Returns the "current time" notion of this scheduler.

Implementation Note: The default implementation uses System.currentTimeMillis() when requested with a TimeUnit of milliseconds or coarser, and System.nanoTime() otherwise. As a consequence, results should not be interpreted as absolute timestamps in the latter case, only monotonicity inside the current JVM can be expected.

Specified by:

now in interface Scheduler

Parameters:

unit - the target unit of the current time

Returns:

the current time value in the target unit of measure

schedule

public Disposable schedule(Runnable task)

Description copied from interface: Scheduler

Schedules the non-delayed execution of the given task on this scheduler.

This method is safe to be called from multiple threads but there are no ordering guarantees between tasks.

Specified by:

schedule in interface Scheduler

Parameters:

task - the task to execute

Returns:

the Disposable instance that let's one cancel this particular task. If the Scheduler has been shut down, throw a RejectedExecutionException.

schedule

public Disposable schedule(Runnable task,
                           long delay,
                           TimeUnit unit)

Description copied from interface: Scheduler

Schedules the execution of the given task with the given delay amount.

This method is safe to be called from multiple threads but there are no ordering guarantees between tasks.

Specified by:

schedule in interface Scheduler

Parameters:

task - the task to schedule

delay - the delay amount, non-positive values indicate non-delayed scheduling

unit - the unit of measure of the delay amount

Returns:

the Disposable that let's one cancel this particular delayed task, or throw a RejectedExecutionException if the Scheduler is not capable of scheduling with delay.

isDisposed

public boolean isDisposed()

Description copied from interface: Disposable

Optionally return true when the resource or task is disposed.

Implementations are not required to track disposition and as such may never return true even when disposed. However, they MUST only return true when there's a guarantee the resource or task is disposed.

Specified by:

isDisposed in interface Disposable

Returns:

true when there's a guarantee the resource or task is disposed.

dispose

public void dispose()

Description copied from interface: Scheduler

Instructs this Scheduler to release all resources and reject any new tasks to be executed.

The operation is thread-safe.

The Scheduler may choose to ignore this instruction.

When used in combination with Scheduler.disposeGracefully() there are no guarantees that all resources will be forcefully shutdown. When a graceful disposal has started, the references to the underlying Executors might have already been lost.

Specified by:

dispose in interface Disposable

Specified by:

dispose in interface Scheduler

schedulePeriodically

public Disposable schedulePeriodically(Runnable task,
                                       long initialDelay,
                                       long period,
                                       TimeUnit unit)

Description copied from interface: Scheduler

Schedules a periodic execution of the given task with the given initial delay and period.

This method is safe to be called from multiple threads but there are no ordering guarantees between tasks.

The periodic execution is at a fixed rate, that is, the first execution will be after the initial delay, the second after initialDelay + period, the third after initialDelay + 2 * period, and so on.

Specified by:

schedulePeriodically in interface Scheduler

Parameters:

task - the task to schedule

initialDelay - the initial delay amount, non-positive values indicate non-delayed scheduling

period - the period at which the task should be re-executed

unit - the unit of measure of the delay amount

Returns:

the Disposable that let's one cancel this particular delayed task, or throw a RejectedExecutionException if the Scheduler is not capable of scheduling periodically.