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