org.jboss.threads
Class AtomicArray<T,V>

java.lang.Object
  extended by 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 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.


Constructor Summary
AtomicArray(java.util.concurrent.atomic.AtomicReferenceFieldUpdater<T,V[]> updater, java.lang.Class<V> componentType)
          Construct an instance.
 
Method Summary
 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.
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.
 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
 

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

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


Copyright © 2011. All Rights Reserved.