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 fast and cannot 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> The following code sketch uses a
 * copy-on-write set to maintain a set of Handler objects that
 * perform some action upon state updates.
 *
 * <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();
 *       for (Handler handler : handlers)
 *          handler.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 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 of elements to initially contain
     * @throws NullPointerException if the specified collection is null
     */
    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 boolean  remove(Object o)          { return al.remove(o); }
    public boolean  add(E e)                  { return al.addIfAbsent(e); }
    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); }

    /**
     * Returns an iterator over the elements contained in this collection
     * in the order in which these elements were added.
     */
    public Iterator<E>  iterator()            { return al.iterator(); }

}
Revision:	1.23
Committed:	Tue May 17 05:20:33 2005 UTC (19 years ago) by jsr166
Branch:	MAIN
Changes since 1.22:	+4 -2 lines
Log Message:	doc fixes
#	Content
1	/*
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	package java.util.concurrent;
8	import java.util.*;
9
10	/**
11	* 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	* <ul>
15	* <li>It is best suited for applications in which set sizes generally
16	* stay small, read-only operations
17	* vastly outnumber mutative operations, and you need
18	* to prevent interference among threads during traversal.
19	* <li>It is thread-safe.
20	* <li>Mutative operations (add, set, remove, etc) are expensive
21	* since they usually entail copying the entire underlying array.
22	* <li>Iterators do not support the mutative remove operation.
23	* <li>Traversal via iterators is fast and cannot encounter
24	* interference from other threads. Iterators rely on
25	* unchanging snapshots of the array at the time the iterators were
26	* constructed.
27	* </ul>
28	*
29	* <p> <b>Sample Usage.</b> The following code sketch uses a
30	* copy-on-write set to maintain a set of Handler objects that
31	* perform some action upon state updates.
32	*
33	* <pre>
34	* class Handler { void handle(); ... }
35	*
36	* class X {
37	* private final CopyOnWriteArraySet<Handler> handlers = new CopyOnWriteArraySet<Handler>();
38	* 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	* for (Handler handler : handlers)
46	* handler.handle();
47	* }
48	* }
49	* </pre>
50	*
51	* <p>This class is a member of the
52	* <a href="{@docRoot}/../guide/collections/index.html">
53	* Java Collections Framework</a>.
54	*
55	* @see CopyOnWriteArrayList
56	* @since 1.5
57	* @author Doug Lea
58	* @param <E> the type of elements held in this collection
59	*/
60	public class CopyOnWriteArraySet<E> extends AbstractSet<E>
61	implements java.io.Serializable {
62	private static final long serialVersionUID = 5457747651344034263L;
63
64	private final CopyOnWriteArrayList<E> al;
65
66	/**
67	* Creates an empty set.
68	*/
69	public CopyOnWriteArraySet() {
70	al = new CopyOnWriteArrayList<E>();
71	}
72
73	/**
74	* Creates a set containing all of the elements of the specified
75	* collection.
76	*
77	* @param c the collection of elements to initially contain
78	* @throws NullPointerException if the specified collection is null
79	*/
80	public CopyOnWriteArraySet(Collection<? extends E> c) {
81	al = new CopyOnWriteArrayList<E>();
82	al.addAllAbsent(c);
83	}
84
85
86	public int size() { return al.size(); }
87	public boolean isEmpty() { return al.isEmpty(); }
88	public boolean contains(Object o) { return al.contains(o); }
89	public Object[] toArray() { return al.toArray(); }
90	public <T> T[] toArray(T[] a) { return al.toArray(a); }
91	public void clear() { al.clear(); }
92	public boolean remove(Object o) { return al.remove(o); }
93	public boolean add(E e) { return al.addIfAbsent(e); }
94	public boolean containsAll(Collection<?> c) { return al.containsAll(c); }
95	public boolean addAll(Collection<? extends E> c) { return al.addAllAbsent(c) > 0; }
96	public boolean removeAll(Collection<?> c) { return al.removeAll(c); }
97	public boolean retainAll(Collection<?> c) { return al.retainAll(c); }
98
99	/**
100	* Returns an iterator over the elements contained in this collection
101	* in the order in which these elements were added.
102	*/
103	public Iterator<E> iterator() { return al.iterator(); }
104
105	}