Java example source code file (package-info.java)

This example Java source code file (package-info.java) is included in the alvinalexander.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Learn more about this Java project at its project page.

Java - Java tags/keywords

The package-info.java Java example source code

/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

/*
 * This file is available under and governed by the GNU General Public
 * License version 2 only, as published by the Free Software Foundation.
 * However, the following notice accompanied the original version of this
 * file:
 *
 * 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/
 */

/**
 * A small toolkit of classes that support lock-free thread-safe
 * programming on single variables.  In essence, the classes in this
 * package extend the notion of {@code volatile} values, fields, and
 * array elements to those that also provide an atomic conditional update
 * operation of the form:
 *
 *  <pre> {@code boolean compareAndSet(expectedValue, updateValue);}

* * <p>This method (which varies in argument types across different * classes) atomically sets a variable to the {@code updateValue} if it * currently holds the {@code expectedValue}, reporting {@code true} on * success. The classes in this package also contain methods to get and * unconditionally set values, as well as a weaker conditional atomic * update operation {@code weakCompareAndSet} described below. * * <p>The specifications of these methods enable implementations to * employ efficient machine-level atomic instructions that are available * on contemporary processors. However on some platforms, support may * entail some form of internal locking. Thus the methods are not * strictly guaranteed to be non-blocking -- * a thread may block transiently before performing the operation. * * <p>Instances of classes * {@link java.util.concurrent.atomic.AtomicBoolean}, * {@link java.util.concurrent.atomic.AtomicInteger}, * {@link java.util.concurrent.atomic.AtomicLong}, and * {@link java.util.concurrent.atomic.AtomicReference} * each provide access and updates to a single variable of the * corresponding type. Each class also provides appropriate utility * methods for that type. For example, classes {@code AtomicLong} and * {@code AtomicInteger} provide atomic increment methods. One * application is to generate sequence numbers, as in: * * <pre> {@code * class Sequencer { * private final AtomicLong sequenceNumber * = new AtomicLong(0); * public long next() { * return sequenceNumber.getAndIncrement(); * } * }}</pre> * * <p>It is straightforward to define new utility functions that, like * {@code getAndIncrement}, apply a function to a value atomically. * For example, given some transformation * <pre> {@code long transform(long input)} * * write your utility method as follows: * <pre> {@code * long getAndTransform(AtomicLong var) { * long prev, next; * do { * prev = var.get(); * next = transform(prev); * } while (!var.compareAndSet(prev, next)); * return prev; // return next; for transformAndGet * }}</pre> * * <p>The memory effects for accesses and updates of atomics generally * follow the rules for volatiles, as stated in * <a href="http://docs.oracle.com/javase/specs/jls/se7/html/jls-17.html#jls-17.4"> * The Java Language Specification (17.4 Memory Model)</a>: * * <ul> * * <li> {@code get} has the memory effects of reading a * {@code volatile} variable. * * <li> {@code set} has the memory effects of writing (assigning) a * {@code volatile} variable. * * <li> {@code lazySet} has the memory effects of writing (assigning) * a {@code volatile} variable except that it permits reorderings with * subsequent (but not previous) memory actions that do not themselves * impose reordering constraints with ordinary non-{@code volatile} * writes. Among other usage contexts, {@code lazySet} may apply when * nulling out, for the sake of garbage collection, a reference that is * never accessed again. * * <li>{@code weakCompareAndSet} atomically reads and conditionally * writes a variable but does <em>not * create any happens-before orderings, so provides no guarantees * with respect to previous or subsequent reads and writes of any * variables other than the target of the {@code weakCompareAndSet}. * * <li> {@code compareAndSet} * and all other read-and-update operations such as {@code getAndIncrement} * have the memory effects of both reading and * writing {@code volatile} variables. * </ul> * * <p>In addition to classes representing single values, this package * contains <em>Updater classes that can be used to obtain * {@code compareAndSet} operations on any selected {@code volatile} * field of any selected class. * * {@link java.util.concurrent.atomic.AtomicReferenceFieldUpdater}, * {@link java.util.concurrent.atomic.AtomicIntegerFieldUpdater}, and * {@link java.util.concurrent.atomic.AtomicLongFieldUpdater} are * reflection-based utilities that provide access to the associated * field types. These are mainly of use in atomic data structures in * which several {@code volatile} fields of the same node (for * example, the links of a tree node) are independently subject to * atomic updates. These classes enable greater flexibility in how * and when to use atomic updates, at the expense of more awkward * reflection-based setup, less convenient usage, and weaker * guarantees. * * <p>The * {@link java.util.concurrent.atomic.AtomicIntegerArray}, * {@link java.util.concurrent.atomic.AtomicLongArray}, and * {@link java.util.concurrent.atomic.AtomicReferenceArray} classes * further extend atomic operation support to arrays of these types. * These classes are also notable in providing {@code volatile} access * semantics for their array elements, which is not supported for * ordinary arrays. * * <p id="weakCompareAndSet">The atomic classes also support method * {@code weakCompareAndSet}, which has limited applicability. On some * platforms, the weak version may be more efficient than {@code * compareAndSet} in the normal case, but differs in that any given * invocation of the {@code weakCompareAndSet} method may return {@code * false} <em>spuriously (that is, for no apparent reason). A * {@code false} return means only that the operation may be retried if * desired, relying on the guarantee that repeated invocation when the * variable holds {@code expectedValue} and no other thread is also * attempting to set the variable will eventually succeed. (Such * spurious failures may for example be due to memory contention effects * that are unrelated to whether the expected and current values are * equal.) Additionally {@code weakCompareAndSet} does not provide * ordering guarantees that are usually needed for synchronization * control. However, the method may be useful for updating counters and * statistics when such updates are unrelated to the other * happens-before orderings of a program. When a thread sees an update * to an atomic variable caused by a {@code weakCompareAndSet}, it does * not necessarily see updates to any <em>other variables that * occurred before the {@code weakCompareAndSet}. This may be * acceptable when, for example, updating performance statistics, but * rarely otherwise. * * <p>The {@link java.util.concurrent.atomic.AtomicMarkableReference} * class associates a single boolean with a reference. For example, this * bit might be used inside a data structure to mean that the object * being referenced has logically been deleted. * * The {@link java.util.concurrent.atomic.AtomicStampedReference} * class associates an integer value with a reference. This may be * used for example, to represent version numbers corresponding to * series of updates. * * <p>Atomic classes are designed primarily as building blocks for * implementing non-blocking data structures and related infrastructure * classes. The {@code compareAndSet} method is not a general * replacement for locking. It applies only when critical updates for an * object are confined to a <em>single variable. * * <p>Atomic classes are not general purpose replacements for * {@code java.lang.Integer} and related classes. They do <em>not * define methods such as {@code equals}, {@code hashCode} and * {@code compareTo}. (Because atomic variables are expected to be * mutated, they are poor choices for hash table keys.) Additionally, * classes are provided only for those types that are commonly useful in * intended applications. For example, there is no atomic class for * representing {@code byte}. In those infrequent cases where you would * like to do so, you can use an {@code AtomicInteger} to hold * {@code byte} values, and cast appropriately. * * You can also hold floats using * {@link java.lang.Float#floatToRawIntBits} and * {@link java.lang.Float#intBitsToFloat} conversions, and doubles using * {@link java.lang.Double#doubleToRawLongBits} and * {@link java.lang.Double#longBitsToDouble} conversions. * * @since 1.5 */ package java.util.concurrent.atomic;