Package io.grpc

Class SynchronizationContext

java.lang.Object
io.grpc.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
  • Field Details

  • Constructor Details

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