util/concurrent/CopyOnWriteArraySet.java

/*
 * Written by Doug Lea with assistance from members of JCP JSR-166
 * Expert Group and released to the public domain. Use, modify, and
 * redistribute this code in any way without acknowledgement.
 */

package java.util.concurrent;
import java.util.*;

/**
 * A {@link java.util.Set} that uses {@link
 * java.util.concurrent.CopyOnWriteArrayList} for all of its
 * operations.  Thus, it shares the same basic properties:
 * <ul>
 *  <li>It is best suited for applications in which set sizes generally
 *       stay small, read-only operations
 *       vastly outnumber mutative operations, and you need
 *       to prevent interference among threads during traversal.
 *  <li>It is thread-safe.
 *  <li>Mutative operations(add, set, remove, etc) are expensive
 *      since they usually entail copying the entire underlying array.
 *  <li>Iterators do not support the mutative remove operation
 *  <li>Traversal via iterators is very fast and cannot ever encounter
 *      interference from other threads. Iterators rely on
 *      unchanging snapshots of the array at the time the iterators were
 *     constructed.
 * </ul>
 * <p>
 * <b>Sample Usage.</b> Probably the main application
 * of copy-on-write sets are classes that maintain
 * sets of Handler objects
 * that must be multicasted to upon an update command. This
 * is a classic case where you do not want to be holding a
 * lock while sending a message, and where traversals normally
 * vastly overwhelm additions.
 * <pre>
 * class Handler { void handle(); ... }
 *
 * class X {
 *    private final CopyOnWriteArraySet&lt;Handler&gt; handlers = new CopyOnWriteArraySet&lt;Handler&gt;();
 *    public void addHandler(Handler h) { handlers.add(h); }
 *
 *    private long internalState;
 *    private synchronized void changeState() { internalState = ...; }
 *
 *    public void update() {
 *       changeState();
 *       Iterator&lt;Handler&gt; it = handlers.iterator();
 *       while (it.hasNext())
 *          it.next().handle();
 *    }
 * }
 * </pre>
 *
 * <p>This class is a member of the
 * <a href="{@docRoot}/../guide/collections/index.html">
 * Java Collections Framework</a>.
 *
 * @see CopyOnWriteArrayList
 * @since 1.5
 * @author Doug Lea
 * @param <E> the type of elements held in this collection
 */
public class CopyOnWriteArraySet<E> extends AbstractSet<E>
        implements Cloneable, java.io.Serializable {
    private static final long serialVersionUID = 5457747651344034263L;

    private final CopyOnWriteArrayList<E> al;

    /**
     * Creates an empty set.
     */
    public CopyOnWriteArraySet() {
        al = new CopyOnWriteArrayList<E>();
    }

    /**
     * Creates a set containing all of the elements of the specified
     * Collection.
     * @param c the collection
     */
    public CopyOnWriteArraySet(Collection<? extends E> c) {
        al = new CopyOnWriteArrayList<E>();
        al.addAllAbsent(c);
    }


    public int      size()                    { return al.size(); }
    public boolean  isEmpty()                 { return al.isEmpty(); }
    public boolean  contains(Object o)        { return al.contains(o); }
    public Object[] toArray()                 { return al.toArray(); }
    public <T> T[]  toArray(T[] a)            { return al.toArray(a); }
    public void     clear()                   {        al.clear(); }
    public Iterator<E>  iterator()            { return al.iterator(); }
    public boolean  remove(Object o)          { return al.remove(o); }
    public boolean  add(E o)                  { return al.addIfAbsent(o); }
    public boolean  containsAll(Collection<?> c)      { return al.containsAll(c); }
    public boolean  addAll(Collection<? extends E> c) { return al.addAllAbsent(c) > 0; }
    public boolean  removeAll(Collection<?> c)        { return al.removeAll(c); }
    public boolean  retainAll(Collection<?> c)        { return al.retainAll(c); }

}
Revision:	1.16
Committed:	Sat Apr 10 14:25:24 2004 UTC (20 years, 1 month ago) by dl
Branch:	MAIN
Changes since 1.15:	+3 -2 lines
Log Message:	Documentation improvements
#	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	dl	1.3	* A {@link java.util.Set} that uses {@link
12			* java.util.concurrent.CopyOnWriteArrayList} for all of its
13			* operations. Thus, it shares the same basic properties:
14	tim	1.1	* <ul>
15	dholmes	1.7	* <li>It is best suited for applications in which set sizes generally
16	tim	1.1	* stay small, read-only operations
17			* vastly outnumber mutative operations, and you need
18			* to prevent interference among threads during traversal.
19	dl	1.16	* <li>It is thread-safe.
20	dholmes	1.7	* <li>Mutative operations(add, set, remove, etc) are expensive
21	tim	1.1	* since they usually entail copying the entire underlying array.
22	dholmes	1.7	* <li>Iterators do not support the mutative remove operation
23			* <li>Traversal via iterators is very fast and cannot ever 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			* constructed.
27			* </ul>
28			* <p>
29			* <b>Sample Usage.</b> Probably the main application
30			* of copy-on-write sets are classes that maintain
31			* sets of Handler objects
32			* that must be multicasted to upon an update command. This
33	tim	1.5	* is a classic case where you do not want to be holding a
34	tim	1.1	* lock while sending a message, and where traversals normally
35			* vastly overwhelm additions.
36			* <pre>
37	tim	1.6	* class Handler { void handle(); ... }
38	tim	1.1	*
39			* class X {
40	dl	1.13	* private final CopyOnWriteArraySet<Handler> handlers = new CopyOnWriteArraySet<Handler>();
41	tim	1.1	* public void addHandler(Handler h) { handlers.add(h); }
42			*
43			* private long internalState;
44			* private synchronized void changeState() { internalState = ...; }
45			*
46			* public void update() {
47			* changeState();
48	dl	1.16	* Iterator<Handler> it = handlers.iterator();
49	tim	1.1	* while (it.hasNext())
50	dl	1.10	* it.next().handle();
51	tim	1.1	* }
52			* }
53	tim	1.6	* </pre>
54	dl	1.14	*
55			* <p>This class is a member of the
56			* <a href="{@docRoot}/../guide/collections/index.html">
57			* Java Collections Framework</a>.
58			*
59	dl	1.16	* @see CopyOnWriteArrayList
60	dl	1.4	* @since 1.5
61			* @author Doug Lea
62	dl	1.11	* @param <E> the type of elements held in this collection
63	dl	1.4	*/
64	tim	1.1	public class CopyOnWriteArraySet<E> extends AbstractSet<E>
65			implements Cloneable, java.io.Serializable {
66	dl	1.8	private static final long serialVersionUID = 5457747651344034263L;
67	tim	1.1
68			private final CopyOnWriteArrayList<E> al;
69
70			/**
71	dl	1.15	* Creates an empty set.
72	tim	1.1	*/
73			public CopyOnWriteArraySet() {
74			al = new CopyOnWriteArrayList<E>();
75			}
76
77			/**
78	dl	1.15	* Creates a set containing all of the elements of the specified
79	tim	1.1	* Collection.
80	dl	1.4	* @param c the collection
81	tim	1.1	*/
82	tim	1.12	public CopyOnWriteArraySet(Collection<? extends E> c) {
83	tim	1.1	al = new CopyOnWriteArrayList<E>();
84			al.addAllAbsent(c);
85			}
86
87
88			public int size() { return al.size(); }
89			public boolean isEmpty() { return al.isEmpty(); }
90			public boolean contains(Object o) { return al.contains(o); }
91			public Object[] toArray() { return al.toArray(); }
92			public <T> T[] toArray(T[] a) { return al.toArray(a); }
93			public void clear() { al.clear(); }
94			public Iterator<E> iterator() { return al.iterator(); }
95			public boolean remove(Object o) { return al.remove(o); }
96			public boolean add(E o) { return al.addIfAbsent(o); }
97	tim	1.5	public boolean containsAll(Collection<?> c) { return al.containsAll(c); }
98			public boolean addAll(Collection<? extends E> c) { return al.addAllAbsent(c) > 0; }
99			public boolean removeAll(Collection<?> c) { return al.removeAll(c); }
100			public boolean retainAll(Collection<?> c) { return al.retainAll(c); }
101	tim	1.1
102			}