Package io.grpc

Class SynchronizationContext

  • All Implemented Interfaces:
    Executor
    @ThreadSafe
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

    • 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.

      • throwIfNotInThisSynchronizationContext

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

      • scheduleWithFixedDelay

        public final SynchronizationContext.ScheduledHandle scheduleWithFixedDelay​(Runnable task,
                                                                           long initialDelay,
                                                                           long delay,
                                                                           TimeUnit unit,
                                                                           ScheduledExecutorService timerService)
        Schedules a task to be added and run via execute(java.lang.Runnable) after an initial 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