io.grpc

Class SynchronizationContext

java.lang.Object

io.grpc.SynchronizationContext

All Implemented Interfaces:

Executor

@ThreadSafe
 @ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/4984")
public final class SynchronizationContext
extends Object
implements Executor

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(java.lang.Runnable) and executeLater(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 Classes

Modifier and Type	Class and Description
static class	SynchronizationContext.ScheduledHandle Allows the user to check the status and/or cancel a task scheduled by schedule(java.lang.Runnable, long, java.util.concurrent.TimeUnit, java.util.concurrent.ScheduledExecutorService).

Constructor Summary

Constructors

Constructor and Description
SynchronizationContext(Thread.UncaughtExceptionHandler uncaughtExceptionHandler) Creates a SynchronizationContext.

Method Summary

Modifier and Type	Method and Description
void	drain() Run all tasks in the queue in the current thread, if no other thread is running this method.
void	execute(Runnable task) Adds a task and run it in this synchronization context as soon as possible.
void	executeLater(Runnable runnable) Adds a task that will be run when drain() is called.
SynchronizationContext.ScheduledHandle	schedule(Runnable task, long delay, TimeUnit unit, ScheduledExecutorService timerService) Schedules a task to be added and run via execute(java.lang.Runnable) after a delay.
void	throwIfNotInThisSynchronizationContext() Throw IllegalStateException if this method is not called from this synchronization context.

Methods inherited from class java.lang.Object

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

Constructor Detail

SynchronizationContext

public SynchronizationContext(Thread.UncaughtExceptionHandler uncaughtExceptionHandler)

Creates a SynchronizationContext.

Parameters:

uncaughtExceptionHandler - handles exceptions thrown out of the tasks. Different from what's documented on Thread.UncaughtExceptionHandler.uncaughtException(java.lang.Thread, java.lang.Throwable), the thread is not terminated when the handler is called.

Method Detail

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().

executeLater

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(java.lang.Runnable) in the lock, and call drain() outside the lock.

execute

public final void execute(Runnable task)

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

Specified by:

execute in interface Executor

throwIfNotInThisSynchronizationContext

public void throwIfNotInThisSynchronizationContext()

Throw IllegalStateException 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 via execute(java.lang.Runnable) after a delay.

Parameters:

task - the task being scheduled

delay - the delay

unit - the time unit for the delay

timerService - the ScheduledExecutorService that provides delayed execution

Returns:

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