pu.pi

Interface ParIterator<E>

Type Parameters:

E - The type of the elements returned from the Parallel Iterator.

All Superinterfaces:

java.util.Iterator<E>

All Known Implementing Classes:

DFSonDAGBottomTop, DFSonDAGs, DFSWorkStealing, DynamicParIterator, GuidedParIterator, MemoryAwareParIterator, ParIteratorAbstract, StaticParIterator

public interface ParIterator<E>
extends java.util.Iterator<E>

A Parallel Iterator over a collection. Unlike the standard sequential java.util.Iterator, the Parallel Iterator is thread-safe and allows multiple threads to traverse it.

A Parallel Iterator instance is created using ParIteratorFactory.

Author:

Nasser Giacaman, Oliver Sinnen, Lama Akeila

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	ParIterator.Schedule Enum representing the possible schedules that a Parallel Iterator may have.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_CHUNKSIZE The default chunk size, depending on the scheduling policy.

Method Summary

Modifier and Type	Method and Description
ParIteratorException<E>[]	getAllExceptions() Returns all the exceptions that have (so far) occurred during traversal of the Parallel Iterator.
int	getID() For test.
void	globalBreak() Causes all threads to stop processing elements at the next iteration boundary.
boolean	hasNext() Checks to see if any elements remain for the current thread.
boolean	localBreak() Attempts to excuse the current thread from continuing to iterate (and re-distribute all unprocessed elements to the other threads).
E	next() Returns an element for the current thread to process.
void	register(java.lang.Exception e) When a thread encounters an exception during traversal of a Parallel Iterator, the exception is registered using this method.
void	remove() Removes from the underlying collection the last element returned by the Parallel Iterator to the current thread.
void	reset() Reset ParIterator for reuse.

Methods inherited from interface java.util.Iterator

forEachRemaining

Field Detail

DEFAULT_CHUNKSIZE

static final int DEFAULT_CHUNKSIZE

The default chunk size, depending on the scheduling policy.

See Also:

Constant Field Values

Method Detail

hasNext

boolean hasNext()

Checks to see if any elements remain for the current thread. If such an element exists, true is returned and the current thread must follow up with a binding call to next(). A thread must continue to obtain elements in this fashion until this method returns false.

Note that this method involves an implicit barrier for the last call to hasNext() in order to ensure all threads finish at the same time.

Specified by:

hasNext in interface java.util.Iterator<E>

Returns:

true if at least one element has been reserved for the calling thread (in which case it must follow up with a call to next()).
false otherwise (in such a case, the calling thread blocks until all the other threads have completed their iterations).

See Also:

next()

next

E next()

Returns an element for the current thread to process. A thread must not call this method unless it has previously called hasNext() (and received true).

Note that calls to hasNext() (that return true) only allow for one corresponding and binding call to hasNext(). Therefore, multiple calls to hasNext() have no effect until the corresponding call to next() takes place.

Specified by:

next in interface java.util.Iterator<E>

Throws:

java.lang.RuntimeException - If this method has been called without a binding call to hasNext() that returned true.

See Also:

hasNext()

globalBreak

void globalBreak()

Causes all threads to stop processing elements at the next iteration boundary. Therefore, even if there were any unprocessed elements, they will not be processed. In such a case, false is returned to every thread at the next call to hasNext(). Therefore, all the threads safely stop iterating when they call hasNext() (includes an implicit barrier to ensure all threads stop at the same time).

See Also:

localBreak()

localBreak

boolean localBreak()

Attempts to excuse the current thread from continuing to iterate (and re-distribute all unprocessed elements to the other threads). This is only successful if the the elements previously assigned to this thread are successfully allocated to the other thread(s). If the elements cannot be assigned to another thread (because the other threads have already stopped processing), then this attempt to local break will fail.

Therefore, (as opposed to globalBreak()) this method guarantees that even if all threads attempt to localBreak(), at least one will fail and is left to traverse the remaining elements. Note that in many cases, calling localBreak() will break the original scheduling policy.

Returns:

true if the attempt is successful, false otherwise.

See Also:

globalBreak()

register

void register(java.lang.Exception e)

When a thread encounters an exception during traversal of a Parallel Iterator, the exception is registered using this method. Therefore, calling this method records the following information (wrapped inside a ParIteratorException):

• e - The exception that occurred
• The current thread (who encountered the exception)
• The current element that the thread was processing (the hasNext() method serves as the iteration boundary to determine the current element).

Parameters:

e - The exception to register

See Also:

getAllExceptions()

getAllExceptions

ParIteratorException<E>[] getAllExceptions()

Returns all the exceptions that have (so far) occurred during traversal of the Parallel Iterator. All exceptions must be caught and then registered by the thread that caught the exception.

Returns:

All the exceptions (each is wrapped inside a ParIteratorException), or an empty array if none were registered.

See Also:

register(Exception)

remove

void remove()

Removes from the underlying collection the last element returned by the Parallel Iterator to the current thread.

Specified by:

remove in interface java.util.Iterator<E>

Throws:

java.lang.UnsupportedOperationException - If the Parallel Iterator does not support this.

reset

void reset()

Reset ParIterator for reuse.

getID

int getID()

For test.

Returns:

thread ID.