A synchronization context is a queue of tasks that run in sequence. It offers following guarantees:

Ordering. Tasks are run in the same order as they are submitted via execute and executeLater.
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.

This class is thread-safe.

Nested and Inner Type Summary

Modifier and Type	Class and Description
private static class	SynchronizationContext.ManagedRunnable
public static class	SynchronizationContext.ScheduledHandle Allows the user to check the status and/or cancel a task scheduled by `schedule`.

Modifier and Type	Field and Description
private final AtomicReference<Thread>	drainingThread
private final Queue<Runnable>	queue
private final Thread.UncaughtExceptionHandler	uncaughtExceptionHandler

Constructor Summary

Access	Constructor and Description
public	SynchronizationContext(Thread.UncaughtExceptionHandler handles exceptions thrown out of the tasks. Different from what's documented on `UncaughtExceptionHandler#uncaughtException`, the thread is not terminated when the handler is called. uncaughtExceptionHandler) Creates a SynchronizationContext.

Method Summary

Modifier and Type	Method and Description
public final void	drain() Run all tasks in the queue in the current thread, if no other thread is running this method.
public final void	execute(Runnable the runnable task task) Implements java.util.concurrent.Executor.execute. Adds a task and run it in this synchronization context as soon as possible.
public final void	executeLater(Runnable runnable) Adds a task that will be run when `drain` is called.
public final SynchronizationContext.ScheduledHandle	Returns: an object for checking the status and/or cancel the scheduled task schedule(final Runnable the task being scheduled task, long the delay delay, TimeUnit the time unit for the delay unit, ScheduledExecutorService the `ScheduledExecutorService` that provides delayed execution timerService) Schedules a task to be added and run via `execute` after a delay.
public final SynchronizationContext.ScheduledHandle	Returns: an object for checking the status and/or cancel the scheduled task scheduleWithFixedDelay(final Runnable the task being scheduled task, long the delay before the first run initialDelay, long the delay after the first run. delay, TimeUnit the time unit for the delay unit, ScheduledExecutorService the `ScheduledExecutorService` that provides delayed execution timerService) Schedules a task to be added and run via `execute` after an inital delay and then repeated after the delay until cancelled.
public void	throwIfNotInThisSynchronizationContext() Throw `IllegalStateException` if this method is not called from this synchronization context.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

drainingThread	back to summary
private final AtomicReference<Thread> drainingThread

queue	back to summary
private final Queue<Runnable> queue

uncaughtExceptionHandler	back to summary
private final Thread.UncaughtExceptionHandler uncaughtExceptionHandler

Constructor Detail

SynchronizationContext back to summary

SynchronizationContext	back to summary
public SynchronizationContext(Thread.UncaughtExceptionHandler uncaughtExceptionHandler) Creates a SynchronizationContext. Parameters uncaughtExceptionHandler:Thread.UncaughtExceptionHandler handles exceptions thrown out of the tasks. Different from what's documented on `UncaughtExceptionHandler#uncaughtException`, the thread is not terminated when the handler is called.

public SynchronizationContext(Thread.UncaughtExceptionHandler uncaughtExceptionHandler)

Creates a SynchronizationContext.

Parameters

uncaughtExceptionHandler:Thread.UncaughtExceptionHandler: handles exceptions thrown out of the tasks. Different from what's documented on UncaughtExceptionHandler#uncaughtException, the thread is not terminated when the handler is called.

Method Detail

drain back to summary

drain	back to summary
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 to `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 to drain().

execute back to summary

execute	back to summary
public final void execute(Runnable task) Implements java.util.concurrent.Executor.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 by `executeLater` but have not been run, this method will trigger them to be run before the given task. This is equivalent to calling `executeLater` immediately followed by `drain`. Parameters task:Runnable Doc from java.util.concurrent.Executor.execute. the runnable task Annotations @Override

public final void execute(Runnable task)

Implements java.util.concurrent.Executor.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 by executeLater but have not been run, this method will trigger them to be run before the given task. This is equivalent to calling executeLater immediately followed by drain.

Parameters

task:Runnable

Doc from java.util.concurrent.Executor.execute.

the runnable task

Annotations

@Override

executeLater back to summary

executeLater	back to summary
public final void executeLater(Runnable runnable) Adds a task that will be run when `drain` 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` in the lock, and call `drain` outside the lock.

public final void executeLater(Runnable runnable)

Adds a task that will be run when drain 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 in the lock, and call drain outside the lock.

schedule back to summary

schedule	back to summary
public final SynchronizationContext.ScheduledHandle schedule(final Runnable task, long delay, TimeUnit unit, ScheduledExecutorService timerService) Schedules a task to be added and run via `execute` after a delay. Parameters task:Runnable the task being scheduled delay:long the delay unit:TimeUnit the time unit for the delay timerService:ScheduledExecutorService the `ScheduledExecutorService` that provides delayed execution Returns:SynchronizationContext.ScheduledHandle an object for checking the status and/or cancel the scheduled task

public final SynchronizationContext.ScheduledHandle schedule(final Runnable task, long delay, TimeUnit unit, ScheduledExecutorService timerService)

Schedules a task to be added and run via execute after a delay.

Parameters

task:Runnable: the task being scheduled
delay:long: the delay
unit:TimeUnit: the time unit for the delay
timerService:ScheduledExecutorService: the ScheduledExecutorService that provides delayed execution

Returns:SynchronizationContext.ScheduledHandle

an object for checking the status and/or cancel the scheduled task

scheduleWithFixedDelay back to summary

scheduleWithFixedDelay	back to summary
public final SynchronizationContext.ScheduledHandle scheduleWithFixedDelay(final Runnable task, long initialDelay, long delay, TimeUnit unit, ScheduledExecutorService timerService) Schedules a task to be added and run via `execute` after an inital delay and then repeated after the delay until cancelled. Parameters task:Runnable the task being scheduled initialDelay:long the delay before the first run delay:long the delay after the first run. unit:TimeUnit the time unit for the delay timerService:ScheduledExecutorService the `ScheduledExecutorService` that provides delayed execution Returns:SynchronizationContext.ScheduledHandle an object for checking the status and/or cancel the scheduled task

public final SynchronizationContext.ScheduledHandle scheduleWithFixedDelay(final Runnable task, long initialDelay, long delay, TimeUnit unit, ScheduledExecutorService timerService)

Schedules a task to be added and run via execute after an inital delay and then repeated after the delay until cancelled.

Parameters

task:Runnable: the task being scheduled
initialDelay:long: the delay before the first run
delay:long: the delay after the first run.
unit:TimeUnit: the time unit for the delay
timerService:ScheduledExecutorService: the ScheduledExecutorService that provides delayed execution

Returns:SynchronizationContext.ScheduledHandle

an object for checking the status and/or cancel the scheduled task

throwIfNotInThisSynchronizationContext	back to summary
public void throwIfNotInThisSynchronizationContext() Throw `IllegalStateException` if this method is not called from this synchronization context.

io.grpc back to summary

private Class SynchronizationContext.ManagedRunnable

Class Inheritance

extends Object
implements Runnable

java.lang.Object
io.grpc.SynchronizationContext.ManagedRunnable

All Implemented Interfaces

java.lang.Runnable

Field Summary

Modifier and Type	Field and Description
pack-priv boolean	hasStarted
pack-priv boolean	isCancelled
pack-priv final Runnable	task

Constructor Summary

Access	Constructor and Description
pack-priv	ManagedRunnable(Runnable task)

Method Summary

Modifier and Type	Method and Description
public void	run() Implements java.lang.Runnable.run. Runs this operation.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

hasStarted	back to summary
pack-priv boolean hasStarted

isCancelled	back to summary
pack-priv boolean isCancelled

task	back to summary
pack-priv final Runnable task

Constructor Detail

ManagedRunnable	back to summary
pack-priv ManagedRunnable(Runnable task)

Method Detail

run	back to summary
public void run() Implements java.lang.Runnable.run. Doc from java.lang.Runnable.run. Runs this operation. Annotations @Override

run

back to summary

public void run()

Implements java.lang.Runnable.run.

Doc from java.lang.Runnable.run.

Runs this operation.

Annotations

@Override

io.grpc back to summary

public final Class SynchronizationContext.ScheduledHandle

Class Inheritance

extends Object

java.lang.Object
io.grpc.SynchronizationContext.ScheduledHandle

Allows the user to check the status and/or cancel a task scheduled by schedule.

This class is NOT thread-safe. All methods must be run from the same SynchronizationContext as which the task was scheduled in.

Field Summary

Modifier and Type	Field and Description
private final ScheduledFuture<?>	future
private final SynchronizationContext.ManagedRunnable	runnable

Constructor Summary

Access	Constructor and Description
private	ScheduledHandle(SynchronizationContext.ManagedRunnable runnable, ScheduledFuture<?> future)

Method Summary

Modifier and Type	Method and Description
public void	cancel() Cancel the task if it's still `pending`.
public boolean	isPending() Returns `true` if the task will eventually run, meaning that it has neither started running nor been cancelled.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

future	back to summary
private final ScheduledFuture<?> future

runnable	back to summary
private final SynchronizationContext.ManagedRunnable runnable

Constructor Detail

ScheduledHandle	back to summary
private ScheduledHandle(SynchronizationContext.ManagedRunnable runnable, ScheduledFuture<?> future)

Method Detail

cancel	back to summary
public void cancel() Cancel the task if it's still `pending`.

isPending	back to summary
public boolean isPending() Returns `true` if the task will eventually run, meaning that it has neither started running nor been cancelled.