public interface Scheduler extends Disposable
Implementations that use an underlying ExecutorService
or
ScheduledExecutorService
should decorate it with the relevant Schedulers
hook
(Schedulers.decorateExecutorService(Scheduler, ScheduledExecutorService)
.
Modifier and Type | Interface and Description |
---|---|
static interface |
Scheduler.Worker
A worker representing an asynchronous boundary that executes tasks.
|
Disposable.Composite, Disposable.Swap
Modifier and Type | Method and Description |
---|---|
Scheduler.Worker |
createWorker()
Creates a worker of this Scheduler.
|
default void |
dispose()
Instructs this Scheduler to release all resources and reject
any new tasks to be executed.
|
default Mono<Void> |
disposeGracefully()
Lazy variant of
dispose() that also allows for graceful cleanup
of underlying resources. |
default void |
init()
Instructs this Scheduler to prepare itself for running tasks
directly or through its
Scheduler.Worker s. |
default long |
now(TimeUnit unit)
Returns the "current time" notion of this scheduler.
|
Disposable |
schedule(Runnable task)
Schedules the non-delayed execution of the given task on this scheduler.
|
default Disposable |
schedule(Runnable task,
long delay,
TimeUnit unit)
Schedules the execution of the given task with the given delay amount.
|
default 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.
|
default void |
start()
Deprecated.
Use
init() instead. The use of this method is discouraged.
Some implementations allowed restarting a Scheduler, while others did not. One
of the issues with restarting is that checking
the disposed state is unreliable in concurrent scenarios. |
isDisposed
Disposable schedule(Runnable task)
This method is safe to be called from multiple threads but there are no ordering guarantees between tasks.
task
- the task to executeDisposable
instance that let's one cancel this particular task.
If the Scheduler
has been shut down, throw a RejectedExecutionException
.default Disposable schedule(Runnable task, long delay, TimeUnit unit)
This method is safe to be called from multiple threads but there are no ordering guarantees between tasks.
task
- the task to scheduledelay
- the delay amount, non-positive values indicate non-delayed schedulingunit
- the unit of measure of the delay amountDisposable
that let's one cancel this particular delayed task,
or throw a RejectedExecutionException
if the Scheduler is not capable of scheduling with delay.default Disposable schedulePeriodically(Runnable task, long initialDelay, long period, TimeUnit unit)
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.
task
- the task to scheduleinitialDelay
- the initial delay amount, non-positive values indicate non-delayed schedulingperiod
- the period at which the task should be re-executedunit
- the unit of measure of the delay amountDisposable
that let's one cancel this particular delayed task,
or throw a RejectedExecutionException
if the Scheduler is not capable of scheduling periodically.default long now(TimeUnit unit)
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.
unit
- the target unit of the current timeScheduler.Worker createWorker()
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
).
default void dispose()
The operation is thread-safe.
The Scheduler may choose to ignore this instruction.
When used in combination with disposeGracefully()
there are no guarantees that all resources will be forcefully shutdown.
When a graceful disposal has started, the references to the underlying
Executor
s might have already been lost.
dispose
in interface Disposable
default Mono<Void> disposeGracefully()
dispose()
that also allows for graceful cleanup
of underlying resources.
It is advised to apply a Mono.timeout(Duration)
operator to the
resulting Mono
.
The returned Mono
can be retried
in case of
timeout errors
. It can also be
followed by a call to dispose()
to issue a forceful shutdown of
underlying resources.
@Deprecated default void start()
init()
instead. The use of this method is discouraged.
Some implementations allowed restarting a Scheduler, while others did not. One
of the issues with restarting is that checking
the disposed state
is unreliable in concurrent scenarios.The operation is thread-safe but one should avoid using start() and dispose() concurrently as it would non-deterministically leave the Scheduler in either active or inactive state.
init()
default void init()
Scheduler.Worker
s.
Implementations are encouraged to throw an exception if this method is called
after the scheduler has been disposed via dispose()
or disposeGracefully()
.