reactor.util.concurrent

Class WaitStrategy

java.lang.Object

reactor.util.concurrent.WaitStrategy

public abstract class WaitStrategy
extends Object

Strategy employed to wait for specific LongSupplier values with various spinning strategies.

Field Summary

Fields

Modifier and Type	Field and Description
static Runnable	NOOP_SPIN_OBSERVER A no-op Runnable that can be used as a placeholder spin observer with waitFor(long, LongSupplier, Runnable)

Constructor Summary

Constructors

Constructor and Description
WaitStrategy()

Method Summary

Modifier and Type	Method and Description
static void	alert() Throw an Alert signal exception (singleton) that can be checked against isAlert(Throwable)
static WaitStrategy	blocking() Blocking strategy that uses a lock and condition variable for consumer waiting on a barrier.
static WaitStrategy	busySpin() Busy Spin strategy that uses a busy spin loop for consumers waiting on a barrier.
static boolean	isAlert(Throwable t) Test if exception is alert
static WaitStrategy	liteBlocking() Variation of the blocking() that attempts to elide conditional wake-ups when the lock is uncontended.
static WaitStrategy	parking() Parking strategy that initially spins, then uses a Thread.yield(), and eventually sleep (LockSupport.parkNanos(1)) for the minimum number of nanos the OS and JVM will allow while the consumers are waiting on a barrier.
static WaitStrategy	parking(int retries) Parking strategy that initially spins, then uses a Thread.yield(), and eventually sleep (LockSupport.parkNanos(1)) for the minimum number of nanos the OS and JVM will allow while the consumers are waiting on a barrier.
static WaitStrategy	phasedOff(long spinTimeout, long yieldTimeout, TimeUnit units, WaitStrategy delegate) Phased wait strategy for waiting consumers on a barrier.
static WaitStrategy	phasedOffLiteLock(long spinTimeout, long yieldTimeout, TimeUnit units) Block with wait/notifyAll semantics
static WaitStrategy	phasedOffLock(long spinTimeout, long yieldTimeout, TimeUnit units) Block with wait/notifyAll semantics
static WaitStrategy	phasedOffSleep(long spinTimeout, long yieldTimeout, TimeUnit units) Block by parking in a loop
void	signalAllWhenBlocking() Implementations should signal the waiting consumers that the cursor has advanced.
static WaitStrategy	sleeping() Yielding strategy that uses a Thread.sleep(1) for consumers waiting on a barrier after an initially spinning.
abstract long	waitFor(long sequence, LongSupplier cursor, Runnable spinObserver) Wait for the given sequence to be available.
static WaitStrategy	yielding() Yielding strategy that uses a Thread.yield() for consumers waiting on a barrier after an initially spinning.

Methods inherited from class java.lang.Object

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

Field Detail

NOOP_SPIN_OBSERVER

public static final Runnable NOOP_SPIN_OBSERVER

A no-op Runnable that can be used as a placeholder spin observer with waitFor(long, LongSupplier, Runnable)

Constructor Detail

WaitStrategy

public WaitStrategy()

Method Detail

alert

public static void alert()

Throw an Alert signal exception (singleton) that can be checked against isAlert(Throwable)

blocking

public static WaitStrategy blocking()

Blocking strategy that uses a lock and condition variable for consumer waiting on a barrier. This strategy can be used when throughput and low-latency are not as important as CPU resource.

Returns:

the wait strategy

busySpin

public static WaitStrategy busySpin()

Busy Spin strategy that uses a busy spin loop for consumers waiting on a barrier. This strategy will use CPU resource to avoid syscalls which can introduce latency jitter. It is best used when threads can be bound to specific CPU cores.

Returns:

the wait strategy

isAlert

public static boolean isAlert(Throwable t)

Test if exception is alert

Parameters:

t - exception checked

Returns:

true if this is an alert signal

liteBlocking

public static WaitStrategy liteBlocking()

Variation of the blocking() that attempts to elide conditional wake-ups when the lock is uncontended. Shows performance improvements on microbenchmarks. However this wait strategy should be considered experimental as I have not full proved the correctness of the lock elision code.

Returns:

the wait strategy

parking

public static WaitStrategy parking()

Parking strategy that initially spins, then uses a Thread.yield(), and eventually sleep (LockSupport.parkNanos(1)) for the minimum number of nanos the OS and JVM will allow while the consumers are waiting on a barrier.

This strategy is a good compromise between performance and CPU resource. Latency spikes can occur after quiet periods.

Returns:

the wait strategy

parking

public static WaitStrategy parking(int retries)

Parking strategy that initially spins, then uses a Thread.yield(), and eventually sleep (LockSupport.parkNanos(1)) for the minimum number of nanos the OS and JVM will allow while the consumers are waiting on a barrier.

This strategy is a good compromise between performance and CPU resource. Latency spikes can occur after quiet periods.

Parameters:

retries - the spin cycle count before parking

Returns:

the wait strategy

phasedOff

public static WaitStrategy phasedOff(long spinTimeout,
                                     long yieldTimeout,
                                     TimeUnit units,
                                     WaitStrategy delegate)

Phased wait strategy for waiting consumers on a barrier.

This strategy can be used when throughput and low-latency are not as important as CPU resource. Spins, then yields, then waits using the configured fallback WaitStrategy.

Parameters:

spinTimeout - the spin timeout

yieldTimeout - the yield timeout

units - the time unit

delegate - the target wait strategy to fallback on

Returns:

the wait strategy

phasedOffLiteLock

public static WaitStrategy phasedOffLiteLock(long spinTimeout,
                                             long yieldTimeout,
                                             TimeUnit units)

Block with wait/notifyAll semantics

Parameters:

spinTimeout - the spin timeout

yieldTimeout - the yield timeout

units - the time unit

Returns:

the wait strategy

phasedOffLock

public static WaitStrategy phasedOffLock(long spinTimeout,
                                         long yieldTimeout,
                                         TimeUnit units)

Block with wait/notifyAll semantics

Parameters:

spinTimeout - the spin timeout

yieldTimeout - the yield timeout

units - the time unit

Returns:

the wait strategy

phasedOffSleep

public static WaitStrategy phasedOffSleep(long spinTimeout,
                                          long yieldTimeout,
                                          TimeUnit units)

Block by parking in a loop

Parameters:

spinTimeout - the spin timeout

yieldTimeout - the yield timeout

units - the time unit

Returns:

the wait strategy

signalAllWhenBlocking

public void signalAllWhenBlocking()

Implementations should signal the waiting consumers that the cursor has advanced.

sleeping

public static WaitStrategy sleeping()

Yielding strategy that uses a Thread.sleep(1) for consumers waiting on a barrier after an initially spinning. This strategy will incur up a latency of 1ms and save a maximum CPU resources.

Returns:

the wait strategy

waitFor

public abstract long waitFor(long sequence,
                             LongSupplier cursor,
                             Runnable spinObserver)
                      throws InterruptedException

Wait for the given sequence to be available. It is possible for this method to return a value less than the sequence number supplied depending on the implementation of the WaitStrategy. A common use for this is to signal a timeout. Any EventProcessor that is using a WaitStrategy to get notifications about message becoming available should remember to handle this case.

Parameters:

sequence - to be waited on.

cursor - the main sequence from ringbuffer. Wait/notify strategies will need this as is notified upon update.

spinObserver - Spin observer

Returns:

the sequence that is available which may be greater than the requested sequence.

Throws:

InterruptedException - if the thread is interrupted.

yielding

public static WaitStrategy yielding()

Yielding strategy that uses a Thread.yield() for consumers waiting on a barrier after an initially spinning. This strategy is a good compromise between performance and CPU resource without incurring significant latency spikes.

Returns:

the wait strategy