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

    NOTE: 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's flipPhase() attempt.

    When used to protect an actively recording data structure, the assumptions on how readers and writers act are:

    1. There are two sets of data structures ("active" and "inactive")
    2. Writing is done to the perceived active version (as perceived by the writer), and only within critical sections delineated by writerCriticalSectionEnter() and writerCriticalSectionExit(long)).
    3. 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().
    When the above assumptions are met, 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 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
    • Constructor Detail

      • WriterReaderPhaser

        public WriterReaderPhaser()