org.modeshape.common.collection.ring

## Interface Cursor

- All Superinterfaces:
    DependentOnPointers
  All Known Implementing Classes:
    SingleProducerCursor

      public interface Cursor
      extends DependentOnPointers

  A cursor in a ring buffer at which point information can be added to the buffer. A ring buffer uses its cursor to keep track of the `positions` of all consumers (to keep from overlapping them), and to ensure that entries are added to the buffer in the correct fashion using a two-phase process:
  1. `Claim` the next position for writing
  2. `Publish` that one or more positions has been successfully populated with entries and that the consumers are free to consume them

- - ### 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.
    `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` | `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.
    `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.

    - ### Methods inherited from interface org.modeshape.common.collection.ring.DependentOnPointers

      `ignore, stayBehind`

- - ### Method Detail

    - #### getBufferSize

          int getBufferSize()

      Get the size of the buffer that this cursor operates against.
      Returns:
        the size of the ring buffer; always positive and a power of 2

    - #### getCurrent

          long getCurrent()

      Get the current position that can be read.
      Returns:
        the position for entries that have been published.

    - #### claim

          long claim()

      Claim the next position for writing and publishing. This method blocks until the next position is available.
      Returns:
        the position that is available for publishing

    - #### claim

          long claim(int number)

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

    - #### publish

          boolean publish(long position)

      Publish the supplied position, making it available for consumers.
      Parameters:
        `position` - the position that is now available for consumers
      Returns:
        true if the position was published, or false if not

    - #### getHighestPublishedPosition

          long getHighestPublishedPosition(long lowerPosition,
                                         long upperPosition)

      Get the highest published position that is equal to or between the supplied lower and upper positions.
      Parameters:
        `lowerPosition` - the lowest potential position
        `upperPosition` - the highest potential position
      Returns:
        the highest available position

    - #### newBarrier

          PointerBarrier newBarrier()

      Add a new barrier that a consumer can use the wait for the next available positions.
      Returns:
        the new barrier; never null

    - #### newPointer

          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.
      Returns:
        the new pointer

    - #### signalConsumers

          void signalConsumers()

      Signal that the consumers should wake up if they are blocked on the barrier.

    - #### complete

          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)`.

    - #### isComplete

          boolean isComplete()

      Return whether this cursor has `completed` normally.
      Returns:
        true if this cursor is complete, or false otherwise

    - #### createGarbageCollectingConsumer

          GarbageCollectingConsumer createGarbageCollectingConsumer(GarbageCollectingConsumer.Collectable collectable)

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