Package com.github.mizool.core.concurrent

Class 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 Detail

      • Synchronizer

        public Synchronizer()
        Creates a new Synchronizer instance.

    • Method Detail

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