com.github.mizool.core.concurrent

Class Synchronizer

java.lang.Object

com.github.mizool.core.concurrent.Synchronizer

All Implemented Interfaces:

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
  • a Runnable (run) or Supplier (get)
    
  
  
• Sleep until condition is true
  • 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
• Using wakeOthers() is equivalent to calling Object.notifyAll(). If the main action 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();

Constructor Summary

Constructors

Constructor and Description
Synchronizer() Creates a new Synchronizer instance.

Method Summary

Modifier and Type	Method and Description
<T> SynchronizerApi.Get.WakeSleepInvoke<T>	get(@NonNull Supplier<T> getter) Sets the given Supplier as the main action of the chain.
SynchronizerApi.Run.WakeSleepInvoke	run(@NonNull Runnable runnable) Sets the given Runnable as the main action of the chain.
SynchronizerApi.RunGet	sleepUntil(@NonNull BooleanSupplier state) Adds sleeping to the action chain.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Synchronizer

public Synchronizer()

Creates a new Synchronizer instance.

Method Detail

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.RunGet sleepUntil(@NonNull
                                         @NonNull BooleanSupplier state)

Description copied from interface: SynchronizerApi.SleepRunGet

Adds sleeping to the action chain.

When performing this action, the chain will sleep until another chain wakes it up, then call the given supplier. If the supplier returns false, this action chain resumes sleeping. Otherwise, the chain continues by performing the main action.

Specified by:

sleepUntil in interface SynchronizerApi.SleepRunGet

Parameters:

state - the supplier that returns true if the action chain should continue, false otherwise.