Class WriterReaderPhaser
- java.lang.Object
-
- org.HdrHistogram.WriterReaderPhaser
-
public class WriterReaderPhaser extends java.lang.Object
WriterReaderPhaser
instances provide an asymmetric means for synchronizing the execution of wait-free "writer" critical sections against a "reader phase flip" that needs to make sure no writer critical sections that were active at the beginning of the flip are still active after the flip is done. Multiple writers and multiple readers are supported.While a
WriterReaderPhaser
can be useful in multiple scenarios, a specific and common use case is that of safely managing "double buffered" data stream access in which writers can proceed without being blocked, while readers gain access to stable and unchanging buffer samplesNOTE:
WriterReaderPhaser
writers are wait-free on architectures that support wait-free atomic increment operations. They remain lock-free (but not wait-free) on architectures that do not support wait-free atomic increment operations.WriterReaderPhaser
"writers" are wait free, "readers" block for other "readers", and "readers" are only blocked by "writers" whose critical section was entered before the reader'sflipPhase()
attempt.When used to protect an actively recording data structure, the assumptions on how readers and writers act are:
- There are two sets of data structures ("active" and "inactive")
- Writing is done to the perceived active version (as perceived by the writer), and only
within critical sections delineated by
writerCriticalSectionEnter()
andwriterCriticalSectionExit(long)
). - Only readers switch the perceived roles of the active and inactive data structures. They do so only while under readerLock(), and only before calling flipPhase().
WriterReaderPhaser
guarantees that the inactive data structures are not being modified by any writers while being read while under readerLock() protection after a flipPhase() operation.
-
-
Field Summary
Fields Modifier and Type Field Description private long
evenEndEpoch
private static java.util.concurrent.atomic.AtomicLongFieldUpdater<WriterReaderPhaser>
evenEndEpochUpdater
private long
oddEndEpoch
private static java.util.concurrent.atomic.AtomicLongFieldUpdater<WriterReaderPhaser>
oddEndEpochUpdater
private java.util.concurrent.locks.ReentrantLock
readerLock
private long
startEpoch
private static java.util.concurrent.atomic.AtomicLongFieldUpdater<WriterReaderPhaser>
startEpochUpdater
-
Constructor Summary
Constructors Constructor Description WriterReaderPhaser()
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
flipPhase()
Flip a phase in theWriterReaderPhaser
instance,flipPhase()
can only be called while holding the readerLock().void
flipPhase(long yieldTimeNsec)
Flip a phase in theWriterReaderPhaser
instance,flipPhase()
can only be called while holding the readerLock().void
readerLock()
Enter to a critical section containing a read operation (mutually excludes against otherreaderLock
calls).void
readerUnlock()
Exit from a critical section containing a read operation (relinquishes mutual exclusion against otherreaderLock
calls).long
writerCriticalSectionEnter()
Indicate entry to a critical section containing a write operation.void
writerCriticalSectionExit(long criticalValueAtEnter)
Indicate exit from a critical section containing a write operation.
-
-
-
Field Detail
-
startEpoch
private volatile long startEpoch
-
evenEndEpoch
private volatile long evenEndEpoch
-
oddEndEpoch
private volatile long oddEndEpoch
-
readerLock
private final java.util.concurrent.locks.ReentrantLock readerLock
-
startEpochUpdater
private static final java.util.concurrent.atomic.AtomicLongFieldUpdater<WriterReaderPhaser> startEpochUpdater
-
evenEndEpochUpdater
private static final java.util.concurrent.atomic.AtomicLongFieldUpdater<WriterReaderPhaser> evenEndEpochUpdater
-
oddEndEpochUpdater
private static final java.util.concurrent.atomic.AtomicLongFieldUpdater<WriterReaderPhaser> oddEndEpochUpdater
-
-
Method Detail
-
writerCriticalSectionEnter
public long writerCriticalSectionEnter()
Indicate entry to a critical section containing a write operation.This call is wait-free on architectures that support wait free atomic increment operations, and is lock-free on architectures that do not.
writerCriticalSectionEnter()
must be matched with a subsequentwriterCriticalSectionExit(long)
in order for CriticalSectionPhaser synchronization to function properly.- Returns:
- an (opaque) value associated with the critical section entry, which MUST be provided
to the matching
writerCriticalSectionExit(long)
call.
-
writerCriticalSectionExit
public void writerCriticalSectionExit(long criticalValueAtEnter)
Indicate exit from a critical section containing a write operation.This call is wait-free on architectures that support wait free atomic increment operations, and is lock-free on architectures that do not.
writerCriticalSectionExit(long)
must be matched with a precedingwriterCriticalSectionEnter()
call, and must be provided with the matchingwriterCriticalSectionEnter()
call's return value, in order for CriticalSectionPhaser synchronization to function properly.- Parameters:
criticalValueAtEnter
- the (opaque) value returned from the matchingwriterCriticalSectionEnter()
call.
-
readerLock
public void readerLock()
Enter to a critical section containing a read operation (mutually excludes against otherreaderLock
calls).readerLock
DOES NOT provide synchronization againstwriterCriticalSectionEnter()
calls. UseflipPhase()
to synchronize reads against writers.
-
readerUnlock
public void readerUnlock()
Exit from a critical section containing a read operation (relinquishes mutual exclusion against otherreaderLock
calls).
-
flipPhase
public void flipPhase(long yieldTimeNsec)
Flip a phase in theWriterReaderPhaser
instance,flipPhase()
can only be called while holding the readerLock().flipPhase()
will return only after all writer critical sections (protected bywriterCriticalSectionEnter()
()} andwriterCriticalSectionExit(long)
()}) that may have been in flight when theflipPhase()
call were made had completed.No actual writer critical section activity is required for
flipPhase()
to succeed.However,
flipPhase()
is lock-free with respect to calls towriterCriticalSectionEnter()
andwriterCriticalSectionExit(long)
. It may spin-wait for for active writer critical section code to complete.- Parameters:
yieldTimeNsec
- The amount of time (in nanoseconds) to sleep in each yield if yield loop is needed.
-
flipPhase
public void flipPhase()
Flip a phase in theWriterReaderPhaser
instance,flipPhase()
can only be called while holding the readerLock().flipPhase()
will return only after all writer critical sections (protected bywriterCriticalSectionEnter()
()} andwriterCriticalSectionExit(long)
()}) that may have been in flight when theflipPhase()
call were made had completed.No actual writer critical section activity is required for
flipPhase()
to succeed.However,
flipPhase()
is lock-free with respect to calls towriterCriticalSectionEnter()
andwriterCriticalSectionExit(long)
. It may spin-wait for for active writer critical section code to complete.
-
-