Class AtomicArray<T,​V>

  • Type Parameters:
    T - the type which contains the target field
    V - the array value type

    final class AtomicArray<T,​V>
    extends java.lang.Object
    Utility for snapshot/copy-on-write arrays. To use these methods, two things are required: an immutable array stored on a volatile field, and an instance of AtomicReferenceFieldUpdater which corresponds to that field. Some of these methods perform multi-step operations; if the array field value is changed in the middle of such an operation, the operation is retried. To avoid spinning, in some situations it may be advisable to hold a write lock to prevent multiple concurrent updates.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private java.lang.Class<V> componentType  
      private V[] emptyArray  
      private java.util.concurrent.atomic.AtomicReferenceFieldUpdater<T,​V[]> updater  
    • Constructor Summary

      Constructors 
      Constructor Description
      AtomicArray​(java.util.concurrent.atomic.AtomicReferenceFieldUpdater<T,​V[]> updater, java.lang.Class<V> componentType)
      Construct an instance.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void add​(T instance, V value)
      Atomically replace the array with a new array which is one element longer, and which includes the given value.
      void add​(T instance, V value, java.util.Comparator<? super V> comparator)
      Add a value to a sorted array.
      boolean addIfAbsent​(T instance, V value, boolean identity)
      Atomically replace the array with a new array which is one element longer, and which includes the given value, if the value is not already present within the array.
      boolean addIfAbsent​(T instance, V value, java.util.Comparator<? super V> comparator)
      Add a value to a sorted array if it is not already present.
      void clear​(T instance)
      Convenience method to set the field value to the empty array.
      boolean compareAndSet​(T instance, V[] expect, V[] update)
      Compare and set the array.
      private static <V> V[] copyOf​(java.lang.Class<V> componentType, V[] old, int newLen)  
      static <T,​V>
      AtomicArray<T,​V>
      create​(java.util.concurrent.atomic.AtomicReferenceFieldUpdater<T,​V[]> updater, java.lang.Class<V> componentType)
      Convenience method to create an instance.
      V[] getAndSet​(T instance, V[] value)
      Atomically get and update the value of this array.
      private static int insertionPoint​(int searchResult)  
      private static <V> V[] newInstance​(java.lang.Class<V> componentType, int length)  
      boolean remove​(T instance, V value, boolean identity)
      Atomically replace the array with a new array which does not include the first occurrance of the given value, if the value is present in the array.
      boolean remove​(T instance, V value, java.util.Comparator<? super V> comparator)
      Remove a value to a sorted array.
      int removeAll​(T instance, V value, boolean identity)
      Atomically replace the array with a new array which does not include any occurrances of the given value, if the value is present in the array.
      void set​(T instance, V[] value)
      Update the value of this array.
      void sort​(T instance, java.util.Comparator<? super V> comparator)
      Sort an array.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • updater

        private final java.util.concurrent.atomic.AtomicReferenceFieldUpdater<T,​V[]> updater
      • componentType

        private final java.lang.Class<V> componentType
      • emptyArray

        private final V[] emptyArray
    • Constructor Detail

      • AtomicArray

        public AtomicArray​(java.util.concurrent.atomic.AtomicReferenceFieldUpdater<T,​V[]> updater,
                           java.lang.Class<V> componentType)
        Construct an instance.
        Parameters:
        updater - the field updater
        componentType - the component class
    • Method Detail

      • create

        public static <T,​V> AtomicArray<T,​V> create​(java.util.concurrent.atomic.AtomicReferenceFieldUpdater<T,​V[]> updater,
                                                                java.lang.Class<V> componentType)
        Convenience method to create an instance.
        Type Parameters:
        T - the type which contains the target field
        V - the array value type
        Parameters:
        updater - the field updater
        componentType - the component class
        Returns:
        the new instance
      • clear

        public void clear​(T instance)
        Convenience method to set the field value to the empty array. Empty array instances are shared.
        Parameters:
        instance - the instance holding the field
      • set

        public void set​(T instance,
                        V[] value)
        Update the value of this array.
        Parameters:
        instance - the instance holding the field
        value - the new value
      • getAndSet

        public V[] getAndSet​(T instance,
                             V[] value)
        Atomically get and update the value of this array.
        Parameters:
        instance - the instance holding the field
        value - the new value
      • copyOf

        private static <V> V[] copyOf​(java.lang.Class<V> componentType,
                                      V[] old,
                                      int newLen)
      • add

        public void add​(T instance,
                        V value)
        Atomically replace the array with a new array which is one element longer, and which includes the given value.
        Parameters:
        instance - the instance holding the field
        value - the updated value
      • addIfAbsent

        public boolean addIfAbsent​(T instance,
                                   V value,
                                   boolean identity)
        Atomically replace the array with a new array which is one element longer, and which includes the given value, if the value is not already present within the array. This method does a linear search for the target value.
        Parameters:
        instance - the instance holding the field
        value - the updated value
        identity - true if comparisons should be done using reference identity, or false to use the equals() method
        Returns:
        true if the value was added, or false if it was already present
      • remove

        public boolean remove​(T instance,
                              V value,
                              boolean identity)
        Atomically replace the array with a new array which does not include the first occurrance of the given value, if the value is present in the array.
        Parameters:
        instance - the instance holding the field
        value - the updated value
        identity - true if comparisons should be done using reference identity, or false to use the equals() method
        Returns:
        true if the value was removed, or false if it was not present
      • removeAll

        public int removeAll​(T instance,
                             V value,
                             boolean identity)
        Atomically replace the array with a new array which does not include any occurrances of the given value, if the value is present in the array.
        Parameters:
        instance - the instance holding the field
        value - the updated value
        identity - true if comparisons should be done using reference identity, or false to use the equals() method
        Returns:
        the number of values removed
      • add

        public void add​(T instance,
                        V value,
                        java.util.Comparator<? super V> comparator)
        Add a value to a sorted array. Does not check for duplicates.
        Parameters:
        instance - the instance holding the field
        value - the value to add
        comparator - a comparator, or null to use natural ordering
      • addIfAbsent

        public boolean addIfAbsent​(T instance,
                                   V value,
                                   java.util.Comparator<? super V> comparator)
        Add a value to a sorted array if it is not already present. Does not check for duplicates.
        Parameters:
        instance - the instance holding the field
        value - the value to add
        comparator - a comparator, or null to use natural ordering
      • remove

        public boolean remove​(T instance,
                              V value,
                              java.util.Comparator<? super V> comparator)
        Remove a value to a sorted array. Does not check for duplicates. If there are multiple occurrances of a value, there is no guarantee as to which one is removed.
        Parameters:
        instance - the instance holding the field
        value - the value to remove
        comparator - a comparator, or null to use natural ordering
      • sort

        public void sort​(T instance,
                         java.util.Comparator<? super V> comparator)
        Sort an array.
        Parameters:
        instance - the instance holding the field
        comparator - a comparator, or null to use natural ordering
      • insertionPoint

        private static int insertionPoint​(int searchResult)
      • newInstance

        private static <V> V[] newInstance​(java.lang.Class<V> componentType,
                                           int length)
      • compareAndSet

        public boolean compareAndSet​(T instance,
                                     V[] expect,
                                     V[] update)
        Compare and set the array.
        Parameters:
        instance - the instance holding the field
        expect - the expected value
        update - the update value
        Returns:
        true if the value was updated or false if the expected value did not match