Collections.addAll: remove outdated performance advice and add a note about atomicity

[Tagir Valeev]

Hello!

I suggest a patch for java.util.Collections#addAll JavaDoc:

--- Collections.java    2018-01-31 09:39:31.599107500 +0700
+++ Collections.java.patched    2018-01-31 09:51:11.929059600 +0700
@@ -5406,4 +5406,8 @@
      * The behavior of this convenience method is identical to that of
-     * {@code c.addAll(Arrays.asList(elements))}, but this method is likely
-     * to run significantly faster under most implementations.
+     * {@code c.addAll(Arrays.asList(elements))} except possible
+     * difference in intermediate state visibility for concurrent or
+     * synchronized collections. Calling this method does not guarantee
+     * that the intermediate state (some of elements are added) is invisible,
+     * even if the collection itself provides such guarantee for its
+     * {@link Collection#addAll(Collection)} method.
      *

First, currently it says that Collections#addAll is likely to run
significantly faster. However it's only marginally faster for
collections which delegate their addAll method to standard
AbstractCollection#addAll implementation. Also it could be much slower
for collections which have optimized addAll (like ArrayList,
CopyOnWriteArrayList, ConcurrentLinkedDeque, etc.). I don't know a
single example of collection where Collections#addAll is actually
significantly faster. Also it says that the behavior is identical,
while it's not. If, e.g. c is a collection returned from
synchronizedCollection, then intermediate state of
c.addAll(Arrays.asList(elements)) would not be visible under
synchronized(c) in another thread. On the other hand, replacing such
call with Collections.addAll(c, elements) (to make it "significantly
faster") will lift this guarantee: now you can see partially added
array.

What do you think? Should I file an issue?

With best regards,
Tagir Valeev.