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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	AtomicArray.Creator<V>
private static class	AtomicArray.ReflectCreator<V>

Field Summary

Fields

Modifier and Type	Field and Description
private AtomicArray.Creator<V>	creator
private V[]	emptyArray
private java.util.concurrent.atomic.AtomicReferenceFieldUpdater<T,V[]>	updater

Constructor Summary

Constructors

Modifier	Constructor and Description
private	AtomicArray(java.util.concurrent.atomic.AtomicReferenceFieldUpdater<T,V[]> updater, AtomicArray.Creator<V> creator) Construct an instance.

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, 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.
private static <V> V[]	copyOf(AtomicArray.Creator<V> creator, V[] old, int newLen)
static <T,V> AtomicArray<T,V>	create(java.util.concurrent.atomic.AtomicReferenceFieldUpdater<T,V[]> updater, AtomicArray.Creator<V> creator) Convenience method to create an instance.
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

emptyArray

private final V[] emptyArray

creator

private final AtomicArray.Creator<V> creator

Constructor Detail

AtomicArray

private AtomicArray(java.util.concurrent.atomic.AtomicReferenceFieldUpdater<T,V[]> updater,
                    AtomicArray.Creator<V> creator)

Construct an instance.

Parameters:

updater - the field updater

creator - the array creator

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

create

public static <T,V> AtomicArray<T,V> create(java.util.concurrent.atomic.AtomicReferenceFieldUpdater<T,V[]> updater,
                                            AtomicArray.Creator<V> creator)

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

creator - the array creator

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(AtomicArray.Creator<V> creator,
                              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)