Class SynchronizationContext
- All Implemented Interfaces:
Executor
- Ordering. Tasks are run in the same order as they are submitted via
execute(java.lang.Runnable)
andexecuteLater(java.lang.Runnable)
. - Serialization. Tasks are run in sequence and establish a happens-before relationship between them.
- Non-reentrancy. If a task running in a synchronization context executes or schedules another task in the same synchronization context, the latter task will never run inline. It will instead be queued and run only after the current task has returned.
It doesn't own any thread. Tasks are run from caller's or caller-provided threads.
Conceptually, it is fairly accurate to think of SynchronizationContext
like a cheaper
Executors.newSingleThreadExecutor()
when used for synchronization (not long-running
tasks). Both use a queue for tasks that are run in order and neither guarantee that tasks have
completed before returning from execute()
. However, the behavior does diverge if locks
are held when calling the context. So it is encouraged to avoid mixing locks and synchronization
context except via executeLater(java.lang.Runnable)
.
This class is thread-safe.
- Since:
- 1.17.0
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final class
Allows the user to check the status and/or cancel a task scheduled byschedule(java.lang.Runnable, long, java.util.concurrent.TimeUnit, java.util.concurrent.ScheduledExecutorService)
. -
Constructor Summary
ConstructorsConstructorDescriptionSynchronizationContext
(Thread.UncaughtExceptionHandler uncaughtExceptionHandler) Creates a SynchronizationContext. -
Method Summary
Modifier and TypeMethodDescriptionfinal void
drain()
Run all tasks in the queue in the current thread, if no other thread is running this method.final void
Adds a task and run it in this synchronization context as soon as possible.final void
executeLater
(Runnable runnable) Adds a task that will be run whendrain()
is called.schedule
(Runnable task, long delay, TimeUnit unit, ScheduledExecutorService timerService) Schedules a task to be added and run viaexecute(java.lang.Runnable)
after a delay.schedule
(Runnable task, Duration delay, ScheduledExecutorService timerService) scheduleWithFixedDelay
(Runnable task, long initialDelay, long delay, TimeUnit unit, ScheduledExecutorService timerService) Schedules a task to be added and run viaexecute(java.lang.Runnable)
after an initial delay and then repeated after the delay until cancelled.scheduleWithFixedDelay
(Runnable task, Duration initialDelay, Duration delay, ScheduledExecutorService timerService) void
ThrowIllegalStateException
if this method is not called from this synchronization context.
-
Constructor Details
-
SynchronizationContext
Creates a SynchronizationContext.- Parameters:
uncaughtExceptionHandler
- handles exceptions thrown out of the tasks. Different from what's documented onThread.UncaughtExceptionHandler.uncaughtException(java.lang.Thread, java.lang.Throwable)
, the thread is not terminated when the handler is called.
-
-
Method Details
-
drain
public final void drain()Run all tasks in the queue in the current thread, if no other thread is running this method. Otherwise do nothing.Upon returning, it guarantees that all tasks submitted by
#executeLater
before it have been or will eventually be run, while not requiring any more calls todrain()
. -
executeLater
Adds a task that will be run whendrain()
is called.This is useful for cases where you want to enqueue a task while under a lock of your own, but don't want the tasks to be run under your lock (for fear of deadlock). You can call
executeLater(java.lang.Runnable)
in the lock, and calldrain()
outside the lock. -
execute
Adds a task and run it in this synchronization context as soon as possible. The task may run inline. If there are tasks that are previously queued byexecuteLater(java.lang.Runnable)
but have not been run, this method will trigger them to be run before the given task. This is equivalent to callingexecuteLater(java.lang.Runnable)
immediately followed bydrain()
. -
throwIfNotInThisSynchronizationContext
public void throwIfNotInThisSynchronizationContext()ThrowIllegalStateException
if this method is not called from this synchronization context. -
schedule
public final SynchronizationContext.ScheduledHandle schedule(Runnable task, long delay, TimeUnit unit, ScheduledExecutorService timerService) Schedules a task to be added and run viaexecute(java.lang.Runnable)
after a delay.- Parameters:
task
- the task being scheduleddelay
- the delayunit
- the time unit for the delaytimerService
- theScheduledExecutorService
that provides delayed execution- Returns:
- an object for checking the status and/or cancel the scheduled task
-
schedule
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/11657") public final SynchronizationContext.ScheduledHandle schedule(Runnable task, Duration delay, ScheduledExecutorService timerService) -
scheduleWithFixedDelay
public final SynchronizationContext.ScheduledHandle scheduleWithFixedDelay(Runnable task, long initialDelay, long delay, TimeUnit unit, ScheduledExecutorService timerService) Schedules a task to be added and run viaexecute(java.lang.Runnable)
after an initial delay and then repeated after the delay until cancelled.- Parameters:
task
- the task being scheduledinitialDelay
- the delay before the first rundelay
- the delay after the first run.unit
- the time unit for the delaytimerService
- theScheduledExecutorService
that provides delayed execution- Returns:
- an object for checking the status and/or cancel the scheduled task
-
scheduleWithFixedDelay
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/11657") public final SynchronizationContext.ScheduledHandle scheduleWithFixedDelay(Runnable task, Duration initialDelay, Duration delay, ScheduledExecutorService timerService)
-