concurrent/atomic/AtomicReference.java

/*
 * Written by Doug Lea with assistance from members of JCP JSR-166
 * Expert Group and released to the public domain, as explained at
 * http://creativecommons.org/publicdomain/zero/1.0/
 */

package java.util.concurrent.atomic;
import sun.misc.Unsafe;

/**
 * An object reference that may be updated atomically. See the {@link
 * java.util.concurrent.atomic} package specification for description
 * of the properties of atomic variables.
 * @since 1.5
 * @author Doug Lea
 * @param <V> The type of object referred to by this reference
 */
public class AtomicReference<V> implements java.io.Serializable {
    private static final long serialVersionUID = -1848883965231344442L;

    private static final Unsafe unsafe = Unsafe.getUnsafe();
    private static final long valueOffset;

    static {
        try {
            valueOffset = unsafe.objectFieldOffset
                (AtomicReference.class.getDeclaredField("value"));
        } catch (Exception ex) { throw new Error(ex); }
    }

    private volatile V value;

    /**
     * Creates a new AtomicReference with the given initial value.
     *
     * @param initialValue the initial value
     */
    public AtomicReference(V initialValue) {
        value = initialValue;
    }

    /**
     * Creates a new AtomicReference with null initial value.
     */
    public AtomicReference() {
    }

    /**
     * Gets the current value.
     *
     * @return the current value
     */
    public final V get() {
        return value;
    }

    /**
     * Sets to the given value.
     *
     * @param newValue the new value
     */
    public final void set(V newValue) {
        value = newValue;
    }

    /**
     * Eventually sets to the given value.
     *
     * @param newValue the new value
     * @since 1.6
     */
    public final void lazySet(V newValue) {
        unsafe.putOrderedObject(this, valueOffset, newValue);
    }

    /**
     * Atomically sets the value to the given updated value
     * if the current value {@code ==} the expected value.
     * @param expect the expected value
     * @param update the new value
     * @return true if successful. False return indicates that
     * the actual value was not equal to the expected value.
     */
    public final boolean compareAndSet(V expect, V update) {
        return unsafe.compareAndSwapObject(this, valueOffset, expect, update);
    }

    /**
     * Atomically sets the value to the given updated value
     * if the current value {@code ==} the expected value.
     *
     * <p><a href="package-summary.html#weakCompareAndSet">May fail
     * spuriously and does not provide ordering guarantees</a>, so is
     * only rarely an appropriate alternative to {@code compareAndSet}.
     *
     * @param expect the expected value
     * @param update the new value
     * @return true if successful
     */
    public final boolean weakCompareAndSet(V expect, V update) {
        return unsafe.compareAndSwapObject(this, valueOffset, expect, update);
    }

    /**
     * Atomically sets to the given value and returns the old value.
     *
     * @param newValue the new value
     * @return the previous value
     */
    public final V getAndSet(V newValue) {
        while (true) {
            V x = get();
            if (compareAndSet(x, newValue))
                return x;
        }
    }

    /**
     * Returns the String representation of the current value.
     * @return the String representation of the current value
     */
    public String toString() {
        return String.valueOf(get());
    }

}
Revision:	1.3
Committed:	Mon Mar 4 16:09:25 2013 UTC (11 years, 4 months ago) by jsr166
Branch:	MAIN
Changes since 1.2:	+3 -3 lines
Log Message:	improve javadoc anchored text
#	User	Rev	Content
1	dl	1.1	/*
2			* Written by Doug Lea with assistance from members of JCP JSR-166
3			* Expert Group and released to the public domain, as explained at
4			* http://creativecommons.org/publicdomain/zero/1.0/
5			*/
6
7			package java.util.concurrent.atomic;
8			import sun.misc.Unsafe;
9
10			/**
11			* An object reference that may be updated atomically. See the {@link
12			* java.util.concurrent.atomic} package specification for description
13			* of the properties of atomic variables.
14			* @since 1.5
15			* @author Doug Lea
16			* @param <V> The type of object referred to by this reference
17			*/
18			public class AtomicReference<V> implements java.io.Serializable {
19			private static final long serialVersionUID = -1848883965231344442L;
20
21			private static final Unsafe unsafe = Unsafe.getUnsafe();
22			private static final long valueOffset;
23
24			static {
25			try {
26			valueOffset = unsafe.objectFieldOffset
27			(AtomicReference.class.getDeclaredField("value"));
28			} catch (Exception ex) { throw new Error(ex); }
29			}
30
31			private volatile V value;
32
33			/**
34			* Creates a new AtomicReference with the given initial value.
35			*
36			* @param initialValue the initial value
37			*/
38			public AtomicReference(V initialValue) {
39			value = initialValue;
40			}
41
42			/**
43			* Creates a new AtomicReference with null initial value.
44			*/
45			public AtomicReference() {
46			}
47
48			/**
49			* Gets the current value.
50			*
51			* @return the current value
52			*/
53			public final V get() {
54			return value;
55			}
56
57			/**
58			* Sets to the given value.
59			*
60			* @param newValue the new value
61			*/
62			public final void set(V newValue) {
63			value = newValue;
64			}
65
66			/**
67			* Eventually sets to the given value.
68			*
69			* @param newValue the new value
70			* @since 1.6
71			*/
72			public final void lazySet(V newValue) {
73			unsafe.putOrderedObject(this, valueOffset, newValue);
74			}
75
76			/**
77			* Atomically sets the value to the given updated value
78			* if the current value {@code ==} the expected value.
79			* @param expect the expected value
80			* @param update the new value
81			* @return true if successful. False return indicates that
82			* the actual value was not equal to the expected value.
83			*/
84			public final boolean compareAndSet(V expect, V update) {
85			return unsafe.compareAndSwapObject(this, valueOffset, expect, update);
86			}
87
88			/**
89			* Atomically sets the value to the given updated value
90			* if the current value {@code ==} the expected value.
91			*
92	jsr166	1.3	* <p><a href="package-summary.html#weakCompareAndSet">May fail
93			* spuriously and does not provide ordering guarantees</a>, so is
94			* only rarely an appropriate alternative to {@code compareAndSet}.
95	dl	1.1	*
96			* @param expect the expected value
97			* @param update the new value
98	jsr166	1.2	* @return true if successful
99	dl	1.1	*/
100			public final boolean weakCompareAndSet(V expect, V update) {
101			return unsafe.compareAndSwapObject(this, valueOffset, expect, update);
102			}
103
104			/**
105			* Atomically sets to the given value and returns the old value.
106			*
107			* @param newValue the new value
108			* @return the previous value
109			*/
110			public final V getAndSet(V newValue) {
111			while (true) {
112			V x = get();
113			if (compareAndSet(x, newValue))
114			return x;
115			}
116			}
117
118			/**
119			* Returns the String representation of the current value.
120	jsr166	1.2	* @return the String representation of the current value
121	dl	1.1	*/
122			public String toString() {
123			return String.valueOf(get());
124			}
125
126			}