Interface ConcurrentIterator

All Superinterfaces:

java.util.Iterator

All Known Implementing Classes:

ConcurrentList.ListItr

public interface ConcurrentIterator

extends java.util.Iterator

Interface to iterate over a concurrent list. The class extends the Iterator interface, because the implementation of the concurrent list provides access to the items (containers) of the list as well. Further, an iteration over a concurrent list needs to maintain certain information at each item, which makes an explicit finishing of an iteration necessary (avoids that a threads is delayed until the garbage collector finalizes iterators which are not used any more, but which still block an item.

Version:

0.1, 05/19/03

Author:

Arno Formella and José B. González López

See Also:

Iterator

Method Summary

void	finish() Finishes an iteration.
ConcurrentItem	nextItem() Returns the next item in the list.
ConcurrentItem	nextItem(ConcurrentItem item) Returns the next item and element in the list.
void	removeCurrent() Removes the item currently held by the iterator.

Methods inherited from interface java.util.Iterator

hasNext, next, remove

Method Detail

nextItem

public ConcurrentItem nextItem()

Returns the next item in the list.

Returns:

the next item in the list, or null if there are no more items.

nextItem

public ConcurrentItem nextItem(ConcurrentItem item)

Returns the next item and element in the list. Allows for an atomic access to an item of the list. If one uses the separate forms of first accessing the item then accessing the element, another thread might have changed the element of the item in the mean while.

Parameters:

item - the item where to place the corresponding element, item will be unchanged if there are no more elements.

Returns:

the next item in the list, or null if there are no more elements.

removeCurrent

public void removeCurrent()
                   throws java.lang.InterruptedException

Removes the item currently held by the iterator. The iterator is placed to the previous item. The method can be called several times without calling a next()-method as long as the iterator does not recover its initial state, that is, being placed as after construction.

Throws:

java.util.NoSuchElementException - if there is no current item, i.e., if still none of the next()-methods has been executed or if the iteration already has completed.

java.lang.InterruptedException - if the thread is interrupted while waiting for iterators releasing the current item.

finish

public void finish()

Finishes an iteration. Because an iteration over a ConcurrentList needs to maintain some state information, one should call this method whenever an iterator is not used any more. Once finish() has been called, the state of the iteration is the same as if one had iterated to the end of the list. If this advice is not followed, other threads might get blocked until the garbage collector finalizes the iterator.