/usr/share/doc/libbackport-util-concurrent-java/api/edu/emory/mathcs/backport/java/util/concurrent/atomic/package-summary.html is in libbackport-util-concurrent-java-doc 3.1-3build1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!-- NewPage -->
<html lang="en">
<head>
<!-- Generated by javadoc (version 1.7.0_03) on Fri May 18 11:21:08 UTC 2012 -->
<title>edu.emory.mathcs.backport.java.util.concurrent.atomic</title>
<meta name="date" content="2012-05-18">
<link rel="stylesheet" type="text/css" href="../../../../../../../../stylesheet.css" title="Style">
</head>
<body>
<script type="text/javascript"><!--
if (location.href.indexOf('is-external=true') == -1) {
parent.document.title="edu.emory.mathcs.backport.java.util.concurrent.atomic";
}
//-->
</script>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
<!-- ========= START OF TOP NAVBAR ======= -->
<div class="topNav"><a name="navbar_top">
<!-- -->
</a><a href="#skip-navbar_top" title="Skip navigation links"></a><a name="navbar_top_firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../../../../../../overview-summary.html">Overview</a></li>
<li class="navBarCell1Rev">Package</li>
<li>Class</li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../../../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../../../../../../index-all.html">Index</a></li>
<li><a href="../../../../../../../../help-doc.html">Help</a></li>
</ul>
</div>
<div class="subNav">
<ul class="navList">
<li><a href="../../../../../../../../edu/emory/mathcs/backport/java/util/concurrent/package-summary.html">Prev Package</a></li>
<li><a href="../../../../../../../../edu/emory/mathcs/backport/java/util/concurrent/helpers/package-summary.html">Next Package</a></li>
</ul>
<ul class="navList">
<li><a href="../../../../../../../../index.html?edu/emory/mathcs/backport/java/util/concurrent/atomic/package-summary.html" target="_top">Frames</a></li>
<li><a href="package-summary.html" target="_top">No Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_top">
<li><a href="../../../../../../../../allclasses-noframe.html">All Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_top");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<a name="skip-navbar_top">
<!-- -->
</a></div>
<!-- ========= END OF TOP NAVBAR ========= -->
<div class="header">
<h1 title="Package" class="title">Package edu.emory.mathcs.backport.java.util.concurrent.atomic</h1>
<div class="docSummary">
<div class="block">A small toolkit of classes that support lock-free thread-safe
programming on single variables.</div>
</div>
<p>See: <a href="#package_description">Description</a></p>
</div>
<div class="contentContainer">
<ul class="blockList">
<li class="blockList">
<table class="packageSummary" border="0" cellpadding="3" cellspacing="0" summary="Class Summary table, listing classes, and an explanation">
<caption><span>Class Summary</span><span class="tabEnd"> </span></caption>
<tr>
<th class="colFirst" scope="col">Class</th>
<th class="colLast" scope="col">Description</th>
</tr>
<tbody>
<tr class="altColor">
<td class="colFirst"><a href="../../../../../../../../edu/emory/mathcs/backport/java/util/concurrent/atomic/AtomicBoolean.html" title="class in edu.emory.mathcs.backport.java.util.concurrent.atomic">AtomicBoolean</a></td>
<td class="colLast">
<div class="block">A <code>boolean</code> value that may be updated atomically.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><a href="../../../../../../../../edu/emory/mathcs/backport/java/util/concurrent/atomic/AtomicInteger.html" title="class in edu.emory.mathcs.backport.java.util.concurrent.atomic">AtomicInteger</a></td>
<td class="colLast">
<div class="block">An <code>int</code> value that may be updated atomically.</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><a href="../../../../../../../../edu/emory/mathcs/backport/java/util/concurrent/atomic/AtomicIntegerArray.html" title="class in edu.emory.mathcs.backport.java.util.concurrent.atomic">AtomicIntegerArray</a></td>
<td class="colLast">
<div class="block">An <code>int</code> array in which elements may be updated atomically.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><a href="../../../../../../../../edu/emory/mathcs/backport/java/util/concurrent/atomic/AtomicLong.html" title="class in edu.emory.mathcs.backport.java.util.concurrent.atomic">AtomicLong</a></td>
<td class="colLast">
<div class="block">A <code>long</code> value that may be updated atomically.</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><a href="../../../../../../../../edu/emory/mathcs/backport/java/util/concurrent/atomic/AtomicLongArray.html" title="class in edu.emory.mathcs.backport.java.util.concurrent.atomic">AtomicLongArray</a></td>
<td class="colLast">
<div class="block">A <code>long</code> array in which elements may be updated atomically.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><a href="../../../../../../../../edu/emory/mathcs/backport/java/util/concurrent/atomic/AtomicMarkableReference.html" title="class in edu.emory.mathcs.backport.java.util.concurrent.atomic">AtomicMarkableReference</a></td>
<td class="colLast">
<div class="block">An <code>AtomicMarkableReference</code> maintains an object reference
along with a mark bit, that can be updated atomically.</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><a href="../../../../../../../../edu/emory/mathcs/backport/java/util/concurrent/atomic/AtomicReference.html" title="class in edu.emory.mathcs.backport.java.util.concurrent.atomic">AtomicReference</a></td>
<td class="colLast">
<div class="block">An object reference that may be updated atomically.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><a href="../../../../../../../../edu/emory/mathcs/backport/java/util/concurrent/atomic/AtomicReferenceArray.html" title="class in edu.emory.mathcs.backport.java.util.concurrent.atomic">AtomicReferenceArray</a></td>
<td class="colLast">
<div class="block">An array of object references in which elements may be updated
atomically.</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><a href="../../../../../../../../edu/emory/mathcs/backport/java/util/concurrent/atomic/AtomicStampedReference.html" title="class in edu.emory.mathcs.backport.java.util.concurrent.atomic">AtomicStampedReference</a></td>
<td class="colLast">
<div class="block">An <code>AtomicStampedReference</code> maintains an object reference
along with an integer "stamp", that can be updated atomically.</div>
</td>
</tr>
</tbody>
</table>
</li>
</ul>
<a name="package_description">
<!-- -->
</a>
<h2 title="Package edu.emory.mathcs.backport.java.util.concurrent.atomic Description">Package edu.emory.mathcs.backport.java.util.concurrent.atomic Description</h2>
<div class="block">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 <tt>volatile</tt> values, fields, and
array elements to those that also provide an atomic conditional update
operation of the form:
<pre>
boolean compareAndSet(expectedValue, updateValue);
</pre>
<p> This method (which varies in argument types across different
classes) atomically sets a variable to the <tt>updateValue</tt> if it
currently holds the <tt>expectedValue</tt>, reporting <tt>true</tt> 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 <tt>weakCompareAndSet</tt> 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 <a href="../../../../../../../../edu/emory/mathcs/backport/java/util/concurrent/atomic/AtomicBoolean.html" title="class in edu.emory.mathcs.backport.java.util.concurrent.atomic"><code>AtomicBoolean</code></a>, <a href="../../../../../../../../edu/emory/mathcs/backport/java/util/concurrent/atomic/AtomicInteger.html" title="class in edu.emory.mathcs.backport.java.util.concurrent.atomic"><code>AtomicInteger</code></a>, <a href="../../../../../../../../edu/emory/mathcs/backport/java/util/concurrent/atomic/AtomicLong.html" title="class in edu.emory.mathcs.backport.java.util.concurrent.atomic"><code>AtomicLong</code></a>, and <a href="../../../../../../../../edu/emory/mathcs/backport/java/util/concurrent/atomic/AtomicReference.html" title="class in edu.emory.mathcs.backport.java.util.concurrent.atomic"><code>AtomicReference</code></a> 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 <tt>AtomicLong</tt> and <tt>AtomicInteger</tt> provide atomic
increment methods. One application is to generate sequence numbers,
as in:
<pre>
class Sequencer {
private final AtomicLong sequenceNumber
= new AtomicLong(0);
public long next() {
return sequenceNumber.getAndIncrement();
}
}
</pre>
<p>The memory effects for accesses and updates of atomics generally
follow the rules for volatiles, as stated in <a
href="http://java.sun.com/docs/books/jls/"> The Java Language
Specification, Third Edition (17.4 Memory Model)</a>:
<ul>
<li> <tt>get</tt> has the memory effects of reading a
<tt>volatile</tt> variable.
<li> <tt>set</tt> has the memory effects of writing (assigning) a
<tt>volatile</tt> variable.
<li> <tt>lazySet</tt> has the memory effects of writing (assigning)
a <tt>volatile</tt> variable except that it permits reorderings with
subsequent (but not previous) memory actions that do not themselves
impose reordering constraints with ordinary non-<tt>volatile</tt>
writes. Among other usage contexts, <tt>lazySet</tt> may apply when
nulling out, for the sake of garbage collection, a reference that is
never accessed again.
<li><tt>weakCompareAndSet</tt> atomically reads and conditionally
writes a variable but does <em>not</em>
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 <tt>weakCompareAndSet</tt>.
<li> <tt>compareAndSet</tt>
and all other read-and-update operations such as <tt>getAndIncrement</tt>
have the memory effects of both reading and
writing <tt>volatile</tt> variables.
</ul>
<p>In addition to classes representing single values, this package
contains <em>Updater</em> classes that can be used to obtain
<tt>compareAndSet</tt> operations on any selected <tt>volatile</tt>
field of any selected class. <code>edu.emory.mathcs.backport.java.util.concurrent.atomic.AtomicReferenceFieldUpdater</code>, <code>edu.emory.mathcs.backport.java.util.concurrent.atomic.AtomicIntegerFieldUpdater</code>, and <code>edu.emory.mathcs.backport.java.util.concurrent.atomic.AtomicLongFieldUpdater</code> are
reflection-based utilities that provide access to the associated field
types. These are mainly of use in atomic data structures in which
several <tt>volatile</tt> 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 <a href="../../../../../../../../edu/emory/mathcs/backport/java/util/concurrent/atomic/AtomicIntegerArray.html" title="class in edu.emory.mathcs.backport.java.util.concurrent.atomic"><code>AtomicIntegerArray</code></a>, <a href="../../../../../../../../edu/emory/mathcs/backport/java/util/concurrent/atomic/AtomicLongArray.html" title="class in edu.emory.mathcs.backport.java.util.concurrent.atomic"><code>AtomicLongArray</code></a>, and <a href="../../../../../../../../edu/emory/mathcs/backport/java/util/concurrent/atomic/AtomicReferenceArray.html" title="class in edu.emory.mathcs.backport.java.util.concurrent.atomic"><code>AtomicReferenceArray</code></a> classes further
extend atomic operation support to arrays of these types. These
classes are also notable in providing <tt>volatile</tt> access
semantics for their array elements, which is not supported for
ordinary arrays.
<a name="Spurious">
<p>The atomic classes also support method <tt>weakCompareAndSet</tt>,
which has limited applicability. On some platforms, the weak version
may be more efficient than <tt>compareAndSet</tt> in the normal case,
but differs in that any given invocation of the
<tt>weakCompareAndSet</tt> method may return <tt>false</tt>
<em>spuriously</em> (that is, for no apparent reason)</a>. A
<tt>false</tt> return means only that the operation may be retried if
desired, relying on the guarantee that repeated invocation when the
variable holds <tt>expectedValue</tt> 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 <tt>weakCompareAndSet</tt> 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 <tt>weakCompareAndSet</tt>, it does
not necessarily see updates to any <em>other</em> variables that
occurred before the <tt>weakCompareAndSet</tt>. This may be
acceptable when, for example, updating performance statistics, but
rarely otherwise.
<p> The <a href="../../../../../../../../edu/emory/mathcs/backport/java/util/concurrent/atomic/AtomicMarkableReference.html" title="class in edu.emory.mathcs.backport.java.util.concurrent.atomic"><code>AtomicMarkableReference</code></a>
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 <a href="../../../../../../../../edu/emory/mathcs/backport/java/util/concurrent/atomic/AtomicStampedReference.html" title="class in edu.emory.mathcs.backport.java.util.concurrent.atomic"><code>AtomicStampedReference</code></a> 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 <tt>compareAndSet</tt> method is not a general
replacement for locking. It applies only when critical updates for an
object are confined to a <em>single</em> variable.
<p> Atomic classes are not general purpose replacements for
<tt>java.lang.Integer</tt> and related classes. They do <em>not</em>
define methods such as <tt>hashCode</tt> and
<tt>compareTo</tt>. (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 <tt>byte</tt>. In those infrequent cases where you would
like to do so, you can use an <tt>AtomicInteger</tt> to hold
<tt>byte</tt> values, and cast appropriately. You can also hold floats
using <tt>Float.floatToIntBits</tt> and <tt>Float.intBitstoFloat</tt>
conversions, and doubles using <tt>Double.doubleToLongBits</tt> and
<tt>Double.longBitsToDouble</tt> conversions.</div>
<dl><dt><span class="strong">Since:</span></dt>
<dd>1.5
</body> </html></dd></dl>
</div>
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<div class="bottomNav"><a name="navbar_bottom">
<!-- -->
</a><a href="#skip-navbar_bottom" title="Skip navigation links"></a><a name="navbar_bottom_firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../../../../../../overview-summary.html">Overview</a></li>
<li class="navBarCell1Rev">Package</li>
<li>Class</li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../../../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../../../../../../index-all.html">Index</a></li>
<li><a href="../../../../../../../../help-doc.html">Help</a></li>
</ul>
</div>
<div class="subNav">
<ul class="navList">
<li><a href="../../../../../../../../edu/emory/mathcs/backport/java/util/concurrent/package-summary.html">Prev Package</a></li>
<li><a href="../../../../../../../../edu/emory/mathcs/backport/java/util/concurrent/helpers/package-summary.html">Next Package</a></li>
</ul>
<ul class="navList">
<li><a href="../../../../../../../../index.html?edu/emory/mathcs/backport/java/util/concurrent/atomic/package-summary.html" target="_top">Frames</a></li>
<li><a href="package-summary.html" target="_top">No Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_bottom">
<li><a href="../../../../../../../../allclasses-noframe.html">All Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_bottom");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<a name="skip-navbar_bottom">
<!-- -->
</a></div>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
</body>
</html>
|