51 * the size of the array used to store the elements in the list. It is always
52 * at least as large as the list size. As elements are added to an IdentityArrayList,
53 * its capacity grows automatically. The details of the growth policy are not
54 * specified beyond the fact that adding an element has constant amortized
55 * time cost.<p>
56 *
57 * An application can increase the capacity of an <tt>IdentityArrayList</tt> instance
58 * before adding a large number of elements using the <tt>ensureCapacity</tt>
59 * operation. This may reduce the amount of incremental reallocation.
60 *
61 * <p><strong>Note that this implementation is not synchronized.</strong>
62 * If multiple threads access an <tt>IdentityArrayList</tt> instance concurrently,
63 * and at least one of the threads modifies the list structurally, it
64 * <i>must</i> be synchronized externally. (A structural modification is
65 * any operation that adds or deletes one or more elements, or explicitly
66 * resizes the backing array; merely setting the value of an element is not
67 * a structural modification.) This is typically accomplished by
68 * synchronizing on some object that naturally encapsulates the list.
69 *
70 * If no such object exists, the list should be "wrapped" using the
71 * {@link Collections#synchronizedList Collections.synchronizedList}
72 * method. This is best done at creation time, to prevent accidental
73 * unsynchronized access to the list:<pre>
74 * List list = Collections.synchronizedList(new IdentityArrayList(...));</pre>
75 *
76 * <p>The iterators returned by this class's <tt>iterator</tt> and
77 * <tt>listIterator</tt> methods are <i>fail-fast</i>: if the list is
78 * structurally modified at any time after the iterator is created, in any way
79 * except through the iterator's own <tt>remove</tt> or <tt>add</tt> methods,
80 * the iterator will throw a {@link ConcurrentModificationException}. Thus, in
81 * the face of concurrent modification, the iterator fails quickly and cleanly,
82 * rather than risking arbitrary, non-deterministic behavior at an undetermined
83 * time in the future.<p>
84 *
85 * Note that the fail-fast behavior of an iterator cannot be guaranteed
86 * as it is, generally speaking, impossible to make any hard guarantees in the
87 * presence of unsynchronized concurrent modification. Fail-fast iterators
88 * throw <tt>ConcurrentModificationException</tt> on a best-effort basis.
89 * Therefore, it would be wrong to write a program that depended on this
90 * exception for its correctness: <i>the fail-fast behavior of iterators
91 * should be used only to detect bugs.</i><p>
|
51 * the size of the array used to store the elements in the list. It is always
52 * at least as large as the list size. As elements are added to an IdentityArrayList,
53 * its capacity grows automatically. The details of the growth policy are not
54 * specified beyond the fact that adding an element has constant amortized
55 * time cost.<p>
56 *
57 * An application can increase the capacity of an <tt>IdentityArrayList</tt> instance
58 * before adding a large number of elements using the <tt>ensureCapacity</tt>
59 * operation. This may reduce the amount of incremental reallocation.
60 *
61 * <p><strong>Note that this implementation is not synchronized.</strong>
62 * If multiple threads access an <tt>IdentityArrayList</tt> instance concurrently,
63 * and at least one of the threads modifies the list structurally, it
64 * <i>must</i> be synchronized externally. (A structural modification is
65 * any operation that adds or deletes one or more elements, or explicitly
66 * resizes the backing array; merely setting the value of an element is not
67 * a structural modification.) This is typically accomplished by
68 * synchronizing on some object that naturally encapsulates the list.
69 *
70 * If no such object exists, the list should be "wrapped" using the
71 * {@link java.util.Collections#synchronizedList Collections.synchronizedList}
72 * method. This is best done at creation time, to prevent accidental
73 * unsynchronized access to the list:<pre>
74 * List list = Collections.synchronizedList(new IdentityArrayList(...));</pre>
75 *
76 * <p>The iterators returned by this class's <tt>iterator</tt> and
77 * <tt>listIterator</tt> methods are <i>fail-fast</i>: if the list is
78 * structurally modified at any time after the iterator is created, in any way
79 * except through the iterator's own <tt>remove</tt> or <tt>add</tt> methods,
80 * the iterator will throw a {@link ConcurrentModificationException}. Thus, in
81 * the face of concurrent modification, the iterator fails quickly and cleanly,
82 * rather than risking arbitrary, non-deterministic behavior at an undetermined
83 * time in the future.<p>
84 *
85 * Note that the fail-fast behavior of an iterator cannot be guaranteed
86 * as it is, generally speaking, impossible to make any hard guarantees in the
87 * presence of unsynchronized concurrent modification. Fail-fast iterators
88 * throw <tt>ConcurrentModificationException</tt> on a best-effort basis.
89 * Therefore, it would be wrong to write a program that depended on this
90 * exception for its correctness: <i>the fail-fast behavior of iterators
91 * should be used only to detect bugs.</i><p>
|