org.jboss.threads
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 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