stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8022318: Document Spliterator characteristics and binding policy of java util concurrent collection impls

Browse Source 
Co-authored-by: Martin Buchholz <martinrb@google.com>
Reviewed-by: chegar
This commit is contained in:
Paul Sandoz 2013-08-06 14:26:34 +01:00
parent 63de7b9fd0
commit b42c6fb241
16 changed files with 348 additions and 175 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
jdk/src/share/classes/java/util/concurrent/ArrayBlockingQueue.java
View File

@ -757,12 +757,8 @@ public class ArrayBlockingQueue<E> extends AbstractQueue<E>
* Returns an iterator over the elements in this queue in proper sequence.
* The elements will be returned in order from first (head) to last (tail).
*
* <p>The returned iterator is a "weakly consistent" iterator that
* will never throw {@link java.util.ConcurrentModificationException
* ConcurrentModificationException}, and guarantees to traverse
* elements as they existed upon construction of the iterator, and
* may (but is not guaranteed to) reflect any modifications
* subsequent to construction.
* <p>The returned iterator is
* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
*
* @return an iterator over the elements in this queue in proper sequence
*/
@ -1396,9 +1392,26 @@ public class ArrayBlockingQueue<E> extends AbstractQueue<E>
// }
}
/**
* Returns a {@link Spliterator} over the elements in this queue.
*
* <p>The returned spliterator is
* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
*
* <p>The {@code Spliterator} reports {@link Spliterator#CONCURRENT},
* {@link Spliterator#ORDERED}, and {@link Spliterator#NONNULL}.
*
* @implNote
* The {@code Spliterator} implements {@code trySplit} to permit limited
* parallelism.
*
* @return a {@code Spliterator} over the elements in this queue
* @since 1.8
*/
public Spliterator<E> spliterator() {
return Spliterators.spliterator
(this, Spliterator.ORDERED | Spliterator.NONNULL |
Spliterator.CONCURRENT);
}
}

57
jdk/src/share/classes/java/util/concurrent/ConcurrentHashMap.java
View File

@ -43,7 +43,6 @@ import java.util.AbstractMap;
import java.util.Arrays;
import java.util.Collection;
import java.util.Comparator;
import java.util.ConcurrentModificationException;
import java.util.Enumeration;
import java.util.HashMap;
import java.util.Hashtable;
@ -94,14 +93,14 @@ import java.util.stream.Stream;
* that key reporting the updated value.) For aggregate operations
* such as {@code putAll} and {@code clear}, concurrent retrievals may
* reflect insertion or removal of only some entries. Similarly,
* Iterators and Enumerations return elements reflecting the state of
* the hash table at some point at or since the creation of the
* Iterators, Spliterators and Enumerations return elements reflecting the
* state of the hash table at some point at or since the creation of the
* iterator/enumeration. They do <em>not</em> throw {@link
* ConcurrentModificationException}. However, iterators are designed
* to be used by only one thread at a time. Bear in mind that the
* results of aggregate status methods including {@code size}, {@code
* isEmpty}, and {@code containsValue} are typically useful only when
* a map is not undergoing concurrent updates in other threads.
* java.util.ConcurrentModificationException ConcurrentModificationException}.
* However, iterators are designed to be used by only one thread at a time.
* Bear in mind that the results of aggregate status methods including
* {@code size}, {@code isEmpty}, and {@code containsValue} are typically
* useful only when a map is not undergoing concurrent updates in other threads.
* Otherwise the results of these methods reflect transient states
* that may be adequate for monitoring or estimation purposes, but not
* for program control.
@ -1200,11 +1199,11 @@ public class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
* operations. It does not support the {@code add} or
* {@code addAll} operations.
*
* <p>The view's {@code iterator} is a "weakly consistent" iterator
* that will never throw {@link ConcurrentModificationException},
* and guarantees to traverse elements as they existed upon
* construction of the iterator, and may (but is not guaranteed to)
* reflect any modifications subsequent to construction.
* <p>The view's iterators and spliterators are
* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
*
* <p>The view's {@code spliterator} reports {@link Spliterator#CONCURRENT},
* {@link Spliterator#DISTINCT}, and {@link Spliterator#NONNULL}.
*
* @return the set view
*/
@ -1223,11 +1222,11 @@ public class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
* {@code retainAll}, and {@code clear} operations. It does not
* support the {@code add} or {@code addAll} operations.
*
* <p>The view's {@code iterator} is a "weakly consistent" iterator
* that will never throw {@link ConcurrentModificationException},
* and guarantees to traverse elements as they existed upon
* construction of the iterator, and may (but is not guaranteed to)
* reflect any modifications subsequent to construction.
* <p>The view's iterators and spliterators are
* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
*
* <p>The view's {@code spliterator} reports {@link Spliterator#CONCURRENT}
* and {@link Spliterator#NONNULL}.
*
* @return the collection view
*/
@ -1245,11 +1244,11 @@ public class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
* {@code removeAll}, {@code retainAll}, and {@code clear}
* operations.
*
* <p>The view's {@code iterator} is a "weakly consistent" iterator
* that will never throw {@link ConcurrentModificationException},
* and guarantees to traverse elements as they existed upon
* construction of the iterator, and may (but is not guaranteed to)
* reflect any modifications subsequent to construction.
* <p>The view's iterators and spliterators are
* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
*
* <p>The view's {@code spliterator} reports {@link Spliterator#CONCURRENT},
* {@link Spliterator#DISTINCT}, and {@link Spliterator#NONNULL}.
*
* @return the set view
*/
@ -4308,12 +4307,12 @@ public class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
// implementations below rely on concrete classes supplying these
// abstract methods
/**
* Returns a "weakly consistent" iterator that will never
* throw {@link ConcurrentModificationException}, and
* guarantees to traverse elements as they existed upon
* construction of the iterator, and may (but is not
* guaranteed to) reflect any modifications subsequent to
* construction.
* Returns an iterator over the elements in this collection.
*
* <p>The returned iterator is
* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
*
* @return an iterator over the elements in this collection
*/
public abstract Iterator<E> iterator();
public abstract boolean contains(Object o);

46
jdk/src/share/classes/java/util/concurrent/ConcurrentLinkedDeque.java
View File

@ -55,12 +55,8 @@ import java.util.function.Consumer;
* Like most other concurrent collection implementations, this class
* does not permit the use of {@code null} elements.
*
* <p>Iterators are <i>weakly consistent</i>, returning elements
* reflecting the state of the deque at some point at or since the
* creation of the iterator. They do <em>not</em> throw {@link
* java.util.ConcurrentModificationException
* ConcurrentModificationException}, and may proceed concurrently with
* other operations.
* <p>Iterators and spliterators are
* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
*
* <p>Beware that, unlike in most collections, the {@code size} method
* is <em>NOT</em> a constant-time operation. Because of the
@ -1290,12 +1286,8 @@ public class ConcurrentLinkedDeque<E>
* Returns an iterator over the elements in this deque in proper sequence.
* The elements will be returned in order from first (head) to last (tail).
*
* <p>The returned iterator is a "weakly consistent" iterator that
* will never throw {@link java.util.ConcurrentModificationException
* ConcurrentModificationException}, and guarantees to traverse
* elements as they existed upon construction of the iterator, and
* may (but is not guaranteed to) reflect any modifications
* subsequent to construction.
* <p>The returned iterator is
* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
*
* @return an iterator over the elements in this deque in proper sequence
*/
@ -1308,12 +1300,8 @@ public class ConcurrentLinkedDeque<E>
* sequential order. The elements will be returned in order from
* last (tail) to first (head).
*
* <p>The returned iterator is a "weakly consistent" iterator that
* will never throw {@link java.util.ConcurrentModificationException
* ConcurrentModificationException}, and guarantees to traverse
* elements as they existed upon construction of the iterator, and
* may (but is not guaranteed to) reflect any modifications
* subsequent to construction.
* <p>The returned iterator is
* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
*
* @return an iterator over the elements in this deque in reverse order
*/
@ -1493,6 +1481,22 @@ public class ConcurrentLinkedDeque<E>
}
}
/**
* Returns a {@link Spliterator} over the elements in this deque.
*
* <p>The returned spliterator is
* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
*
* <p>The {@code Spliterator} reports {@link Spliterator#CONCURRENT},
* {@link Spliterator#ORDERED}, and {@link Spliterator#NONNULL}.
*
* @implNote
* The {@code Spliterator} implements {@code trySplit} to permit limited
* parallelism.
*
* @return a {@code Spliterator} over the elements in this deque
* @since 1.8
*/
public Spliterator<E> spliterator() {
return new CLDSpliterator<E>(this);
}
@ -1500,6 +1504,8 @@ public class ConcurrentLinkedDeque<E>
/**
* Saves this deque to a stream (that is, serializes it).
*
* @param s the stream
* @throws java.io.IOException if an I/O error occurs
* @serialData All of the elements (each an {@code E}) in
* the proper order, followed by a null
*/
@ -1522,6 +1528,10 @@ public class ConcurrentLinkedDeque<E>
/**
* Reconstitutes this deque from a stream (that is, deserializes it).
* @param s the stream
* @throws ClassNotFoundException if the class of a serialized object
* could not be found
* @throws java.io.IOException if an I/O error occurs
*/
private void readObject(java.io.ObjectInputStream s)
throws java.io.IOException, ClassNotFoundException {

31
jdk/src/share/classes/java/util/concurrent/ConcurrentLinkedQueue.java
View File

@ -654,12 +654,8 @@ public class ConcurrentLinkedQueue<E> extends AbstractQueue<E>
* Returns an iterator over the elements in this queue in proper sequence.
* The elements will be returned in order from first (head) to last (tail).
*
* <p>The returned iterator is a "weakly consistent" iterator that
* will never throw {@link java.util.ConcurrentModificationException
* ConcurrentModificationException}, and guarantees to traverse
* elements as they existed upon construction of the iterator, and
* may (but is not guaranteed to) reflect any modifications
* subsequent to construction.
* <p>The returned iterator is
* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
*
* @return an iterator over the elements in this queue in proper sequence
*/
@ -749,6 +745,8 @@ public class ConcurrentLinkedQueue<E> extends AbstractQueue<E>
/**
* Saves this queue to a stream (that is, serializes it).
*
* @param s the stream
* @throws java.io.IOException if an I/O error occurs
* @serialData All of the elements (each an {@code E}) in
* the proper order, followed by a null
*/
@ -771,6 +769,10 @@ public class ConcurrentLinkedQueue<E> extends AbstractQueue<E>
/**
* Reconstitutes this queue from a stream (that is, deserializes it).
* @param s the stream
* @throws ClassNotFoundException if the class of a serialized object
* could not be found
* @throws java.io.IOException if an I/O error occurs
*/
private void readObject(java.io.ObjectInputStream s)
throws java.io.IOException, ClassNotFoundException {
@ -881,6 +883,23 @@ public class ConcurrentLinkedQueue<E> extends AbstractQueue<E>
}
}
/**
* Returns a {@link Spliterator} over the elements in this queue.
*
* <p>The returned spliterator is
* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
*
* <p>The {@code Spliterator} reports {@link Spliterator#CONCURRENT},
* {@link Spliterator#ORDERED}, and {@link Spliterator#NONNULL}.
*
* @implNote
* The {@code Spliterator} implements {@code trySplit} to permit limited
* parallelism.
*
* @return a {@code Spliterator} over the elements in this queue
* @since 1.8
*/
@Override
public Spliterator<E> spliterator() {
return new CLQSpliterator<E>(this);
}

21
jdk/src/share/classes/java/util/concurrent/ConcurrentNavigableMap.java
View File

@ -120,11 +120,8 @@ public interface ConcurrentNavigableMap<K,V>
* operations. It does not support the {@code add} or {@code addAll}
* operations.
*
* <p>The view's {@code iterator} is a "weakly consistent" iterator
* that will never throw {@link ConcurrentModificationException},
* and guarantees to traverse elements as they existed upon
* construction of the iterator, and may (but is not guaranteed to)
* reflect any modifications subsequent to construction.
* <p>The view's iterators and spliterators are
* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
*
* @return a navigable set view of the keys in this map
*/
@ -141,11 +138,8 @@ public interface ConcurrentNavigableMap<K,V>
* operations. It does not support the {@code add} or {@code addAll}
* operations.
*
* <p>The view's {@code iterator} is a "weakly consistent" iterator
* that will never throw {@link ConcurrentModificationException},
* and guarantees to traverse elements as they existed upon
* construction of the iterator, and may (but is not guaranteed to)
* reflect any modifications subsequent to construction.
* <p>The view's iterators and spliterators are
* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
*
* <p>This method is equivalent to method {@code navigableKeySet}.
*
@ -164,11 +158,8 @@ public interface ConcurrentNavigableMap<K,V>
* operations. It does not support the {@code add} or {@code addAll}
* operations.
*
* <p>The view's {@code iterator} is a "weakly consistent" iterator
* that will never throw {@link ConcurrentModificationException},
* and guarantees to traverse elements as they existed upon
* construction of the iterator, and may (but is not guaranteed to)
* reflect any modifications subsequent to construction.
* <p>The view's iterators and spliterators are
* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
*
* @return a reverse order navigable set view of the keys in this map
*/

74
jdk/src/share/classes/java/util/concurrent/ConcurrentSkipListMap.java
View File

@ -71,12 +71,13 @@ import java.util.function.Function;
* {@code containsKey}, {@code get}, {@code put} and
* {@code remove} operations and their variants. Insertion, removal,
* update, and access operations safely execute concurrently by
* multiple threads. Iterators are <i>weakly consistent</i>, returning
* elements reflecting the state of the map at some point at or since
* the creation of the iterator. They do <em>not</em> throw {@link
* java.util.ConcurrentModificationException ConcurrentModificationException},
* and may proceed concurrently with other operations. Ascending key ordered
* views and their iterators are faster than descending ones.
* multiple threads.
*
* <p>Iterators and spliterators are
* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
*
* <p>Ascending key ordered views and their iterators are faster than
* descending ones.
*
* <p>All {@code Map.Entry} pairs returned by methods in this class
* and its views represent snapshots of mappings at the time they were
@ -1804,8 +1805,18 @@ public class ConcurrentSkipListMap<K,V> extends AbstractMap<K,V>
/**
* Returns a {@link NavigableSet} view of the keys contained in this map.
* The set's iterator returns the keys in ascending order.
* The set is backed by the map, so changes to the map are
*
* <p>The set's iterator returns the keys in ascending order.
* The set's spliterator additionally reports {@link Spliterator#CONCURRENT},
* {@link Spliterator#NONNULL}, {@link Spliterator#SORTED} and
* {@link Spliterator#ORDERED}, with an encounter order that is ascending
* key order. The spliterator's comparator (see
* {@link java.util.Spliterator#getComparator()}) is {@code null} if
* the map's comparator (see {@link #comparator()}) is {@code null}.
* Otherwise, the spliterator's comparator is the same as or imposes the
* same total ordering as the map's comparator.
*
* <p>The set is backed by the map, so changes to the map are
* reflected in the set, and vice-versa. The set supports element
* removal, which removes the corresponding mapping from the map,
* via the {@code Iterator.remove}, {@code Set.remove},
@ -1813,11 +1824,8 @@ public class ConcurrentSkipListMap<K,V> extends AbstractMap<K,V>
* operations. It does not support the {@code add} or {@code addAll}
* operations.
*
* <p>The view's {@code iterator} is a "weakly consistent" iterator that
* will never throw {@link java.util.ConcurrentModificationException
* ConcurrentModificationException}, and guarantees to traverse elements
* as they existed upon construction of the iterator, and may (but is not
* guaranteed to) reflect any modifications subsequent to construction.
* <p>The view's iterators and spliterators are
* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
*
* <p>This method is equivalent to method {@code navigableKeySet}.
*
@ -1835,9 +1843,13 @@ public class ConcurrentSkipListMap<K,V> extends AbstractMap<K,V>
/**
* Returns a {@link Collection} view of the values contained in this map.
* The collection's iterator returns the values in ascending order
* of the corresponding keys.
* The collection is backed by the map, so changes to the map are
* <p>The collection's iterator returns the values in ascending order
* of the corresponding keys. The collections's spliterator additionally
* reports {@link Spliterator#CONCURRENT}, {@link Spliterator#NONNULL} and
* {@link Spliterator#ORDERED}, with an encounter order that is ascending
* order of the corresponding keys.
*
* <p>The collection is backed by the map, so changes to the map are
* reflected in the collection, and vice-versa. The collection
* supports element removal, which removes the corresponding
* mapping from the map, via the {@code Iterator.remove},
@ -1845,11 +1857,8 @@ public class ConcurrentSkipListMap<K,V> extends AbstractMap<K,V>
* {@code retainAll} and {@code clear} operations. It does not
* support the {@code add} or {@code addAll} operations.
*
* <p>The view's {@code iterator} is a "weakly consistent" iterator that
* will never throw {@link java.util.ConcurrentModificationException
* ConcurrentModificationException}, and guarantees to traverse elements
* as they existed upon construction of the iterator, and may (but is not
* guaranteed to) reflect any modifications subsequent to construction.
* <p>The view's iterators and spliterators are
* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
*/
public Collection<V> values() {
Values<V> vs = values;
@ -1858,8 +1867,14 @@ public class ConcurrentSkipListMap<K,V> extends AbstractMap<K,V>
/**
* Returns a {@link Set} view of the mappings contained in this map.
* The set's iterator returns the entries in ascending key order.
* The set is backed by the map, so changes to the map are
*
* <p>The set's iterator returns the entries in ascending key order. The
* set's spliterator additionally reports {@link Spliterator#CONCURRENT},
* {@link Spliterator#NONNULL}, {@link Spliterator#SORTED} and
* {@link Spliterator#ORDERED}, with an encounter order that is ascending
* key order.
*
* <p>The set is backed by the map, so changes to the map are
* reflected in the set, and vice-versa. The set supports element
* removal, which removes the corresponding mapping from the map,
* via the {@code Iterator.remove}, {@code Set.remove},
@ -1867,15 +1882,12 @@ public class ConcurrentSkipListMap<K,V> extends AbstractMap<K,V>
* operations. It does not support the {@code add} or
* {@code addAll} operations.
*
* <p>The view's {@code iterator} is a "weakly consistent" iterator that
* will never throw {@link java.util.ConcurrentModificationException
* ConcurrentModificationException}, and guarantees to traverse elements
* as they existed upon construction of the iterator, and may (but is not
* guaranteed to) reflect any modifications subsequent to construction.
* <p>The view's iterators and spliterators are
* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
*
* <p>The {@code Map.Entry} elements returned by
* {@code iterator.next()} do <em>not</em> support the
* {@code setValue} operation.
* <p>The {@code Map.Entry} elements traversed by the {@code iterator}
* or {@code spliterator} do <em>not</em> support the {@code setValue}
* operation.
*
* @return a set view of the mappings contained in this map,
* sorted in ascending key order

30
jdk/src/share/classes/java/util/concurrent/ConcurrentSkipListSet.java
View File

@ -57,12 +57,12 @@ import java.util.Spliterator;
* cost for the {@code contains}, {@code add}, and {@code remove}
* operations and their variants. Insertion, removal, and access
* operations safely execute concurrently by multiple threads.
* Iterators are <i>weakly consistent</i>, returning elements
* reflecting the state of the set at some point at or since the
* creation of the iterator. They do <em>not</em> throw {@link
* java.util.ConcurrentModificationException}, and may proceed
* concurrently with other operations. Ascending ordered views and
* their iterators are faster than descending ones.
*
* <p>Iterators and spliterators are
* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
*
* <p>Ascending ordered views and their iterators are faster than
* descending ones.
*
* <p>Beware that, unlike in most collections, the {@code size}
* method is <em>not</em> a constant-time operation. Because of the
@ -480,6 +480,24 @@ public class ConcurrentSkipListSet<E>
return new ConcurrentSkipListSet<E>(m.descendingMap());
}
/**
* Returns a {@link Spliterator} over the elements in this set.
*
* <p>The {@code Spliterator} reports {@link Spliterator#CONCURRENT},
* {@link Spliterator#NONNULL}, {@link Spliterator#DISTINCT},
* {@link Spliterator#SORTED} and {@link Spliterator#ORDERED}, with an
* encounter order that is ascending order. Overriding implementations
* should document the reporting of additional characteristic values.
*
* <p>The spliterator's comparator (see
* {@link java.util.Spliterator#getComparator()}) is {@code null} if
* the set's comparator (see {@link #comparator()}) is {@code null}.
* Otherwise, the spliterator's comparator is the same as or imposes the
* same total ordering as the set's comparator.
*
* @return a {@code Spliterator} over the elements in this set
* @since 1.8
*/
@SuppressWarnings("unchecked")
public Spliterator<E> spliterator() {
if (m instanceof ConcurrentSkipListMap)

35
jdk/src/share/classes/java/util/concurrent/CopyOnWriteArrayList.java
View File

@ -952,6 +952,8 @@ public class CopyOnWriteArrayList<E>
/**
* Saves this list to a stream (that is, serializes it).
*
* @param s the stream
* @throws java.io.IOException if an I/O error occurs
* @serialData The length of the array backing the list is emitted
* (int), followed by all of its elements (each an Object)
* in the proper order.
@ -972,6 +974,10 @@ public class CopyOnWriteArrayList<E>
/**
* Reconstitutes this list from a stream (that is, deserializes it).
* @param s the stream
* @throws ClassNotFoundException if the class of a serialized object
* could not be found
* @throws java.io.IOException if an I/O error occurs
*/
private void readObject(java.io.ObjectInputStream s)
throws java.io.IOException, ClassNotFoundException {
@ -1092,15 +1098,29 @@ public class CopyOnWriteArrayList<E>
*
* @throws IndexOutOfBoundsException {@inheritDoc}
*/
public ListIterator<E> listIterator(final int index) {
public ListIterator<E> listIterator(int index) {
Object[] elements = getArray();
int len = elements.length;
if (index<0 || index>len)
if (index < 0 || index > len)
throw new IndexOutOfBoundsException("Index: "+index);
return new COWIterator<E>(elements, index);
}
/**
* Returns a {@link Spliterator} over the elements in this list.
*
* <p>The {@code Spliterator} reports {@link Spliterator#IMMUTABLE},
* {@link Spliterator#ORDERED}, {@link Spliterator#SIZED}, and
* {@link Spliterator#SUBSIZED}.
*
* <p>The spliterator provides a snapshot of the state of the list
* when the spliterator was constructed. No synchronization is needed while
* operating on the spliterator.
*
* @return a {@code Spliterator} over the elements in this list
* @since 1.8
*/
public Spliterator<E> spliterator() {
return Spliterators.spliterator
(getArray(), Spliterator.IMMUTABLE | Spliterator.ORDERED);
@ -1257,7 +1277,7 @@ public class CopyOnWriteArrayList<E>
// only call this holding l's lock
private void rangeCheck(int index) {
if (index<0 || index>=size)
if (index < 0 || index >= size)
throw new IndexOutOfBoundsException("Index: "+index+
",Size: "+size);
}
@ -1304,7 +1324,7 @@ public class CopyOnWriteArrayList<E>
lock.lock();
try {
checkForComodification();
if (index<0 || index>size)
if (index < 0 || index > size)
throw new IndexOutOfBoundsException();
l.add(index+offset, element);
expectedArray = l.getArray();
@ -1361,12 +1381,12 @@ public class CopyOnWriteArrayList<E>
}
}
public ListIterator<E> listIterator(final int index) {
public ListIterator<E> listIterator(int index) {
final ReentrantLock lock = l.lock;
lock.lock();
try {
checkForComodification();
if (index<0 || index>size)
if (index < 0 || index > size)
throw new IndexOutOfBoundsException("Index: "+index+
", Size: "+size);
return new COWSubListIterator<E>(l, index, offset, size);
@ -1380,7 +1400,7 @@ public class CopyOnWriteArrayList<E>
lock.lock();
try {
checkForComodification();
if (fromIndex<0 || toIndex>size)
if (fromIndex < 0 || toIndex > size)
throw new IndexOutOfBoundsException();
return new COWSubList<E>(l, fromIndex + offset,
toIndex + offset);
@ -1580,6 +1600,7 @@ public class CopyOnWriteArrayList<E>
return Spliterators.spliterator
(a, lo, hi, Spliterator.IMMUTABLE | Spliterator.ORDERED);
}
}
private static class COWSubListIterator<E> implements ListIterator<E> {

15
jdk/src/share/classes/java/util/concurrent/CopyOnWriteArraySet.java
View File

@ -404,6 +404,21 @@ public class CopyOnWriteArraySet<E> extends AbstractSet<E>
al.forEach(action);
}
/**
* Returns a {@link Spliterator} over the elements in this set in the order
* in which these elements were added.
*
* <p>The {@code Spliterator} reports {@link Spliterator#IMMUTABLE},
* {@link Spliterator#DISTINCT}, {@link Spliterator#SIZED}, and
* {@link Spliterator#SUBSIZED}.
*
* <p>The spliterator provides a snapshot of the state of the set
* when the spliterator was constructed. No synchronization is needed while
* operating on the spliterator.
*
* @return a {@code Spliterator} over the elements in this set
* @since 1.8
*/
public Spliterator<E> spliterator() {
return Spliterators.spliterator
(al.getArray(), Spliterator.IMMUTABLE | Spliterator.DISTINCT);

8
jdk/src/share/classes/java/util/concurrent/DelayQueue.java
View File

@ -512,12 +512,8 @@ public class DelayQueue<E extends Delayed> extends AbstractQueue<E>
* unexpired) in this queue. The iterator does not return the
* elements in any particular order.
*
* <p>The returned iterator is a "weakly consistent" iterator that
* will never throw {@link java.util.ConcurrentModificationException
* ConcurrentModificationException}, and guarantees to traverse
* elements as they existed upon construction of the iterator, and
* may (but is not guaranteed to) reflect any modifications
* subsequent to construction.
* <p>The returned iterator is
* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
*
* @return an iterator over the elements in this queue
*/

38
jdk/src/share/classes/java/util/concurrent/LinkedBlockingDeque.java
View File

@ -1008,12 +1008,8 @@ public class LinkedBlockingDeque<E>
* Returns an iterator over the elements in this deque in proper sequence.
* The elements will be returned in order from first (head) to last (tail).
*
* <p>The returned iterator is a "weakly consistent" iterator that
* will never throw {@link java.util.ConcurrentModificationException
* ConcurrentModificationException}, and guarantees to traverse
* elements as they existed upon construction of the iterator, and
* may (but is not guaranteed to) reflect any modifications
* subsequent to construction.
* <p>The returned iterator is
* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
*
* @return an iterator over the elements in this deque in proper sequence
*/
@ -1026,12 +1022,8 @@ public class LinkedBlockingDeque<E>
* sequential order. The elements will be returned in order from
* last (tail) to first (head).
*
* <p>The returned iterator is a "weakly consistent" iterator that
* will never throw {@link java.util.ConcurrentModificationException
* ConcurrentModificationException}, and guarantees to traverse
* elements as they existed upon construction of the iterator, and
* may (but is not guaranteed to) reflect any modifications
* subsequent to construction.
* <p>The returned iterator is
* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
*
* @return an iterator over the elements in this deque in reverse order
*/
@ -1270,6 +1262,22 @@ public class LinkedBlockingDeque<E>
}
}
/**
* Returns a {@link Spliterator} over the elements in this deque.
*
* <p>The returned spliterator is
* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
*
* <p>The {@code Spliterator} reports {@link Spliterator#CONCURRENT},
* {@link Spliterator#ORDERED}, and {@link Spliterator#NONNULL}.
*
* @implNote
* The {@code Spliterator} implements {@code trySplit} to permit limited
* parallelism.
*
* @return a {@code Spliterator} over the elements in this deque
* @since 1.8
*/
public Spliterator<E> spliterator() {
return new LBDSpliterator<E>(this);
}
@ -1277,6 +1285,8 @@ public class LinkedBlockingDeque<E>
/**
* Saves this deque to a stream (that is, serializes it).
*
* @param s the stream
* @throws java.io.IOException if an I/O error occurs
* @serialData The capacity (int), followed by elements (each an
* {@code Object}) in the proper order, followed by a null
*/
@ -1299,6 +1309,10 @@ public class LinkedBlockingDeque<E>
/**
* Reconstitutes this deque from a stream (that is, deserializes it).
* @param s the stream
* @throws ClassNotFoundException if the class of a serialized object
* could not be found
* @throws java.io.IOException if an I/O error occurs
*/
private void readObject(java.io.ObjectInputStream s)
throws java.io.IOException, ClassNotFoundException {

30
jdk/src/share/classes/java/util/concurrent/LinkedBlockingQueue.java
View File

@ -766,12 +766,8 @@ public class LinkedBlockingQueue<E> extends AbstractQueue<E>
* Returns an iterator over the elements in this queue in proper sequence.
* The elements will be returned in order from first (head) to last (tail).
*
* <p>The returned iterator is a "weakly consistent" iterator that
* will never throw {@link java.util.ConcurrentModificationException
* ConcurrentModificationException}, and guarantees to traverse
* elements as they existed upon construction of the iterator, and
* may (but is not guaranteed to) reflect any modifications
* subsequent to construction.
* <p>The returned iterator is
* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
*
* @return an iterator over the elements in this queue in proper sequence
*/
@ -973,6 +969,22 @@ public class LinkedBlockingQueue<E> extends AbstractQueue<E>
}
}
/**
* Returns a {@link Spliterator} over the elements in this queue.
*
* <p>The returned spliterator is
* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
*
* <p>The {@code Spliterator} reports {@link Spliterator#CONCURRENT},
* {@link Spliterator#ORDERED}, and {@link Spliterator#NONNULL}.
*
* @implNote
* The {@code Spliterator} implements {@code trySplit} to permit limited
* parallelism.
*
* @return a {@code Spliterator} over the elements in this queue
* @since 1.8
*/
public Spliterator<E> spliterator() {
return new LBQSpliterator<E>(this);
}
@ -980,6 +992,8 @@ public class LinkedBlockingQueue<E> extends AbstractQueue<E>
/**
* Saves this queue to a stream (that is, serializes it).
*
* @param s the stream
* @throws java.io.IOException if an I/O error occurs
* @serialData The capacity is emitted (int), followed by all of
* its elements (each an {@code Object}) in the proper order,
* followed by a null
@ -1005,6 +1019,10 @@ public class LinkedBlockingQueue<E> extends AbstractQueue<E>
/**
* Reconstitutes this queue from a stream (that is, deserializes it).
* @param s the stream
* @throws ClassNotFoundException if the class of a serialized object
* could not be found
* @throws java.io.IOException if an I/O error occurs
*/
private void readObject(java.io.ObjectInputStream s)
throws java.io.IOException, ClassNotFoundException {

31
jdk/src/share/classes/java/util/concurrent/LinkedTransferQueue.java
View File

@ -40,6 +40,7 @@ import java.util.Collection;
import java.util.Iterator;
import java.util.NoSuchElementException;
import java.util.Queue;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.locks.LockSupport;
import java.util.Spliterator;
import java.util.Spliterators;
@ -1018,6 +1019,22 @@ public class LinkedTransferQueue<E> extends AbstractQueue<E>
}
}
/**
* Returns a {@link Spliterator} over the elements in this queue.
*
* <p>The returned spliterator is
* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
*
* <p>The {@code Spliterator} reports {@link Spliterator#CONCURRENT},
* {@link Spliterator#ORDERED}, and {@link Spliterator#NONNULL}.
*
* @implNote
* The {@code Spliterator} implements {@code trySplit} to permit limited
* parallelism.
*
* @return a {@code Spliterator} over the elements in this queue
* @since 1.8
*/
public Spliterator<E> spliterator() {
return new LTQSpliterator<E>(this);
}
@ -1301,12 +1318,8 @@ public class LinkedTransferQueue<E> extends AbstractQueue<E>
* Returns an iterator over the elements in this queue in proper sequence.
* The elements will be returned in order from first (head) to last (tail).
*
* <p>The returned iterator is a "weakly consistent" iterator that
* will never throw {@link java.util.ConcurrentModificationException
* ConcurrentModificationException}, and guarantees to traverse
* elements as they existed upon construction of the iterator, and
* may (but is not guaranteed to) reflect any modifications
* subsequent to construction.
* <p>The returned iterator is
* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
*
* @return an iterator over the elements in this queue in proper sequence
*/
@ -1407,6 +1420,8 @@ public class LinkedTransferQueue<E> extends AbstractQueue<E>
/**
* Saves this queue to a stream (that is, serializes it).
*
* @param s the stream
* @throws java.io.IOException if an I/O error occurs
* @serialData All of the elements (each an {@code E}) in
* the proper order, followed by a null
*/
@ -1421,6 +1436,10 @@ public class LinkedTransferQueue<E> extends AbstractQueue<E>
/**
* Reconstitutes this queue from a stream (that is, deserializes it).
* @param s the stream
* @throws ClassNotFoundException if the class of a serialized object
* could not be found
* @throws java.io.IOException if an I/O error occurs
*/
private void readObject(java.io.ObjectInputStream s)
throws java.io.IOException, ClassNotFoundException {

32
jdk/src/share/classes/java/util/concurrent/PriorityBlockingQueue.java
View File

@ -229,7 +229,7 @@ public class PriorityBlockingQueue<E> extends AbstractQueue<E>
/**
* Creates a {@code PriorityBlockingQueue} containing the elements
* in the specified collection. If the specified collection is a
* {@link SortedSet} or a {@link PriorityQueue}, this
* {@link SortedSet} or a {@link PriorityQueue}, this
* priority queue will be ordered according to the same ordering.
* Otherwise, this priority queue will be ordered according to the
* {@linkplain Comparable natural ordering} of its elements.
@ -864,12 +864,8 @@ public class PriorityBlockingQueue<E> extends AbstractQueue<E>
* Returns an iterator over the elements in this queue. The
* iterator does not return the elements in any particular order.
*
* <p>The returned iterator is a "weakly consistent" iterator that
* will never throw {@link java.util.ConcurrentModificationException
* ConcurrentModificationException}, and guarantees to traverse
* elements as they existed upon construction of the iterator, and
* may (but is not guaranteed to) reflect any modifications
* subsequent to construction.
* <p>The returned iterator is
* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
*
* @return an iterator over the elements in this queue
*/
@ -915,6 +911,9 @@ public class PriorityBlockingQueue<E> extends AbstractQueue<E>
* For compatibility with previous version of this class, elements
* are first copied to a java.util.PriorityQueue, which is then
* serialized.
*
* @param s the stream
* @throws java.io.IOException if an I/O error occurs
*/
private void writeObject(java.io.ObjectOutputStream s)
throws java.io.IOException {
@ -932,6 +931,10 @@ public class PriorityBlockingQueue<E> extends AbstractQueue<E>
/**
* Reconstitutes this queue from a stream (that is, deserializes it).
* @param s the stream
* @throws ClassNotFoundException if the class of a serialized object
* could not be found
* @throws java.io.IOException if an I/O error occurs
*/
private void readObject(java.io.ObjectInputStream s)
throws java.io.IOException, ClassNotFoundException {
@ -1005,6 +1008,21 @@ public class PriorityBlockingQueue<E> extends AbstractQueue<E>
}
}
/**
* Returns a {@link Spliterator} over the elements in this queue.
*
* <p>The returned spliterator is
* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
*
* <p>The {@code Spliterator} reports {@link Spliterator#SIZED} and
* {@link Spliterator#NONNULL}.
*
* @implNote
* The {@code Spliterator} additionally reports {@link Spliterator#SUBSIZED}.
*
* @return a {@code Spliterator} over the elements in this queue
* @since 1.8
*/
public Spliterator<E> spliterator() {
return new PBQSpliterator<E>(this, null, 0, -1);
}

30
jdk/src/share/classes/java/util/concurrent/SynchronousQueue.java
View File

@ -38,6 +38,8 @@ package java.util.concurrent;
import java.util.concurrent.locks.LockSupport;
import java.util.concurrent.locks.ReentrantLock;
import java.util.*;
import java.util.Spliterator;
import java.util.Spliterators;
/**
* A {@linkplain BlockingQueue blocking queue} in which each insert
@ -1062,21 +1064,17 @@ public class SynchronousQueue<E> extends AbstractQueue<E>
*
* @return an empty iterator
*/
@SuppressWarnings("unchecked")
public Iterator<E> iterator() {
return (Iterator<E>) EmptyIterator.EMPTY_ITERATOR;
}
// Replicated from a previous version of Collections
private static class EmptyIterator<E> implements Iterator<E> {
static final EmptyIterator<Object> EMPTY_ITERATOR
= new EmptyIterator<Object>();
public boolean hasNext() { return false; }
public E next() { throw new NoSuchElementException(); }
public void remove() { throw new IllegalStateException(); }
return Collections.emptyIterator();
}
/**
* Returns an empty spliterator in which calls to
* {@link java.util.Spliterator#trySplit()} always return {@code null}.
*
* @return an empty spliterator
* @since 1.8
*/
public Spliterator<E> spliterator() {
return Spliterators.emptySpliterator();
}
@ -1163,6 +1161,8 @@ public class SynchronousQueue<E> extends AbstractQueue<E>
/**
* Saves this queue to a stream (that is, serializes it).
* @param s the stream
* @throws java.io.IOException if an I/O error occurs
*/
private void writeObject(java.io.ObjectOutputStream s)
throws java.io.IOException {
@ -1182,8 +1182,12 @@ public class SynchronousQueue<E> extends AbstractQueue<E>
/**
* Reconstitutes this queue from a stream (that is, deserializes it).
* @param s the stream
* @throws ClassNotFoundException if the class of a serialized object
* could not be found
* @throws java.io.IOException if an I/O error occurs
*/
private void readObject(final java.io.ObjectInputStream s)
private void readObject(java.io.ObjectInputStream s)
throws java.io.IOException, ClassNotFoundException {
s.defaultReadObject();
if (waitingProducers instanceof FifoWaitQueue)

20
jdk/src/share/classes/java/util/concurrent/package-info.java
View File

@ -210,13 +210,19 @@
* collections are unshared, or are accessible only when
* holding other locks.
*
* <p>Most concurrent Collection implementations (including most
* Queues) also differ from the usual java.util conventions in that
* their Iterators provide <em>weakly consistent</em> rather than
* fast-fail traversal. A weakly consistent iterator is thread-safe,
* but does not necessarily freeze the collection while iterating, so
* it may (or may not) reflect any updates since the iterator was
* created.
* <p id="Weakly">Most concurrent Collection implementations
* (including most Queues) also differ from the usual {@code java.util}
* conventions in that their {@linkplain java.util.Iterator Iterators}
* and {@linkplain java.util.Spliterator Spliterators} provide
* <em>weakly consistent</em> rather than fast-fail traversal:
* <ul>
* <li>they may proceed concurrently with other operations
* <li>they will never throw {@link java.util.ConcurrentModificationException
* ConcurrentModificationException}
* <li>they are guaranteed to traverse elements as they existed upon
* construction exactly once, and may (but are not guaranteed to)
* reflect any modifications subsequent to construction.
* </ul>
*
* <h2 id="MemoryVisibility">Memory Consistency Properties</h2>
*