From 4071e413e5a994efd39d3ef864367cde582a3f73 Mon Sep 17 00:00:00 2001 From: Doug Lea Date: Fri, 22 Apr 2011 16:33:23 +0100 Subject: [PATCH] 7038885: Improved bulk operation disclaimers for concurrent collections Reviewed-by: chegar --- .../concurrent/ConcurrentLinkedDeque.java | 13 ++++++++++--- .../concurrent/ConcurrentLinkedQueue.java | 9 ++++++++- .../concurrent/ConcurrentSkipListMap.java | 19 +++++++++++-------- .../concurrent/ConcurrentSkipListSet.java | 14 ++++++++------ .../util/concurrent/LinkedTransferQueue.java | 13 ++++++++++--- 5 files changed, 47 insertions(+), 21 deletions(-) diff --git a/jdk/src/share/classes/java/util/concurrent/ConcurrentLinkedDeque.java b/jdk/src/share/classes/java/util/concurrent/ConcurrentLinkedDeque.java index 4c1c4616263..21d59cfc460 100644 --- a/jdk/src/share/classes/java/util/concurrent/ConcurrentLinkedDeque.java +++ b/jdk/src/share/classes/java/util/concurrent/ConcurrentLinkedDeque.java @@ -59,10 +59,17 @@ import java.util.Queue; * ConcurrentModificationException}, and may proceed concurrently with * other operations. * - *

Beware that, unlike in most collections, the {@code size} - * method is NOT a constant-time operation. Because of the + *

Beware that, unlike in most collections, the {@code size} method + * is NOT a constant-time operation. Because of the * asynchronous nature of these deques, determining the current number - * of elements requires a traversal of the elements. + * of elements requires a traversal of the elements, and so may report + * inaccurate results if this collection is modified during traversal. + * Additionally, the bulk operations {@code addAll}, + * {@code removeAll}, {@code retainAll}, {@code containsAll}, + * {@code equals}, and {@code toArray} are not guaranteed + * to be performed atomically. For example, an iterator operating + * concurrently with an {@code addAll} operation might view only some + * of the added elements. * *

This class and its iterator implement all of the optional * methods of the {@link Deque} and {@link Iterator} interfaces. diff --git a/jdk/src/share/classes/java/util/concurrent/ConcurrentLinkedQueue.java b/jdk/src/share/classes/java/util/concurrent/ConcurrentLinkedQueue.java index 09f21ef1504..fcdfcf97eb6 100644 --- a/jdk/src/share/classes/java/util/concurrent/ConcurrentLinkedQueue.java +++ b/jdk/src/share/classes/java/util/concurrent/ConcurrentLinkedQueue.java @@ -72,7 +72,14 @@ import java.util.Queue; *

Beware that, unlike in most collections, the {@code size} method * is NOT a constant-time operation. Because of the * asynchronous nature of these queues, determining the current number - * of elements requires a traversal of the elements. + * of elements requires a traversal of the elements, and so may report + * inaccurate results if this collection is modified during traversal. + * Additionally, the bulk operations {@code addAll}, + * {@code removeAll}, {@code retainAll}, {@code containsAll}, + * {@code equals}, and {@code toArray} are not guaranteed + * to be performed atomically. For example, an iterator operating + * concurrently with an {@code addAll} operation might view only some + * of the added elements. * *

This class and its iterator implement all of the optional * methods of the {@link Queue} and {@link Iterator} interfaces. diff --git a/jdk/src/share/classes/java/util/concurrent/ConcurrentSkipListMap.java b/jdk/src/share/classes/java/util/concurrent/ConcurrentSkipListMap.java index 8e3e4d0a7cc..8d23964512b 100644 --- a/jdk/src/share/classes/java/util/concurrent/ConcurrentSkipListMap.java +++ b/jdk/src/share/classes/java/util/concurrent/ConcurrentSkipListMap.java @@ -66,12 +66,13 @@ import java.util.concurrent.atomic.*; *

Beware that, unlike in most collections, the size * method is not a constant-time operation. Because of the * asynchronous nature of these maps, determining the current number - * of elements requires a traversal of the elements. Additionally, - * the bulk operations putAll, equals, and - * clear are not guaranteed to be performed - * atomically. For example, an iterator operating concurrently with a - * putAll operation might view only some of the added - * elements. + * of elements requires a traversal of the elements, and so may report + * inaccurate results if this collection is modified during traversal. + * Additionally, the bulk operations putAll, equals, + * toArray, containsValue, and clear are + * not guaranteed to be performed atomically. For example, an + * iterator operating concurrently with a putAll operation + * might view only some of the added elements. * *

This class and its views and iterators implement all of the * optional methods of the {@link Map} and {@link Iterator} @@ -1661,7 +1662,9 @@ public class ConcurrentSkipListMap extends AbstractMap /** * Returns true if this map maps one or more keys to the * specified value. This operation requires time linear in the - * map size. + * map size. Additionally, it is possible for the map to change + * during execution of this method, in which case the returned + * result may be inaccurate. * * @param value value whose presence in this map is to be tested * @return true if a mapping to value exists; @@ -1751,7 +1754,7 @@ public class ConcurrentSkipListMap extends AbstractMap * * @return a navigable set view of the keys in this map */ - public NavigableSet keySet() { + public NavigableSet keySet() { KeySet ks = keySet; return (ks != null) ? ks : (keySet = new KeySet(this)); } diff --git a/jdk/src/share/classes/java/util/concurrent/ConcurrentSkipListSet.java b/jdk/src/share/classes/java/util/concurrent/ConcurrentSkipListSet.java index eb90bb0bf9f..7b5dc79a932 100644 --- a/jdk/src/share/classes/java/util/concurrent/ConcurrentSkipListSet.java +++ b/jdk/src/share/classes/java/util/concurrent/ConcurrentSkipListSet.java @@ -58,12 +58,14 @@ import sun.misc.Unsafe; *

Beware that, unlike in most collections, the size * method is not a constant-time operation. Because of the * asynchronous nature of these sets, determining the current number - * of elements requires a traversal of the elements. Additionally, the - * bulk operations addAll, removeAll, - * retainAll, and containsAll are not - * guaranteed to be performed atomically. For example, an iterator - * operating concurrently with an addAll operation might view - * only some of the added elements. + * of elements requires a traversal of the elements, and so may report + * inaccurate results if this collection is modified during traversal. + * Additionally, the bulk operations addAll, + * removeAll, retainAll, containsAll, + * equals, and toArray are not guaranteed + * to be performed atomically. For example, an iterator operating + * concurrently with an addAll operation might view only some + * of the added elements. * *

This class and its iterators implement all of the * optional methods of the {@link Set} and {@link Iterator} diff --git a/jdk/src/share/classes/java/util/concurrent/LinkedTransferQueue.java b/jdk/src/share/classes/java/util/concurrent/LinkedTransferQueue.java index 3fe72477bf9..ebdf223ff6c 100644 --- a/jdk/src/share/classes/java/util/concurrent/LinkedTransferQueue.java +++ b/jdk/src/share/classes/java/util/concurrent/LinkedTransferQueue.java @@ -51,10 +51,17 @@ import java.util.concurrent.locks.LockSupport; * producer. The tail of the queue is that element that has * been on the queue the shortest time for some producer. * - *

Beware that, unlike in most collections, the {@code size} - * method is NOT a constant-time operation. Because of the + *

Beware that, unlike in most collections, the {@code size} method + * is NOT a constant-time operation. Because of the * asynchronous nature of these queues, determining the current number - * of elements requires a traversal of the elements. + * of elements requires a traversal of the elements, and so may report + * inaccurate results if this collection is modified during traversal. + * Additionally, the bulk operations {@code addAll}, + * {@code removeAll}, {@code retainAll}, {@code containsAll}, + * {@code equals}, and {@code toArray} are not guaranteed + * to be performed atomically. For example, an iterator operating + * concurrently with an {@code addAll} operation might view only some + * of the added elements. * *

This class and its iterator implement all of the * optional methods of the {@link Collection} and {@link