sample/java.util.concurrent.ConcurrentLinkedQueue.txt

   1 *java.util.concurrent.ConcurrentLinkedQueue* *ConcurrentLinkedQueue* An unbounde
   2
   3 public class ConcurrentLinkedQueue<E>
   4   extends    |java.util.AbstractQueue|
   5   implements |java.util.Queue|
   6              |java.io.Serializable|
   7
   8 |java.util.concurrent.ConcurrentLinkedQueue_Description|
   9 |java.util.concurrent.ConcurrentLinkedQueue_Fields|
  10 |java.util.concurrent.ConcurrentLinkedQueue_Constructors|
  11 |java.util.concurrent.ConcurrentLinkedQueue_Methods|
  12
  13 ================================================================================
  14
  15 *java.util.concurrent.ConcurrentLinkedQueue_Constructors*
  16 |java.util.concurrent.ConcurrentLinkedQueue()|Creates a ConcurrentLinkedQueue t
  17 |java.util.concurrent.ConcurrentLinkedQueue(Collection<?extendsE>)|Creates a Co
  18
  19 *java.util.concurrent.ConcurrentLinkedQueue_Methods*
  20 |java.util.concurrent.ConcurrentLinkedQueue.add(E)|Inserts the specified elemen
  21 |java.util.concurrent.ConcurrentLinkedQueue.contains(Object)|Returns true if th
  22 |java.util.concurrent.ConcurrentLinkedQueue.isEmpty()|Returns true if this queu
  23 |java.util.concurrent.ConcurrentLinkedQueue.iterator()|Returns an iterator over
  24 |java.util.concurrent.ConcurrentLinkedQueue.offer(E)|Inserts the specified elem
  25 |java.util.concurrent.ConcurrentLinkedQueue.peek()|
  26 |java.util.concurrent.ConcurrentLinkedQueue.poll()|
  27 |java.util.concurrent.ConcurrentLinkedQueue.remove(Object)|Removes a single ins
  28 |java.util.concurrent.ConcurrentLinkedQueue.size()|Returns the number of elemen
  29 |java.util.concurrent.ConcurrentLinkedQueue.toArray()|Returns an array containi
  30 |java.util.concurrent.ConcurrentLinkedQueue.toArray(T[])|Returns an array conta
  31
  32 *java.util.concurrent.ConcurrentLinkedQueue_Description*
  33
  34 An unbounded thread-safe queue(|java.util.Queue|) based on linked nodes. This
  35 queue orders elements FIFO (first-in-first-out). The head of the queue is that
  36 element that has been on the queue the longest time. The tail of the queue is
  37 that element that has been on the queue the shortest time. New elements are
  38 inserted at the tail of the queue, and the queue retrieval operations obtain
  39 elements at the head of the queue. A ConcurrentLinkedQueue is an appropriate
  40 choice when many threads will share access to a common collection. This queue
  41 does not permit null elements.
  42
  43 This implementation employs an efficient wait-free algorithm based on one
  44 described in Simple, Fast, and Practical Non-Blocking and Blocking Concurrent
  45 Queue Algorithms by Maged M. Michael and Michael L. Scott.
  46
  47 Beware that, unlike in most collections, the size method is NOT a constant-time
  48 operation. Because of the asynchronous nature of these queues, determining the
  49 current number of elements requires a traversal of the elements.
  50
  51 This class and its iterator implement all of the optional methods of the
  52 (|java.util.Collection|) and (|java.util.Iterator|) interfaces.
  53
  54 Memory consistency effects: As with other concurrent collections, actions in a
  55 thread prior to placing an object into aConcurrentLinkedQueuehappen-before
  56 actions subsequent to the access or removal of that element from
  57 theConcurrentLinkedQueuein another thread.
  58
  59 This class is a member of the <a
  60 href="/../technotes/guides/collections/index.html"> Java Collections Framework.
  61
  62
  63
  64 *java.util.concurrent.ConcurrentLinkedQueue()*
  65
  66 public ConcurrentLinkedQueue()
  67
  68 Creates a ConcurrentLinkedQueue that is initially empty.
  69
  70
  71 *java.util.concurrent.ConcurrentLinkedQueue(Collection<?extendsE>)*
  72
  73 public ConcurrentLinkedQueue(java.util.Collection<? extends E> c)
  74
  75 Creates a ConcurrentLinkedQueue initially containing the elements of the given
  76 collection, added in traversal order of the collection's iterator.
  77
  78     c - the collection of elements to initially contain
  79
  80 *java.util.concurrent.ConcurrentLinkedQueue.add(E)*
  81
  82 public boolean add(E e)
  83
  84 Inserts the specified element at the tail of this queue.
  85
  86
  87
  88     Returns: true (as specified by {@link Collection#add})
  89
  90 *java.util.concurrent.ConcurrentLinkedQueue.contains(Object)*
  91
  92 public boolean contains(java.lang.Object o)
  93
  94 Returns true if this queue contains the specified element. More formally,
  95 returns true if and only if this queue contains at least one element e such
  96 that o.equals(e).
  97
  98
  99     o - object to be checked for containment in this queue
 100
 101     Returns: true if this queue contains the specified element
 102
 103 *java.util.concurrent.ConcurrentLinkedQueue.isEmpty()*
 104
 105 public boolean isEmpty()
 106
 107 Returns true if this queue contains no elements.
 108
 109
 110
 111     Returns: true if this queue contains no elements
 112
 113 *java.util.concurrent.ConcurrentLinkedQueue.iterator()*
 114
 115 public |java.util.Iterator|<E> iterator()
 116
 117 Returns an iterator over the elements in this queue in proper sequence. The
 118 returned iterator is a "weakly consistent" iterator that will never throw
 119 (|java.util.ConcurrentModificationException|) , and guarantees to traverse
 120 elements as they existed upon construction of the iterator, and may (but is not
 121 guaranteed to) reflect any modifications subsequent to construction.
 122
 123
 124
 125     Returns: an iterator over the elements in this queue in proper sequence
 126
 127 *java.util.concurrent.ConcurrentLinkedQueue.offer(E)*
 128
 129 public boolean offer(E e)
 130
 131 Inserts the specified element at the tail of this queue.
 132
 133
 134
 135     Returns: true (as specified by {@link Queue#offer})
 136
 137 *java.util.concurrent.ConcurrentLinkedQueue.peek()*
 138
 139 public |E| peek()
 140
 141
 142
 143
 144
 145 *java.util.concurrent.ConcurrentLinkedQueue.poll()*
 146
 147 public |E| poll()
 148
 149
 150
 151
 152
 153 *java.util.concurrent.ConcurrentLinkedQueue.remove(Object)*
 154
 155 public boolean remove(java.lang.Object o)
 156
 157 Removes a single instance of the specified element from this queue, if it is
 158 present. More formally, removes an element e such that o.equals(e), if this
 159 queue contains one or more such elements. Returns true if this queue contained
 160 the specified element (or equivalently, if this queue changed as a result of
 161 the call).
 162
 163
 164     o - element to be removed from this queue, if present
 165
 166     Returns: true if this queue changed as a result of the call
 167
 168 *java.util.concurrent.ConcurrentLinkedQueue.size()*
 169
 170 public int size()
 171
 172 Returns the number of elements in this queue. If this queue contains more than
 173 Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.
 174
 175 Beware that, unlike in most collections, this method is NOT a constant-time
 176 operation. Because of the asynchronous nature of these queues, determining the
 177 current number of elements requires an O(n) traversal.
 178
 179
 180
 181     Returns: the number of elements in this queue
 182
 183 *java.util.concurrent.ConcurrentLinkedQueue.toArray()*
 184
 185 public |java.lang.Object|[] toArray()
 186
 187 Returns an array containing all of the elements in this queue, in proper
 188 sequence.
 189
 190 The returned array will be "safe" in that no references to it are maintained by
 191 this queue. (In other words, this method must allocate a new array). The caller
 192 is thus free to modify the returned array.
 193
 194 This method acts as bridge between array-based and collection-based APIs.
 195
 196
 197
 198     Returns: an array containing all of the elements in this queue
 199
 200 *java.util.concurrent.ConcurrentLinkedQueue.toArray(T[])*
 201
 202 public |T|[] toArray(T[] a)
 203
 204 Returns an array containing all of the elements in this queue, in proper
 205 sequence; the runtime type of the returned array is that of the specified
 206 array. If the queue fits in the specified array, it is returned therein.
 207 Otherwise, a new array is allocated with the runtime type of the specified
 208 array and the size of this queue.
 209
 210 If this queue fits in the specified array with room to spare (i.e., the array
 211 has more elements than this queue), the element in the array immediately
 212 following the end of the queue is set to null.
 213
 214 Like the (|java.util.concurrent.ConcurrentLinkedQueue|) method, this method
 215 acts as bridge between array-based and collection-based APIs. Further, this
 216 method allows precise control over the runtime type of the output array, and
 217 may, under certain circumstances, be used to save allocation costs.
 218
 219 Suppose x is a queue known to contain only strings. The following code can be
 220 used to dump the queue into a newly allocated array of String:
 221
 222
 223
 224 String[] y = x.toArray(new String[0]);
 225
 226 Note that toArray(new Object[0]) is identical in function to toArray().
 227
 228
 229     a - the array into which the elements of the queue are to be stored, if it is big
 230        enough; otherwise, a new array of the same runtime type is allocated for
 231        this purpose
 232
 233     Returns: an array containing all of the elements in this queue
 234
 235