Package com.github.mizool.core.concurrent

Class Synchronizer

java.lang.Object
com.github.mizool.core.concurrent.Synchronizer
All Implemented Interfaces:
SynchronizerApi.Fluent, SynchronizerApi.RunGet, SynchronizerApi.SleepRunGet
public final class Synchronizer extends Object implements SynchronizerApi.SleepRunGet
Encapsulates synchronization and wait/notify functionality.

Introduction

By calling any of the instance methods of Synchronizer, the calling code defines a chain of actions that is completed with invoke(). All those actions are performed in one synchronized block using a lock which is private to the Synchronizer instance.

With its fluent API and encapsulated lock, this class can help increasing both the readability and robustness of concurrent algorithms. Still, care must be taken to avoid deadlocks, just as if using synchronized blocks and Object.wait() / Object.notifyAll() directly.

Actions

Synchronizer provides the following actions:

  • Main action
  • Sleep until condition is true
    • Whenever the thread receives a wake call, it checks this condition. If true, the thread stops sleeping and continues its action chain. If false, it resumes sleeping.
    • By default, the condition will only be checked when a wake call happens. However, you can also specify the duration of an interval after which the thread should re-check the condition on its own and then stop/resume sleep as explained above.
    • Can be used before (sleepUntil) and/or after (thenSleepUntil) the main action.
    • Sleeping is implemented in line with secure coding practices, i.e. Object.wait() is called inside a loop to ensure liveness and safety (see SEI CERT rule THI03-J for details).
    • If the thread is interrupted while waiting, UncheckedInterruptedException is thrown and the thread's interrupted flag is re-set.

  • Wake other threads
    • Wakes each sleeping thread (by calling Object.notifyAll()), causing it to check its condition (see above).
    • If the main action of this chain is a Supplier<T>, the calling code can decide whether waking takes place by using andWakeOthersIf(Predicate<T>) instead.

Fluent API overview



Example usage

synchronizer.run(...)
     .thenSleepUntil(...)
     .invoke();

 synchronizer.sleepUntil(...)
     .run(...)
     .andWakeOthers()
     .invoke();

 ResultClass result = synchronizer.get(...)
     .invoke();

 Spline result = synchronizer.get(...)
     .andWakeOthersIf(Spline::isReticulated)
     .invoke();

Note on terminology

This class intentionally uses the verbs "sleep" and "wake". If it used "wait" and "notify" instead, its methods would all too easily be confused with methods in java.lang.Object which, if invoked on the objects returned by chained methods, could cause deadlocks.

  • Constructor Details

    • Synchronizer

      public Synchronizer()
      Creates a new Synchronizer instance.

  • Method Details

    • run

      public SynchronizerApi.Run.WakeSleepInvoke run(@NonNull @NonNull Runnable runnable)
      Description copied from interface: SynchronizerApi.RunGet
      Sets the given Runnable as the main action of the chain.
      Specified by:
      run in interface SynchronizerApi.RunGet
      Parameters:
      runnable - the action to perform

    • get

      public <T> SynchronizerApi.Get.WakeSleepInvoke<T> get(@NonNull @NonNull Supplier<T> getter)
      Description copied from interface: SynchronizerApi.RunGet
      Sets the given Supplier as the main action of the chain.
      Specified by:
      get in interface SynchronizerApi.RunGet
      Parameters:
      getter - the action to perform

    • sleepUntil

      public SynchronizerApi.RunGetInvoke sleepUntil(@NonNull @NonNull BooleanSupplier state, Duration checkInterval)
      Description copied from interface: SynchronizerApi.SleepRunGet
      Adds sleeping to the action chain.

      This action ensures the given condition is met before performing the next action. When this action begins, the supplier is called immediately.
      Supplier returns false:
      The chain sleeps until either another chain wakes it up or the checkInterval has passed.

      In both cases, the supplier is then called again and if it still returns false, the chain resumes sleeping.
      Supplier returns true:
      The chain proceeds to perform the next action.
      Specified by:
      sleepUntil in interface SynchronizerApi.SleepRunGet
      Parameters:
      state - the supplier that returns true if the action chain should continue, false otherwise.
      checkInterval - how often the condition should be re-checked even if no wake call happens, or null for "never".