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 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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	AtomicArray.Creator<V> Deprecated.

Method Summary

Modifier and Type	Method and 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, 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, 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(AtomicReferenceFieldUpdater<T,V[]> updater, AtomicArray.Creator<V> creator) Deprecated. Use create(AtomicReferenceFieldUpdater, Object[]) or create(AtomicReferenceFieldUpdater, Class) instead.
static <T,V> AtomicArray<T,V>	create(AtomicReferenceFieldUpdater<T,V[]> updater, Class<V> componentType) Construct a new instance.
static <T,V> AtomicArray<T,V>	create(AtomicReferenceFieldUpdater<T,V[]> updater, V[] emptyArray) Construct a new 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, 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, 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

Method Detail

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