com.oracle.common.base

Class SingleWaiterCooperativeNotifier

java.lang.Object

com.oracle.common.base.SingleWaiterMultiNotifier

com.oracle.common.base.SingleWaiterCooperativeNotifier

All Implemented Interfaces:

Notifier

public class SingleWaiterCooperativeNotifier
extends SingleWaiterMultiNotifier

SingleWaiterCooperativeNotifier is an extension of the SingleWaiterMultiNotifier which attempts to offload potentially expensive "notification" work from signaling threads onto the waiting threads. This notifier is beneficial when there are few signaling threads, but potentially many waiting threads, each waiting on their own notifier.

Unlike the standard Notifier usage, a signaling thread must at some point invoke the static flush() method, or await(long) on any SingleWaiterCooperativeNotifier to ensure that all deferred signals are processed.

Author:

mf 2014.03.12

Field Summary

Fields

Modifier and Type	Field and Description
protected Thread	m_threadAwait The waiting thread, or null.
protected static byte	s_cSignal An intentionally non-volatile signal counter to ensure periodic flushes.

Fields inherited from class com.oracle.common.base.SingleWaiterMultiNotifier

m_oState

Constructor Summary

Constructors

Constructor and Description
SingleWaiterCooperativeNotifier()

Method Summary

Modifier and Type	Method and Description
void	await(long cMillis) Wait for a notification (which may have already occurred).
protected void	consumeSignal() Consume the signal.
static void	flush() Ensure that any deferred signals will be processed.
protected static void	flush(int cWake, SingleWaiterCooperativeNotifier self) Ensure that any deferred signals will be processed.
void	signal() Notifies the waiting thread(s), waking them up if awaiting, or preventing the next thread from going to sleep on the next await attempt.
String	toString()

Methods inherited from class com.oracle.common.base.SingleWaiterMultiNotifier

await, getWaitingThread, signalInternal

Methods inherited from class java.lang.Object

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

Field Detail

m_threadAwait

protected Thread m_threadAwait

The waiting thread, or null. Visibility ensured via super.m_oState writes.

s_cSignal

protected static byte s_cSignal

An intentionally non-volatile signal counter to ensure periodic flushes. byte is used to allow for auto-flush on every 256 signals (rollover)

Constructor Detail

SingleWaiterCooperativeNotifier

public SingleWaiterCooperativeNotifier()

Method Detail

flush

public static void flush()

Ensure that any deferred signals will be processed.

Note it is more advantageous if the calling thread's natural idle point is to sit in await(long), in which case calling this method is not required.

await

public void await(long cMillis)
           throws InterruptedException

Description copied from interface: Notifier

Wait for a notification (which may have already occurred). Note that spurious wake-ups are possible.

Specified by:

await in interface Notifier

Overrides:

await in class SingleWaiterMultiNotifier

Parameters:

cMillis - the maximum wait time in milliseconds, or zero for indefinite

Throws:

InterruptedException - if the calling thread is interrupted while it is waiting

signal

public void signal()

Description copied from interface: Notifier

Notifies the waiting thread(s), waking them up if awaiting, or preventing the next thread from going to sleep on the next await attempt.

Specified by:

signal in interface Notifier

Overrides:

signal in class SingleWaiterMultiNotifier

toString

public String toString()

Overrides:

toString in class SingleWaiterMultiNotifier

flush

protected static void flush(int cWake,
                            SingleWaiterCooperativeNotifier self)

Ensure that any deferred signals will be processed.

Parameters:

cWake - the number of deferrals to signal on the calling thread

self - the waiting notifier which is flushing, or null

consumeSignal

protected void consumeSignal()

Description copied from class: SingleWaiterMultiNotifier

Consume the signal.

Overrides:

consumeSignal in class SingleWaiterMultiNotifier