Package io.grpc

Class SynchronizationContext

  • All Implemented Interfaces:
    java.util.concurrent.Executor
    @ThreadSafe
public final class SynchronizationContext
extends java.lang.Object
implements java.util.concurrent.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

    • Constructor Detail

      • SynchronizationContext

        public SynchronizationContext​(java.lang.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​(java.lang.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​(java.lang.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 java.util.concurrent.Executor

      • throwIfNotInThisSynchronizationContext

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

      • schedule

        public final SynchronizationContext.ScheduledHandle schedule​(java.lang.Runnable task,
                                                             long delay,
                                                             java.util.concurrent.TimeUnit unit,
                                                             java.util.concurrent.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

      • scheduleWithFixedDelay

        public final SynchronizationContext.ScheduledHandle scheduleWithFixedDelay​(java.lang.Runnable task,
                                                                           long initialDelay,
                                                                           long delay,
                                                                           java.util.concurrent.TimeUnit unit,
                                                                           java.util.concurrent.ScheduledExecutorService timerService)
        Schedules a task to be added and run via execute(java.lang.Runnable) after an inital delay and then repeated after the delay until cancelled.
        Parameters:
        task - the task being scheduled
        initialDelay - the delay before the first run
        delay - the delay after the first run.
        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