ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/concurrent/CopyOnWriteArraySet.java
Revision: 1.28
Committed: Sun Jun 19 23:01:12 2005 UTC (18 years, 11 months ago) by jsr166
Branch: MAIN
Changes since 1.27: +11 -11 lines
Log Message: 
doc fixes

File Contents

# User Rev Content
1 dl 1.2 /*
2     * Written by Doug Lea with assistance from members of JCP JSR-166
3     * Expert Group and released to the public domain. Use, modify, and
4     * redistribute this code in any way without acknowledgement.
5     */
6    
7 tim 1.1 package java.util.concurrent;
8     import java.util.*;
9    
10     /**
11 jsr166 1.26 * A {@link java.util.Set} that uses an internal {@link CopyOnWriteArrayList}
12     * for all of its operations. Thus, it shares the same basic properties:
13 tim 1.1 * <ul>
14 dholmes 1.7 * <li>It is best suited for applications in which set sizes generally
15 tim 1.1 * stay small, read-only operations
16     * vastly outnumber mutative operations, and you need
17     * to prevent interference among threads during traversal.
18 dl 1.16 * <li>It is thread-safe.
19 jsr166 1.26 * <li>Mutative operations (<tt>add</tt>, <tt>set</tt>, <tt>remove</tt>, etc.)
20     * are expensive since they usually entail copying the entire underlying
21     * array.
22     * <li>Iterators do not support the mutative <tt>remove</tt> operation.
23 dl 1.18 * <li>Traversal via iterators is fast and cannot encounter
24 tim 1.1 * interference from other threads. Iterators rely on
25     * unchanging snapshots of the array at the time the iterators were
26 jsr166 1.26 * constructed.
27 tim 1.1 * </ul>
28 dl 1.18 *
29     * <p> <b>Sample Usage.</b> The following code sketch uses a
30 jsr166 1.21 * copy-on-write set to maintain a set of Handler objects that
31     * perform some action upon state updates.
32 dl 1.18 *
33 tim 1.1 * <pre>
34 tim 1.6 * class Handler { void handle(); ... }
35 tim 1.1 *
36     * class X {
37 dl 1.13 * private final CopyOnWriteArraySet&lt;Handler&gt; handlers = new CopyOnWriteArraySet&lt;Handler&gt;();
38 tim 1.1 * public void addHandler(Handler h) { handlers.add(h); }
39     *
40     * private long internalState;
41     * private synchronized void changeState() { internalState = ...; }
42     *
43     * public void update() {
44     * changeState();
45 dl 1.18 * for (Handler handler : handlers)
46 dl 1.19 * handler.handle();
47 tim 1.1 * }
48     * }
49 tim 1.6 * </pre>
50 dl 1.14 *
51     * <p>This class is a member of the
52     * <a href="{@docRoot}/../guide/collections/index.html">
53     * Java Collections Framework</a>.
54     *
55 dl 1.16 * @see CopyOnWriteArrayList
56 dl 1.4 * @since 1.5
57     * @author Doug Lea
58 dl 1.11 * @param <E> the type of elements held in this collection
59 dl 1.4 */
60 tim 1.1 public class CopyOnWriteArraySet<E> extends AbstractSet<E>
61 dl 1.18 implements java.io.Serializable {
62 dl 1.8 private static final long serialVersionUID = 5457747651344034263L;
63 tim 1.1
64     private final CopyOnWriteArrayList<E> al;
65    
66     /**
67 dl 1.15 * Creates an empty set.
68 tim 1.1 */
69     public CopyOnWriteArraySet() {
70     al = new CopyOnWriteArrayList<E>();
71     }
72    
73     /**
74 dl 1.15 * Creates a set containing all of the elements of the specified
75 jsr166 1.23 * collection.
76 jsr166 1.25 *
77 jsr166 1.23 * @param c the collection of elements to initially contain
78     * @throws NullPointerException if the specified collection is null
79 tim 1.1 */
80 tim 1.12 public CopyOnWriteArraySet(Collection<? extends E> c) {
81 tim 1.1 al = new CopyOnWriteArrayList<E>();
82     al.addAllAbsent(c);
83     }
84    
85 jsr166 1.26 /**
86     * Returns the number of elements in this set.
87     *
88     * @return the number of elements in this set
89     */
90     public int size() {
91     return al.size();
92     }
93    
94     /**
95     * Returns <tt>true</tt> if this set contains no elements.
96     *
97     * @return <tt>true</tt> if this set contains no elements
98     */
99     public boolean isEmpty() {
100     return al.isEmpty();
101     }
102    
103     /**
104     * Returns <tt>true</tt> if this set contains the specified element.
105     * More formally, returns <tt>true</tt> if and only if this set
106 jsr166 1.28 * contains an element <tt>e</tt> such that
107 jsr166 1.26 * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>.
108     *
109     * @param o element whose presence in this set is to be tested
110     * @return <tt>true</tt> if this set contains the specified element
111     */
112     public boolean contains(Object o) {
113     return al.contains(o);
114     }
115    
116     /**
117     * Returns an array containing all of the elements in this set.
118     * If this set makes any guarantees as to what order its elements
119     * are returned by its iterator, this method must return the
120     * elements in the same order.
121     *
122     * <p>The returned array will be "safe" in that no references to it
123     * are maintained by this set. (In other words, this method must
124     * allocate a new array even if this set is backed by an array).
125     * The caller is thus free to modify the returned array.
126     *
127     * <p>This method acts as bridge between array-based and collection-based
128     * APIs.
129     *
130     * @return an array containing all the elements in this set
131     */
132     public Object[] toArray() {
133     return al.toArray();
134     }
135    
136     /**
137     * Returns an array containing all of the elements in this set; the
138     * runtime type of the returned array is that of the specified array.
139     * If the set fits in the specified array, it is returned therein.
140     * Otherwise, a new array is allocated with the runtime type of the
141     * specified array and the size of this set.
142     *
143     * <p>If this set fits in the specified array with room to spare
144     * (i.e., the array has more elements than this set), the element in
145     * the array immediately following the end of the set is set to
146     * <tt>null</tt>. (This is useful in determining the length of this
147     * set <i>only</i> if the caller knows that this set does not contain
148     * any null elements.)
149     *
150     * <p>If this set makes any guarantees as to what order its elements
151     * are returned by its iterator, this method must return the elements
152     * in the same order.
153     *
154     * <p>Like the {@link #toArray()} method, this method acts as bridge between
155     * array-based and collection-based APIs. Further, this method allows
156     * precise control over the runtime type of the output array, and may,
157     * under certain circumstances, be used to save allocation costs.
158     *
159     * <p>Suppose <tt>x</tt> is a set known to contain only strings.
160     * The following code can be used to dump the set into a newly allocated
161     * array of <tt>String</tt>:
162     *
163     * <pre>
164     * String[] y = x.toArray(new String[0]);</pre>
165     *
166     * Note that <tt>toArray(new Object[0])</tt> is identical in function to
167     * <tt>toArray()</tt>.
168     *
169     * @param a the array into which the elements of this set are to be
170     * stored, if it is big enough; otherwise, a new array of the same
171     * runtime type is allocated for this purpose.
172     * @return an array containing all the elements in this set
173     * @throws ArrayStoreException if the runtime type of the specified array
174     * is not a supertype of the runtime type of every element in this
175     * set
176     * @throws NullPointerException if the specified array is null
177     */
178     public <T> T[] toArray(T[] a) {
179     return al.toArray(a);
180     }
181    
182     /**
183     * Removes all of the elements from this set.
184 jsr166 1.27 * The set will be empty after this call returns.
185 jsr166 1.26 */
186     public void clear() {
187     al.clear();
188     }
189    
190     /**
191     * Removes the specified element from this set if it is present.
192     * More formally, removes an element <tt>e</tt> such that
193 jsr166 1.28 * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>,
194     * if this set contains such an element. Returns <tt>true</tt> if
195     * this set contained the element (or equivalently, if this set
196     * changed as a result of the call). (This set will not contain the
197 jsr166 1.26 * element once the call returns.)
198     *
199     * @param o object to be removed from this set, if present
200     * @return <tt>true</tt> if this set contained the specified element
201     */
202     public boolean remove(Object o) {
203     return al.remove(o);
204     }
205    
206     /**
207     * Adds the specified element to this set if it is not already present.
208 jsr166 1.28 * More formally, adds the specified element <tt>e</tt> to this set if
209     * the set contains no element <tt>e2</tt> such that
210     * <tt>(e==null&nbsp;?&nbsp;e2==null&nbsp;:&nbsp;e.equals(e2))</tt>.
211     * If this set already contains the element, the call leaves the set
212     * unchanged and returns <tt>false</tt>.
213 jsr166 1.26 *
214     * @param e element to be added to this set
215     * @return <tt>true</tt> if this set did not already contain the specified
216     * element
217     */
218     public boolean add(E e) {
219     return al.addIfAbsent(e);
220     }
221 tim 1.1
222 jsr166 1.26 /**
223     * Returns <tt>true</tt> if this set contains all of the elements of the
224     * specified collection. If the specified collection is also a set, this
225     * method returns <tt>true</tt> if it is a <i>subset</i> of this set.
226     *
227     * @param c collection to be checked for containment in this set
228     * @return <tt>true</tt> if this set contains all of the elements of the
229     * specified collection
230     * @throws NullPointerException if the specified collection is null
231     * @see #contains(Object)
232     */
233     public boolean containsAll(Collection<?> c) {
234     return al.containsAll(c);
235     }
236    
237     /**
238     * Adds all of the elements in the specified collection to this set if
239     * they're not already present. If the specified collection is also a
240     * set, the <tt>addAll</tt> operation effectively modifies this set so
241     * that its value is the <i>union</i> of the two sets. The behavior of
242 jsr166 1.28 * this operation is undefined if the specified collection is modified
243 jsr166 1.26 * while the operation is in progress.
244     *
245     * @param c collection containing elements to be added to this set
246     * @return <tt>true</tt> if this set changed as a result of the call
247     * @throws NullPointerException if the specified collection is null
248     * @see #add(Object)
249     */
250     public boolean addAll(Collection<? extends E> c) {
251     return al.addAllAbsent(c) > 0;
252     }
253    
254     /**
255     * Removes from this set all of its elements that are contained in the
256     * specified collection. If the specified collection is also a set,
257     * this operation effectively modifies this set so that its value is the
258     * <i>asymmetric set difference</i> of the two sets.
259     *
260     * @param c collection containing elements to be removed from this set
261     * @return <tt>true</tt> if this set changed as a result of the call
262     * @throws ClassCastException if the class of an element of this set
263     * is incompatible with the specified collection (optional)
264     * @throws NullPointerException if this set contains a null element and the
265     * specified collection does not permit null elements (optional),
266     * or if the specified collection is null
267     * @see #remove(Object)
268     */
269     public boolean removeAll(Collection<?> c) {
270     return al.removeAll(c);
271     }
272    
273     /**
274     * Retains only the elements in this set that are contained in the
275     * specified collection. In other words, removes from this set all of
276     * its elements that are not contained in the specified collection. If
277     * the specified collection is also a set, this operation effectively
278     * modifies this set so that its value is the <i>intersection</i> of the
279     * two sets.
280     *
281     * @param c collection containing elements to be retained in this set
282     * @return <tt>true</tt> if this set changed as a result of the call
283     * @throws ClassCastException if the class of an element of this set
284     * is incompatible with the specified collection (optional)
285     * @throws NullPointerException if this set contains a null element and the
286     * specified collection does not permit null elements (optional),
287     * or if the specified collection is null
288     * @see #remove(Object)
289     */
290     public boolean retainAll(Collection<?> c) {
291     return al.retainAll(c);
292     }
293 tim 1.1
294 dl 1.20 /**
295 jsr166 1.24 * Returns an iterator over the elements contained in this set
296 dl 1.20 * in the order in which these elements were added.
297 jsr166 1.26 *
298     * <p>The returned iterator provides a snapshot of the state of the set
299     * when the iterator was constructed. No synchronization is needed while
300     * traversing the iterator. The iterator does <em>NOT</em> support the
301     * <tt>remove</tt> method.
302     *
303     * @return an iterator over the elements in this set
304 dl 1.20 */
305 jsr166 1.26 public Iterator<E> iterator() {
306     return al.iterator();
307     }
308 dl 1.20
309 tim 1.1 }