Class AtomicArray<T,V>

java.lang.Object
org.jboss.threads.AtomicArray<T,V>
Type Parameters:
T - the type which contains the target field
V - the array value type
public final class AtomicArray<T,V> extends 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.

  • Method Details

    • create

      public static <T,V> AtomicArray<T,V> create(AtomicReferenceFieldUpdater<T,V[]> updater, Class<V> componentType)
      Construct a new 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

    • create

      @Deprecated public static <T,V> AtomicArray<T,V> create(AtomicReferenceFieldUpdater<T,V[]> updater, AtomicArray.Creator<V> creator)
      Deprecated.
      Use create(AtomicReferenceFieldUpdater, Object[]) or create(AtomicReferenceFieldUpdater, Class) instead.
      Construct a new instance.
      Type Parameters:
      T - the type which contains the target field
      V - the array value type
      Parameters:
      updater - the field updater
      creator - the array creator
      Returns:
      the new instance

    • create

      public static <T,V> AtomicArray<T,V> create(AtomicReferenceFieldUpdater<T,V[]> updater, V[] emptyArray)
      Construct a new instance.
      Type Parameters:
      T - the type which contains the target field
      V - the array value type
      Parameters:
      updater - the field updater
      emptyArray - an empty array of the target type
      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

    • 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, 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, 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, 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, Comparator<? super V> comparator)
      Sort an array.
      Parameters:
      instance - the instance holding the field
      comparator - a comparator, or null to use natural ordering