org.modeshape.common.collection.ring

## Class SingleProducerCursor

- java.lang.Object
- - org.modeshape.common.collection.ring.SingleProducerCursor

- All Implemented Interfaces:
    Cursor, DependentOnPointers

      public class SingleProducerCursor
      extends Object
      implements Cursor

  A single-threaded cursor for a ring buffer that ensures it does not pass the slowest `Pointer` that is consuming entries. If the cursor needs to advance but cannot due to a slow `Pointer`, then the supplied `strategy` will be used. As new positions are `published`, the supplied `WaitStrategy` (used by consumers waiting for this cursor to advance) will be `signalled`.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected Pointer` | `current`
    `protected long` | `finalPosition`
    `protected Pointer[]` | `stayBehinds`
    `protected WaitStrategy` | `waitStrategy`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SingleProducerCursor(int bufferSize, WaitStrategy waitStrategy)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `long` | `claim()` Claim the next position for writing and publishing.
    `long` | `claim(int number)` Claim a batch of positions for writing and publishing.
    `protected long` | `claimUpTo(int number)` Claim up to the supplied number of positions.
    `void` | `complete()` Signal that no more entries will be written and that the `barriers` will not block on this cursor and should return a negative number from `PointerBarrier.waitFor(long)`.
    `GarbageCollectingConsumer` | `createGarbageCollectingConsumer(GarbageCollectingConsumer.Collectable collectable)`
    `int` | `getBufferSize()` Get the size of the buffer that this cursor operates against.
    `long` | `getCurrent()` Get the current position that can be read.
    `long` | `getHighestPublishedPosition(long lowerPosition, long upperPosition)` Get the highest published position that is equal to or between the supplied lower and upper positions.
    `boolean` | `ignore(Pointer pointer)` Ignore the specified pointer that cursor had previously `stayed behind`.
    `boolean` | `isComplete()` Return whether this cursor has `completed` normally.
    `PointerBarrier` | `newBarrier()` Add a new barrier that a consumer can use the wait for the next available positions.
    `Pointer` | `newPointer()` Return a new pointer that starts at this cursor's current position, ensuring that this cursor always `stays behind` it on the ring buffer.
    `protected long` | `positionOfSlowestPointer(long minimumPosition)`
    `boolean` | `publish(long position)` Publish the supplied position, making it available for consumers.
    `void` | `signalConsumers()` Signal that the consumers should wake up if they are blocked on the barrier.
    `void` | `stayBehind(Pointer... pointers)` Ensure that this cursor always remains behind the specified pointer.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### current

          protected final Pointer current

    - #### waitStrategy

          protected final WaitStrategy waitStrategy

    - #### finalPosition

          protected volatile long finalPosition

    - #### stayBehinds

          protected volatile Pointer[] stayBehinds

  - ### Constructor Detail

    - #### SingleProducerCursor

          public SingleProducerCursor(int bufferSize,
                              WaitStrategy waitStrategy)

  - ### Method Detail

    - #### getCurrent

          public long getCurrent()

      Description copied from interface: `Cursor`
      Get the current position that can be read.
      Specified by:
        `getCurrent` in interface `Cursor`
      Returns:
        the position for entries that have been published.

    - #### getBufferSize

          public int getBufferSize()

      Description copied from interface: `Cursor`
      Get the size of the buffer that this cursor operates against.
      Specified by:
        `getBufferSize` in interface `Cursor`
      Returns:
        the size of the ring buffer; always positive and a power of 2

    - #### claim

          public long claim()

      Description copied from interface: `Cursor`
      Claim the next position for writing and publishing. This method blocks until the next position is available.
      Specified by:
        `claim` in interface `Cursor`
      Returns:
        the position that is available for publishing

    - #### claim

          public long claim(int number)

      Description copied from interface: `Cursor`
      Claim a batch of positions for writing and publishing. This method blocks until all desired positions are available.
      Specified by:
        `claim` in interface `Cursor`
      Parameters:
        `number` - the number of positions to be claimed; must be greater than 0
      Returns:
        the largest position that is available for publishing

    - #### claimUpTo

          protected long claimUpTo(int number)

      Claim up to the supplied number of positions.
      Parameters:
        `number` - the maximum number of positions to claim for writing; must be positive
      Returns:
        the highest position that were claimed

    - #### positionOfSlowestPointer

          protected long positionOfSlowestPointer(long minimumPosition)

    - #### publish

          public boolean publish(long position)

      Description copied from interface: `Cursor`
      Publish the supplied position, making it available for consumers.
      Specified by:
        `publish` in interface `Cursor`
      Parameters:
        `position` - the position that is now available for consumers
      Returns:
        true if the position was published, or false if not

    - #### getHighestPublishedPosition

          public long getHighestPublishedPosition(long lowerPosition,
                                         long upperPosition)

      Description copied from interface: `Cursor`
      Get the highest published position that is equal to or between the supplied lower and upper positions.
      Specified by:
        `getHighestPublishedPosition` in interface `Cursor`
      Parameters:
        `lowerPosition` - the lowest potential position
        `upperPosition` - the highest potential position
      Returns:
        the highest available position

    - #### newBarrier

          public PointerBarrier newBarrier()

      Description copied from interface: `Cursor`
      Add a new barrier that a consumer can use the wait for the next available positions.
      Specified by:
        `newBarrier` in interface `Cursor`
      Returns:
        the new barrier; never null

    - #### signalConsumers

          public void signalConsumers()

      Description copied from interface: `Cursor`
      Signal that the consumers should wake up if they are blocked on the barrier.
      Specified by:
        `signalConsumers` in interface `Cursor`

    - #### complete

          public void complete()

      Description copied from interface: `Cursor`
      Signal that no more entries will be written and that the `barriers` will not block on this cursor and should return a negative number from `PointerBarrier.waitFor(long)`.
      Specified by:
        `complete` in interface `Cursor`

    - #### isComplete

          public boolean isComplete()

      Description copied from interface: `Cursor`
      Return whether this cursor has `completed` normally.
      Specified by:
        `isComplete` in interface `Cursor`
      Returns:
        true if this cursor is complete, or false otherwise

    - #### newPointer

          public Pointer newPointer()

      Description copied from interface: `Cursor`
      Return a new pointer that starts at this cursor's current position, ensuring that this cursor always `stays behind` it on the ring buffer.
      Specified by:
        `newPointer` in interface `Cursor`
      Returns:
        the new pointer

    - #### stayBehind

          public void stayBehind(Pointer... pointers)

      Description copied from interface: `DependentOnPointers`
      Ensure that this cursor always remains behind the specified pointer.
      Specified by:
        `stayBehind` in interface `DependentOnPointers`
      Parameters:
        `pointers` - the pointers that this cursor may not run past in the ring buffer

    - #### ignore

          public boolean ignore(Pointer pointer)

      Description copied from interface: `DependentOnPointers`
      Ignore the specified pointer that cursor had previously `stayed behind`. This should be called when the supplied pointer is removed from the ring buffer.
      Specified by:
        `ignore` in interface `DependentOnPointers`
      Parameters:
        `pointer` - the pointer that this cursor may no longer depend upon
      Returns:
        true if this cursor did depend on the supplied pointer and now no longer does, or false if this cursor never dependent upon the supplied pointer

    - #### createGarbageCollectingConsumer

          public GarbageCollectingConsumer createGarbageCollectingConsumer(GarbageCollectingConsumer.Collectable collectable)

      Specified by:
        `createGarbageCollectingConsumer` in interface `Cursor`

Copyright © 2008-2014 JBoss, a division of Red Hat. All Rights Reserved.