Package com.couchbase.transactions.util

Class ConcurrentDoublyLinkedList<E>

  • Type Parameters:
    E - the type of elements held in this collection
    All Implemented Interfaces:
    java.io.Serializable, java.lang.Iterable<E>, java.util.Collection<E>
    @Internal
public class ConcurrentDoublyLinkedList<E>
extends java.util.AbstractCollection<E>
implements java.io.Serializable
    A concurrent linked-list implementation of a Deque (double-ended queue). Concurrent insertion, removal, and access operations execute safely across multiple threads. Iterators are weakly consistent, returning elements reflecting the state of the deque at some point at or since the creation of the iterator. They do not throw ConcurrentModificationException, and may proceed concurrently with other operations.

    This class and its iterators implement all of the optional methods of the Collection and Iterator interfaces. Like most other concurrent collection implementations, this class does not permit the use of null elements. because some null arguments and return values cannot be reliably distinguished from the absence of elements. Arbitrarily, the Collection.remove(java.lang.Object) method is mapped to removeFirstOccurrence, and Collection.add(E) is mapped to addLast.

    Beware that, unlike in most collections, the size method is NOT a constant-time operation. Because of the asynchronous nature of these deques, determining the current number of elements requires a traversal of the elements.

    This class is Serializable, but relies on default serialization mechanisms. Usually, it is a better idea for any serializable class using a ConcurrentLinkedDeque to instead serialize a snapshot of the elements obtained by method toArray.

    See Also:
    Serialized Form

    • Constructor Summary

      Constructors 
      Constructor Description
      ConcurrentDoublyLinkedList()
      Constructs an empty deque.
      ConcurrentDoublyLinkedList​(java.util.Collection<? extends E> c)
      Constructs a deque containing the elements of the specified collection, in the order they are returned by the collection's iterator.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean add​(E e)  
      boolean addAll​(java.util.Collection<? extends E> c)
      Appends all of the elements in the specified collection to the end of this deque, in the order that they are returned by the specified collection's iterator.
      void addFirst​(E o)
      Prepends the given element at the beginning of this deque.
      void addLast​(E o)
      Appends the given element to the end of this deque.
      void clear()
      Removes all of the elements from this deque.
      boolean contains​(java.lang.Object o)
      Returns true if this deque contains at least one element e such that o.equals(e).
      E element()  
      E getFirst()
      Returns the first element in this deque.
      E getLast()
      Returns the last element in this deque.
      boolean isEmpty()
      Returns true if this collection contains no elements.
      java.util.Iterator<E> iterator()
      Returns a weakly consistent iterator over the elements in this deque, in first-to-last order.
      boolean offer​(E e)  
      boolean offerFirst​(E o)
      Prepends the given element at the beginning of this deque.
      boolean offerLast​(E o)
      Appends the given element to the end of this deque.
      E peek()  
      E peekFirst()
      Retrieves, but does not remove, the first element of this deque, or returns null if this deque is empty.
      E peekLast()
      Retrieves, but does not remove, the last element of this deque, or returns null if this deque is empty.
      E poll()  
      E pollFirst()
      Retrieves and removes the first element of this deque, or returns null if this deque is empty.
      E pollLast()
      Retrieves and removes the last element of this deque, or returns null if this deque is empty.
      E pop()  
      void push​(E e)  
      E remove()  
      boolean remove​(java.lang.Object o)
      Removes the first element e such that o.equals(e), if such an element exists in this deque.
      E removeFirst()
      Removes and returns the first element from this deque.
      boolean removeFirstOccurrence​(java.lang.Object o)
      Removes the first element e such that o.equals(e), if such an element exists in this deque.
      E removeLast()
      Removes and returns the last element from this deque.
      boolean removeLastOccurrence​(java.lang.Object o)
      Removes the last element e such that o.equals(e), if such an element exists in this deque.
      int size()
      Returns the number of elements in this deque.
      java.lang.Object[] toArray()
      Returns an array containing all of the elements in this deque in the correct order.
      <T> T[] toArray​(T[] a)
      Returns an array containing all of the elements in this deque in the correct order; the runtime type of the returned array is that of the specified array.

      • Methods inherited from class java.util.AbstractCollection

        containsAll, removeAll, retainAll, toString

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

      • Methods inherited from interface java.util.Collection

        equals, hashCode, parallelStream, removeIf, spliterator, stream, toArray

      • Methods inherited from interface java.lang.Iterable

        forEach

    • Constructor Detail

      • ConcurrentDoublyLinkedList

        public ConcurrentDoublyLinkedList()
        Constructs an empty deque.

      • ConcurrentDoublyLinkedList

        public ConcurrentDoublyLinkedList​(java.util.Collection<? extends E> c)
        Constructs a deque containing the elements of the specified collection, in the order they are returned by the collection's iterator.
        Parameters:
        c - the collection whose elements are to be placed into this deque.
        Throws:
        java.lang.NullPointerException - if c or any element within it is null

    • Method Detail

      • addFirst

        public void addFirst​(E o)
        Prepends the given element at the beginning of this deque.
        Parameters:
        o - the element to be inserted at the beginning of this deque.
        Throws:
        java.lang.NullPointerException - if the specified element is null

      • addLast

        public void addLast​(E o)
        Appends the given element to the end of this deque. This is identical in function to the add method.
        Parameters:
        o - the element to be inserted at the end of this deque.
        Throws:
        java.lang.NullPointerException - if the specified element is null

      • offerFirst

        public boolean offerFirst​(E o)
        Prepends the given element at the beginning of this deque.
        Parameters:
        o - the element to be inserted at the beginning of this deque.
        Returns:
        true always
        Throws:
        java.lang.NullPointerException - if the specified element is null

      • offerLast

        public boolean offerLast​(E o)
        Appends the given element to the end of this deque. (Identical in function to the add method; included only for consistency.)
        Parameters:
        o - the element to be inserted at the end of this deque.
        Returns:
        true always
        Throws:
        java.lang.NullPointerException - if the specified element is null

      • peekFirst

        public E peekFirst()
        Retrieves, but does not remove, the first element of this deque, or returns null if this deque is empty.
        Returns:
        the first element of this queue, or null if empty.

      • peekLast

        public E peekLast()
        Retrieves, but does not remove, the last element of this deque, or returns null if this deque is empty.
        Returns:
        the last element of this deque, or null if empty.

      • getFirst

        public E getFirst()
        Returns the first element in this deque.
        Returns:
        the first element in this deque.
        Throws:
        java.util.NoSuchElementException - if this deque is empty.

      • getLast

        public E getLast()
        Returns the last element in this deque.
        Returns:
        the last element in this deque.
        Throws:
        java.util.NoSuchElementException - if this deque is empty.

      • pollFirst

        public E pollFirst()
        Retrieves and removes the first element of this deque, or returns null if this deque is empty.
        Returns:
        the first element of this deque, or null if empty.

      • pollLast

        public E pollLast()
        Retrieves and removes the last element of this deque, or returns null if this deque is empty.
        Returns:
        the last element of this deque, or null if empty.

      • removeFirst

        public E removeFirst()
        Removes and returns the first element from this deque.
        Returns:
        the first element from this deque.
        Throws:
        java.util.NoSuchElementException - if this deque is empty.

      • removeLast

        public E removeLast()
        Removes and returns the last element from this deque.
        Returns:
        the last element from this deque.
        Throws:
        java.util.NoSuchElementException - if this deque is empty.

      • offer

        public boolean offer​(E e)

      • add

        public boolean add​(E e)
        Specified by:
        add in interface java.util.Collection<E>
        Overrides:
        add in class java.util.AbstractCollection<E>

      • poll

        public E poll()

      • remove

        public E remove()

      • peek

        public E peek()

      • element

        public E element()

      • push

        public void push​(E e)

      • pop

        public E pop()

      • removeFirstOccurrence

        public boolean removeFirstOccurrence​(java.lang.Object o)
        Removes the first element e such that o.equals(e), if such an element exists in this deque. If the deque does not contain the element, it is unchanged.
        Parameters:
        o - element to be removed from this deque, if present.
        Returns:
        true if the deque contained the specified element.
        Throws:
        java.lang.NullPointerException - if the specified element is null

      • removeLastOccurrence

        public boolean removeLastOccurrence​(java.lang.Object o)
        Removes the last element e such that o.equals(e), if such an element exists in this deque. If the deque does not contain the element, it is unchanged.
        Parameters:
        o - element to be removed from this deque, if present.
        Returns:
        true if the deque contained the specified element.
        Throws:
        java.lang.NullPointerException - if the specified element is null

      • contains

        public boolean contains​(java.lang.Object o)
        Returns true if this deque contains at least one element e such that o.equals(e).
        Specified by:
        contains in interface java.util.Collection<E>
        Overrides:
        contains in class java.util.AbstractCollection<E>
        Parameters:
        o - element whose presence in this deque is to be tested.
        Returns:
        true if this deque contains the specified element.

      • isEmpty

        public boolean isEmpty()
        Returns true if this collection contains no elements.

        Specified by:
        isEmpty in interface java.util.Collection<E>
        Overrides:
        isEmpty in class java.util.AbstractCollection<E>
        Returns:
        true if this collection contains no elements.

      • size

        public int size()
        Returns the number of elements in this deque. If this deque contains more than Integer.MAX_VALUE elements, it returns Integer.MAX_VALUE.

        Beware that, unlike in most collections, this method is NOT a constant-time operation. Because of the asynchronous nature of these deques, determining the current number of elements requires traversing them all to count them. Additionally, it is possible for the size to change during execution of this method, in which case the returned result will be inaccurate. Thus, this method is typically not very useful in concurrent applications.

        Specified by:
        size in interface java.util.Collection<E>
        Specified by:
        size in class java.util.AbstractCollection<E>
        Returns:
        the number of elements in this deque.

      • remove

        public boolean remove​(java.lang.Object o)
        Removes the first element e such that o.equals(e), if such an element exists in this deque. If the deque does not contain the element, it is unchanged.
        Specified by:
        remove in interface java.util.Collection<E>
        Overrides:
        remove in class java.util.AbstractCollection<E>
        Parameters:
        o - element to be removed from this deque, if present.
        Returns:
        true if the deque contained the specified element.
        Throws:
        java.lang.NullPointerException - if the specified element is null

      • addAll

        public boolean addAll​(java.util.Collection<? extends E> c)
        Appends all of the elements in the specified collection to the end of this deque, in the order that they are returned by the specified collection's iterator. The behavior of this operation is undefined if the specified collection is modified while the operation is in progress. (This implies that the behavior of this call is undefined if the specified Collection is this deque, and this deque is nonempty.)
        Specified by:
        addAll in interface java.util.Collection<E>
        Overrides:
        addAll in class java.util.AbstractCollection<E>
        Parameters:
        c - the elements to be inserted into this deque.
        Returns:
        true if this deque changed as a result of the call.
        Throws:
        java.lang.NullPointerException - if c or any element within it is null

      • clear

        public void clear()
        Removes all of the elements from this deque.
        Specified by:
        clear in interface java.util.Collection<E>
        Overrides:
        clear in class java.util.AbstractCollection<E>

      • toArray

        public java.lang.Object[] toArray()
        Returns an array containing all of the elements in this deque in the correct order.
        Specified by:
        toArray in interface java.util.Collection<E>
        Overrides:
        toArray in class java.util.AbstractCollection<E>
        Returns:
        an array containing all of the elements in this deque in the correct order.

      • toArray

        public <T> T[] toArray​(T[] a)
        Returns an array containing all of the elements in this deque in the correct order; the runtime type of the returned array is that of the specified array. If the deque fits in the specified array, it is returned therein. Otherwise, a new array is allocated with the runtime type of the specified array and the size of this deque.

        If the deque fits in the specified array with room to spare (i.e., the array has more elements than the deque), the element in the array immediately following the end of the collection is set to null. This is useful in determining the length of the deque only if the caller knows that the deque does not contain any null elements.

        Specified by:
        toArray in interface java.util.Collection<E>
        Overrides:
        toArray in class java.util.AbstractCollection<E>
        Parameters:
        a - the array into which the elements of the deque are to be stored, if it is big enough; otherwise, a new array of the same runtime type is allocated for this purpose.
        Returns:
        an array containing the elements of the deque.
        Throws:
        java.lang.ArrayStoreException - if the runtime type of a is not a supertype of the runtime type of every element in this deque.
        java.lang.NullPointerException - if the specified array is null.

      • iterator

        public java.util.Iterator<E> iterator()
        Returns a weakly consistent iterator over the elements in this deque, in first-to-last order. The next method returns elements reflecting the state of the deque at some point at or since the creation of the iterator. The method does not throw ConcurrentModificationException, and may proceed concurrently with other operations.
        Specified by:
        iterator in interface java.util.Collection<E>
        Specified by:
        iterator in interface java.lang.Iterable<E>
        Specified by:
        iterator in class java.util.AbstractCollection<E>
        Returns:
        an iterator over the elements in this deque