This API (Application Programming Interface) document has pages corresponding to the items in the navigation bar, described as follows.
76 |
77 |
78 |
79 |
80 |
Overview
81 |
The Overview page is the front page of this API document and provides a list of all packages with a summary for each. This page can also contain an overall description of the set of packages.
82 |
83 |
84 |
Package
85 |
Each package has a page that contains a list of its classes and interfaces, with a summary for each. This page can contain six categories:
86 |
87 |
Interfaces (italic)
88 |
Classes
89 |
Enums
90 |
Exceptions
91 |
Errors
92 |
Annotation Types
93 |
94 |
95 |
96 |
Class/Interface
97 |
Each class, interface, nested class and nested interface has its own separate page. Each of these pages has three sections consisting of a class/interface description, summary tables, and detailed member descriptions:
98 |
99 |
Class inheritance diagram
100 |
Direct Subclasses
101 |
All Known Subinterfaces
102 |
All Known Implementing Classes
103 |
Class/interface declaration
104 |
Class/interface description
105 |
106 |
107 |
Nested Class Summary
108 |
Field Summary
109 |
Constructor Summary
110 |
Method Summary
111 |
112 |
113 |
Field Detail
114 |
Constructor Detail
115 |
Method Detail
116 |
117 |
Each summary entry contains the first sentence from the detailed description for that item. The summary entries are alphabetical, while the detailed descriptions are in the order they appear in the source code. This preserves the logical groupings established by the programmer.
118 |
119 |
120 |
Annotation Type
121 |
Each annotation type has its own separate page with the following sections:
122 |
123 |
Annotation Type declaration
124 |
Annotation Type description
125 |
Required Element Summary
126 |
Optional Element Summary
127 |
Element Detail
128 |
129 |
130 |
131 |
Enum
132 |
Each enum has its own separate page with the following sections:
133 |
134 |
Enum declaration
135 |
Enum description
136 |
Enum Constant Summary
137 |
Enum Constant Detail
138 |
139 |
140 |
141 |
Use
142 |
Each documented package, class and interface has its own Use page. This page describes what packages, classes, methods, constructors and fields use any part of the given class or package. Given a class or interface A, its Use page includes subclasses of A, fields declared as A, methods that return A, and methods and constructors with parameters of type A. You can access this page by first going to the package, class or interface, then clicking on the "Use" link in the navigation bar.
143 |
144 |
145 |
Tree (Class Hierarchy)
146 |
There is a Class Hierarchy page for all packages, plus a hierarchy for each package. Each hierarchy page contains a list of classes and a list of interfaces. The classes are organized by inheritance structure starting with java.lang.Object. The interfaces do not inherit from java.lang.Object.
147 |
148 |
When viewing the Overview page, clicking on "Tree" displays the hierarchy for all packages.
149 |
When viewing a particular package, class or interface page, clicking "Tree" displays the hierarchy for only that package.
150 |
151 |
152 |
153 |
Deprecated API
154 |
The Deprecated API page lists all of the API that have been deprecated. A deprecated API is not recommended for use, generally due to improvements, and a replacement API is usually given. Deprecated APIs may be removed in future implementations.
155 |
156 |
157 |
Index
158 |
The Index contains an alphabetic list of all classes, interfaces, constructors, methods, and fields.
159 |
160 |
161 |
Prev/Next
162 |
These links take you to the next or previous class, interface, package, or related page.
163 |
164 |
165 |
Frames/No Frames
166 |
These links show and hide the HTML frames. All pages are available with or without frames.
167 |
168 |
169 |
All Classes
170 |
The All Classes link shows all classes and interfaces except non-static nested types.
171 |
172 |
173 |
Serialized Form
174 |
Each serializable or externalizable class has a description of its serialization fields and methods. This information is of interest to re-implementors, not to developers using the API. While there is no link in the navigation bar, you can get to this information by going to any serialized class and clicking "Serialized Form" in the "See also" section of the class description.
public static interface CompletableFuture.AsynchronousCompletionTask
104 |
A marker interface identifying asynchronous tasks produced by
105 | async methods. This may be useful for monitoring,
106 | debugging, and tracking asynchronous activities.
A Future that may be explicitly completed (setting its
107 | value and status), and may be used as a CompletionStage,
108 | supporting dependent functions and actions that trigger upon its
109 | completion.
Backport of the Java 9 CompletableFuture API (JEP 266) for Java 8.
In addition, it contains a Java 8 version of the new Java 9 reactive-streams Flow and SubmissionPublisher API (JEP 266) and of the new Java 9 Collections factory methods (JEP 269)
24 |
25 |
26 |
27 |
28 |
29 |
30 |
31 |
32 |
33 |
Javadoc online
34 |
35 |
See the online Javadoc for more details about the API
This is a value-based
35 | * class; use of identity-sensitive operations (including reference equality
36 | * ({@code ==}), identity hash code, or synchronization) on instances of
37 | * {@code KeyValueHolder} may have unpredictable results and should be avoided.
38 | *
39 | *
API Note:
40 | * This class is not public. Instances can be created using the
41 | * {@link Maps#entry Map.entry(k, v)} factory method, which is public.
42 | *
43 | *
This class differs from AbstractMap.SimpleImmutableEntry in the following ways:
44 | * it is not serializable, it is final, and its key and value must be non-null.
45 | *
46 | * @param the key type
47 | * @param the value type
48 | *
49 | * @see Maps#ofEntries Maps.ofEntries()
50 | * @since 9
51 | */
52 | final class KeyValueHolder implements Map.Entry {
53 | final K key;
54 | final V value;
55 |
56 | KeyValueHolder(K k, V v) {
57 | key = Objects.requireNonNull(k);
58 | value = Objects.requireNonNull(v);
59 | }
60 |
61 | /**
62 | * Gets the key from this holder.
63 | *
64 | * @return the key
65 | */
66 | @Override
67 | public K getKey() {
68 | return key;
69 | }
70 |
71 | /**
72 | * Gets the value from this holder.
73 | *
74 | * @return the value
75 | */
76 | @Override
77 | public V getValue() {
78 | return value;
79 | }
80 |
81 | /**
82 | * Throws {@link UnsupportedOperationException}.
83 | *
84 | * @param value ignored
85 | * @return never returns normally
86 | */
87 | @Override
88 | public V setValue(V value) {
89 | throw new UnsupportedOperationException("not supported");
90 | }
91 |
92 | /**
93 | * Compares the specified object with this entry for equality.
94 | * Returns {@code true} if the given object is also a map entry and
95 | * the two entries' keys and values are equal. Note that key and
96 | * value are non-null, so equals() can be called safely on them.
97 | */
98 | @Override
99 | public boolean equals(Object o) {
100 | if (!(o instanceof Map.Entry))
101 | return false;
102 | Map.Entry e = (Map.Entry) o;
103 | return key.equals(e.getKey()) && value.equals(e.getValue());
104 | }
105 |
106 | /**
107 | * Returns the hash code value for this map entry. The hash code
108 | * is {@code key.hashCode() ^ value.hashCode()}. Note that key and
109 | * value are non-null, so hashCode() can be called safely on them.
110 | */
111 | @Override
112 | public int hashCode() {
113 | return key.hashCode() ^ value.hashCode();
114 | }
115 |
116 | /**
117 | * Returns a String representation of this map entry. This
118 | * implementation returns the string representation of this
119 | * entry's key followed by the equals character ("{@code =}")
120 | * followed by the string representation of this entry's value.
121 | *
122 | * @return a String representation of this map entry
123 | */
124 | @Override
125 | public String toString() {
126 | return key + "=" + value;
127 | }
128 | }
129 |
--------------------------------------------------------------------------------
/src/main/java/java9/util/concurrent/ForkJoinWorkerThread.java:
--------------------------------------------------------------------------------
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 | * Any changes or additions made by the maintainers of the
8 | * streamsupport (https://github.com/stefan-zobel/streamsupport)
9 | * or retrostreams (https://github.com/retrostreams) libraries are
10 | * also released to the public domain, as explained at
11 | * https://creativecommons.org/publicdomain/zero/1.0/
12 | */
13 | package java9.util.concurrent;
14 |
15 | import java.security.AccessControlContext;
16 | import java.security.AccessController;
17 | import java.security.PrivilegedAction;
18 | import java.security.ProtectionDomain;
19 |
20 | /**
21 | * A thread managed by a {@link ForkJoinPool}, which executes
22 | * {@link ForkJoinTask}s.
23 | * This class is subclassable solely for the sake of adding
24 | * functionality -- there are no overridable methods dealing with
25 | * scheduling or execution. However, you can override initialization
26 | * and termination methods surrounding the main task processing loop.
27 | * If you do create such a subclass, you will also need to supply a
28 | * custom {@link ForkJoinPool.ForkJoinWorkerThreadFactory} to
29 | *
30 | * use it in a {@code ForkJoinPool}.
31 | *
32 | * @since 1.7
33 | * @author Doug Lea
34 | */
35 | public class ForkJoinWorkerThread extends Thread {
36 | // CVS rev. 1.78
37 | /*
38 | * ForkJoinWorkerThreads are managed by ForkJoinPools and perform
39 | * ForkJoinTasks. For explanation, see the internal documentation
40 | * of class ForkJoinPool.
41 | *
42 | * This class just maintains links to its pool and WorkQueue. The
43 | * pool field is set immediately upon construction, but the
44 | * workQueue field is not set until a call to registerWorker
45 | * completes. This leads to a visibility race, that is tolerated
46 | * by requiring that the workQueue field is only accessed by the
47 | * owning thread.
48 | *
49 | * Support for (non-public) subclass InnocuousForkJoinWorkerThread
50 | * requires that we break quite a lot of encapsulation (via helper
51 | * methods in ThreadLocalRandom) both here and in the subclass to
52 | * access and set Thread fields.
53 | */
54 |
55 | // A placeholder name until a useful name can be set in registerWorker
56 | private static final String NAME_PLACEHOLDER = "aForkJoinWorkerThread";
57 |
58 | final ForkJoinPool pool; // the pool this thread works in
59 | final ForkJoinPool.WorkQueue workQueue; // work-stealing mechanics
60 |
61 | /**
62 | * Creates a ForkJoinWorkerThread operating in the given pool.
63 | *
64 | * @param pool the pool this thread works in
65 | * @throws NullPointerException if pool is null
66 | */
67 | protected ForkJoinWorkerThread(ForkJoinPool pool) {
68 | // Use a placeholder until a useful name can be set in registerWorker
69 | super(NAME_PLACEHOLDER);
70 | this.pool = pool;
71 | this.workQueue = pool.registerWorker(this);
72 | }
73 |
74 | /**
75 | * Version for use by the default pool. Supports setting the
76 | * context class loader. This is a separate constructor to avoid
77 | * affecting the protected constructor.
78 | */
79 | ForkJoinWorkerThread(ForkJoinPool pool, ClassLoader ccl) {
80 | super(NAME_PLACEHOLDER);
81 | TLRandom.setContextClassLoader(this, ccl); // java9-concurrent-backport changed
82 | this.pool = pool;
83 | this.workQueue = pool.registerWorker(this);
84 | }
85 |
86 | /**
87 | * Version for InnocuousForkJoinWorkerThread.
88 | */
89 | ForkJoinWorkerThread(ForkJoinPool pool,
90 | ClassLoader ccl,
91 | ThreadGroup threadGroup,
92 | AccessControlContext acc) {
93 | super(threadGroup, NAME_PLACEHOLDER);
94 | super.setContextClassLoader(ccl);
95 | TLRandom.setInheritedAccessControlContext(this, acc);
96 | TLRandom.eraseThreadLocals(this); // clear before registering
97 | this.pool = pool;
98 | this.workQueue = pool.registerWorker(this);
99 | }
100 |
101 | /**
102 | * Returns the pool hosting this thread.
103 | *
104 | * @return the pool
105 | */
106 | public ForkJoinPool getPool() {
107 | return pool;
108 | }
109 |
110 | /**
111 | * Returns the unique index number of this thread in its pool.
112 | * The returned value ranges from zero to the maximum number of
113 | * threads (minus one) that may exist in the pool, and does not
114 | * change during the lifetime of the thread. This method may be
115 | * useful for applications that track status or collect results
116 | * per-worker-thread rather than per-task.
117 | *
118 | * @return the index number
119 | */
120 | public int getPoolIndex() {
121 | return workQueue.getPoolIndex();
122 | }
123 |
124 | /**
125 | * Initializes internal state after construction but before
126 | * processing any tasks. If you override this method, you must
127 | * invoke {@code super.onStart()} at the beginning of the method.
128 | * Initialization requires care: Most fields must have legal
129 | * default values, to ensure that attempted accesses from other
130 | * threads work correctly even before this thread starts
131 | * processing tasks.
132 | */
133 | protected void onStart() {
134 | }
135 |
136 | /**
137 | * Performs cleanup associated with termination of this worker
138 | * thread. If you override this method, you must invoke
139 | * {@code super.onTermination} at the end of the overridden method.
140 | *
141 | * @param exception the exception causing this thread to abort due
142 | * to an unrecoverable error, or {@code null} if completed normally
143 | */
144 | protected void onTermination(Throwable exception) {
145 | }
146 |
147 | /**
148 | * This method is required to be public, but should never be
149 | * called explicitly. It performs the main run loop to execute
150 | * {@link ForkJoinTask}s.
151 | */
152 | public void run() {
153 | if (workQueue.array == null) { // only run once
154 | Throwable exception = null;
155 | try {
156 | onStart();
157 | pool.runWorker(workQueue);
158 | } catch (Throwable ex) {
159 | exception = ex;
160 | } finally {
161 | try {
162 | onTermination(exception);
163 | } catch (Throwable ex) {
164 | if (exception == null) {
165 | exception = ex;
166 | }
167 | } finally {
168 | pool.deregisterWorker(this, exception);
169 | }
170 | }
171 | }
172 | }
173 |
174 | /**
175 | * Non-public hook method for InnocuousForkJoinWorkerThread.
176 | */
177 | void afterTopLevelExec() {
178 | }
179 |
180 | /**
181 | * A worker thread that has no permissions, is not a member of any
182 | * user-defined ThreadGroup, uses the system class loader as
183 | * thread context class loader, and erases all ThreadLocals after
184 | * running each top-level task.
185 | */
186 | static final class InnocuousForkJoinWorkerThread extends ForkJoinWorkerThread {
187 | /** The ThreadGroup for all InnocuousForkJoinWorkerThreads */
188 | private static final ThreadGroup innocuousThreadGroup =
189 | AccessController.doPrivileged(new PrivilegedAction() {
190 | public ThreadGroup run() {
191 | ThreadGroup group = Thread.currentThread().getThreadGroup();
192 | for (ThreadGroup p; (p = group.getParent()) != null; )
193 | group = p;
194 | return new ThreadGroup(group, "InnocuousForkJoinWorkerThreadGroup");
195 | }});
196 |
197 | /** An AccessControlContext supporting no privileges */
198 | private static final AccessControlContext INNOCUOUS_ACC =
199 | new AccessControlContext(
200 | new ProtectionDomain[] { new ProtectionDomain(null, null) });
201 |
202 | InnocuousForkJoinWorkerThread(ForkJoinPool pool) {
203 | super(pool,
204 | ClassLoader.getSystemClassLoader(),
205 | innocuousThreadGroup,
206 | INNOCUOUS_ACC);
207 | }
208 |
209 | @Override // to erase ThreadLocals
210 | void afterTopLevelExec() {
211 | TLRandom.eraseThreadLocals(this);
212 | }
213 |
214 | @Override // to silently fail
215 | public void setUncaughtExceptionHandler(UncaughtExceptionHandler x) { }
216 |
217 | @Override // paranoically
218 | public void setContextClassLoader(ClassLoader cl) {
219 | if (cl != null && ClassLoader.getSystemClassLoader() != cl)
220 | throw new SecurityException("setContextClassLoader");
221 | }
222 | }
223 | }
224 |
--------------------------------------------------------------------------------
/src/main/java/java9/util/concurrent/TLRandom.java:
--------------------------------------------------------------------------------
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 | * Any changes or additions made by the maintainers of the
8 | * streamsupport (https://github.com/stefan-zobel/streamsupport)
9 | * or retrostreams (https://github.com/retrostreams) libraries are
10 | * also released to the public domain, as explained at
11 | * https://creativecommons.org/publicdomain/zero/1.0/
12 | */
13 | package java9.util.concurrent;
14 |
15 | import java.security.AccessControlContext;
16 | import java.security.PrivilegedAction;
17 | import java.util.Objects;
18 | import java.util.concurrent.atomic.AtomicInteger;
19 | import java.util.concurrent.atomic.AtomicLong;
20 |
21 | /**
22 | * A random number generator isolated to the current thread.
23 | *
24 | * @since 1.7
25 | * @author Doug Lea
26 | */
27 | final class TLRandom {
28 | // CVS rev. 1.63
29 |
30 | private static long mix64(long z) {
31 | z = (z ^ (z >>> 33)) * 0xff51afd7ed558ccdL;
32 | z = (z ^ (z >>> 33)) * 0xc4ceb9fe1a85ec53L;
33 | return z ^ (z >>> 33);
34 | }
35 |
36 | private static int mix32(long z) {
37 | z = (z ^ (z >>> 33)) * 0xff51afd7ed558ccdL;
38 | return (int) (((z ^ (z >>> 33)) * 0xc4ceb9fe1a85ec53L) >>> 32);
39 | }
40 |
41 | private TLRandom() {
42 | }
43 |
44 | /**
45 | * Initialize Thread fields for the current thread. Called only
46 | * when Thread.threadLocalRandomProbe is zero, indicating that a
47 | * thread local seed value needs to be generated. Note that even
48 | * though the initialization is purely thread-local, we need to
49 | * rely on (static) atomic generators to initialize the values.
50 | */
51 | static final void localInit() {
52 | int p = probeGenerator.addAndGet(PROBE_INCREMENT);
53 | int probe = (p == 0) ? 1 : p; // skip 0
54 | long seed = mix64(seeder.getAndAdd(SEEDER_INCREMENT));
55 | utilizeSeed(seed);
56 | setThreadLocalRandomProbe(probe);
57 | }
58 |
59 | // Within-package utilities
60 |
61 | /*
62 | * Descriptions of the usages of the methods below can be found in
63 | * the classes that use them. Briefly, a thread's "probe" value is
64 | * a non-zero hash code that (probably) does not collide with
65 | * other existing threads with respect to any power of two
66 | * collision space. When it does collide, it is pseudo-randomly
67 | * adjusted (using a Marsaglia XorShift). The nextSecondarySeed
68 | * method is used in the same contexts as ThreadLocalRandom, but
69 | * only for transient usages such as random adaptive spin/block
70 | * sequences for which a cheap RNG suffices and for which it could
71 | * in principle disrupt user-visible statistical properties of the
72 | * main ThreadLocalRandom if we were to use it.
73 | */
74 |
75 | /**
76 | * Returns the probe value for the current thread without forcing
77 | * initialization. Note that invoking ThreadLocalRandom.current()
78 | * can be used to force initialization on zero return.
79 | */
80 | static final int getProbe() {
81 | return getThreadLocalRandomProbe();
82 | }
83 |
84 | /**
85 | * Pseudo-randomly advances and records the given probe value for the
86 | * given thread.
87 | */
88 | static final int advanceProbe(int probe) {
89 | probe ^= probe << 13; // xorshift
90 | probe ^= probe >>> 17;
91 | probe ^= probe << 5;
92 | setThreadLocalRandomProbe(probe);
93 | return probe;
94 | }
95 |
96 | /**
97 | * Returns the pseudo-randomly initialized or updated secondary seed.
98 | */
99 | static final int nextSecondarySeed() {
100 | int r;
101 | if ((r = getThreadLocalRandomSecondarySeed()) != 0) {
102 | r ^= r << 13; // xorshift
103 | r ^= r >>> 17;
104 | r ^= r << 5;
105 | }
106 | else if ((r = mix32(seeder.getAndAdd(SEEDER_INCREMENT))) == 0) {
107 | r = 1; // avoid zero
108 | }
109 | setThreadLocalRandomSecondarySeed(r);
110 | return r;
111 | }
112 |
113 | private static void utilizeSeed(long seed) {
114 | Objects.requireNonNull(Long.valueOf(seed));
115 | }
116 |
117 | private static int getThreadLocalRandomProbe() {
118 | return U.getInt(Thread.currentThread(), PROBE);
119 | }
120 |
121 | private static void setThreadLocalRandomProbe(int probe) {
122 | U.putInt(Thread.currentThread(), PROBE, probe);
123 | }
124 |
125 | private static int getThreadLocalRandomSecondarySeed() {
126 | return U.getInt(Thread.currentThread(), SECONDARY);
127 | }
128 |
129 | private static void setThreadLocalRandomSecondarySeed(int secondary) {
130 | U.putInt(Thread.currentThread(), SECONDARY, secondary);
131 | }
132 |
133 | // Support for other package-private ThreadLocal access
134 |
135 | /**
136 | * Erases ThreadLocals by nulling out Thread maps.
137 | */
138 | static final void eraseThreadLocals(Thread thread) {
139 | U.putObject(thread, THREADLOCALS, null);
140 | U.putObject(thread, INHERITABLETHREADLOCALS, null);
141 | }
142 |
143 | static final void setInheritedAccessControlContext(Thread thread,
144 | AccessControlContext acc) {
145 | U.putOrderedObject(thread, INHERITEDACCESSCONTROLCONTEXT, acc);
146 | }
147 |
148 | static final void setContextClassLoader(Thread thread, ClassLoader ccl) {
149 | U.putObject(thread, CCL, ccl);
150 | }
151 |
152 | // Static initialization
153 |
154 | /**
155 | * The increment for generating probe values.
156 | */
157 | private static final int PROBE_INCREMENT = 0x9e3779b9;
158 |
159 | /**
160 | * The increment of seeder per new instance.
161 | */
162 | private static final long SEEDER_INCREMENT = 0xbb67ae8584caa73bL;
163 |
164 | // Unsafe mechanics
165 | private static final sun.misc.Unsafe U = UnsafeAccess.unsafe;
166 | private static final long THREADLOCALS;
167 | private static final long INHERITABLETHREADLOCALS;
168 | private static final long INHERITEDACCESSCONTROLCONTEXT;
169 | private static final long CCL;
170 | private static final long PROBE;
171 | private static final long SECONDARY;
172 | static {
173 | try {
174 | THREADLOCALS = U.objectFieldOffset(Thread.class.getDeclaredField("threadLocals"));
175 | INHERITABLETHREADLOCALS = U.objectFieldOffset(Thread.class.getDeclaredField("inheritableThreadLocals"));
176 | INHERITEDACCESSCONTROLCONTEXT = U
177 | .objectFieldOffset(Thread.class.getDeclaredField("inheritedAccessControlContext"));
178 | CCL = U.objectFieldOffset(Thread.class.getDeclaredField("contextClassLoader"));
179 | PROBE = U.objectFieldOffset(Thread.class.getDeclaredField("threadLocalRandomProbe"));
180 | SECONDARY = U.objectFieldOffset(Thread.class.getDeclaredField("threadLocalRandomSecondarySeed"));
181 | } catch (Exception e) {
182 | throw new ExceptionInInitializerError(e);
183 | }
184 | }
185 |
186 | /** Generates per-thread initialization/probe field */
187 | private static final AtomicInteger probeGenerator = new AtomicInteger();
188 |
189 | /**
190 | * The next seed for default constructors.
191 | */
192 | private static final AtomicLong seeder = new AtomicLong(
193 | mix64(System.currentTimeMillis()) ^ mix64(System.nanoTime()));
194 |
195 | // at end of to survive static initialization circularity
196 | static {
197 | if (java.security.AccessController.doPrivileged(
198 | new PrivilegedAction() {
199 | @Override
200 | public Boolean run() {
201 | return Boolean.getBoolean("java.util.secureRandomSeed");
202 | }
203 | })) {
204 | byte[] seedBytes = java.security.SecureRandom.getSeed(8);
205 | long s = (long) seedBytes[0] & 0xffL;
206 | for (int i = 1; i < 8; ++i) {
207 | s = (s << 8) | ((long) seedBytes[i] & 0xffL);
208 | }
209 | seeder.set(s);
210 | }
211 | }
212 | }
213 |
--------------------------------------------------------------------------------
/src/main/java/java9/util/concurrent/UnsafeAccess.java:
--------------------------------------------------------------------------------
1 | /*
2 | * Written by Stefan Zobel and released to the
3 | * public domain, as explained at
4 | * http://creativecommons.org/publicdomain/zero/1.0/
5 | */
6 | package java9.util.concurrent;
7 |
8 | import java.lang.reflect.Field;
9 | import sun.misc.Unsafe;
10 |
11 | class UnsafeAccess {
12 |
13 | static final Unsafe unsafe;
14 | static {
15 | try {
16 | Field field = Unsafe.class.getDeclaredField("theUnsafe");
17 | field.setAccessible(true);
18 | unsafe = (Unsafe) field.get(null);
19 | } catch (Exception e) {
20 | throw new Error(e);
21 | }
22 | }
23 |
24 | private UnsafeAccess() {
25 | }
26 | }
27 |
--------------------------------------------------------------------------------
/src/main/java/java9/util/concurrent/package-info.java:
--------------------------------------------------------------------------------
1 | /*
2 | * Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved.
3 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 | *
5 | * This code is free software; you can redistribute it and/or modify it
6 | * under the terms of the GNU General Public License version 2 only, as
7 | * published by the Free Software Foundation. Oracle designates this
8 | * particular file as subject to the "Classpath" exception as provided
9 | * by Oracle in the LICENSE file that accompanied this code.
10 | *
11 | * This code is distributed in the hope that it will be useful, but WITHOUT
12 | * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 | * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 | * version 2 for more details (a copy is included in the LICENSE file that
15 | * accompanied this code).
16 | *
17 | * You should have received a copy of the GNU General Public License version
18 | * 2 along with this work; if not, write to the Free Software Foundation,
19 | * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 | *
21 | * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 | * or visit www.oracle.com if you need additional information or have any
23 | * questions.
24 | */
25 |
26 | /**
27 | * Some of the Java 8 and Java 9 utility classes commonly used in concurrent programming.
28 | *
29 | * Covers a backport of the upgraded (JEP 266) Java 9 CompletableFuture API for Java 8.
30 | * In addition, it includes a Java 8 version of the new Java 9 (JEP 266) reactive-streams
31 | * Flow and SubmissionPublisher API for Java 8.
32 | *
33 | * See JEP 266: More Concurrency Updates.
34 | *
35 | *
Memory Consistency Properties
36 | *
37 | *
39 | * Chapter 17 of The Java™ Language Specification defines
40 | * the happens-before relation on memory operations such as reads and
41 | * writes of shared variables. The results of a write by one thread are
42 | * guaranteed to be visible to a read by another thread only if the write
43 | * operation happens-before the read operation. The {@code synchronized}
44 | * and {@code volatile} constructs, as well as the {@code Thread.start()} and
45 | * {@code Thread.join()} methods, can form happens-before relationships.
46 | * In particular:
47 | *
48 | *
49 | *
Each action in a thread happens-before every action in that thread
50 | * that comes later in the program's order.
51 | *
52 | *
An unlock ({@code synchronized} block or method exit) of a monitor
53 | * happens-before every subsequent lock ({@code synchronized} block or
54 | * method entry) of that same monitor. And because the happens-before
55 | * relation is transitive, all actions of a thread prior to unlocking
56 | * happen-before all actions subsequent to any thread locking that
57 | * monitor.
58 | *
59 | *
A write to a {@code volatile} field happens-before every
60 | * subsequent read of that same field. Writes and reads of {@code volatile}
61 | * fields have similar memory consistency effects as entering and exiting
62 | * monitors, but do not entail mutual exclusion locking.
63 | *
64 | *
A call to {@code start} on a thread happens-before any action in
65 | * the started thread.
66 | *
67 | *
All actions in a thread happen-before any other thread
68 | * successfully returns from a {@code join} on that thread.
69 | *
70 | *
71 | *
72 | * @since 9
73 | */
74 | package java9.util.concurrent;
--------------------------------------------------------------------------------
/src/main/java/java9/util/package-info.java:
--------------------------------------------------------------------------------
1 | /*
2 | * Copyright (c) 2012, 2018, Oracle and/or its affiliates. All rights reserved.
3 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 | *
5 | * This code is free software; you can redistribute it and/or modify it
6 | * under the terms of the GNU General Public License version 2 only, as
7 | * published by the Free Software Foundation. Oracle designates this
8 | * particular file as subject to the "Classpath" exception as provided
9 | * by Oracle in the LICENSE file that accompanied this code.
10 | *
11 | * This code is distributed in the hope that it will be useful, but WITHOUT
12 | * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 | * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 | * version 2 for more details (a copy is included in the LICENSE file that
15 | * accompanied this code).
16 | *
17 | * You should have received a copy of the GNU General Public License version
18 | * 2 along with this work; if not, write to the Free Software Foundation,
19 | * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 | *
21 | * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 | * or visit www.oracle.com if you need additional information or have any
23 | * questions.
24 | */
25 |
26 | /**
27 | * Provides a Java 8 backport of the
28 | * JEP 269: Convenience Factory
29 | * Methods for Collections that were introduced in Java 9.
30 | *
31 | *
33 | * An unmodifiable collection is a collection, all of whose mutator
34 | * methods are specified to throw {@code UnsupportedOperationException}. Such a
35 | * collection thus cannot be modified by calling any methods on it. For a
36 | * collection to be properly unmodifiable, any view collections derived from it
37 | * must also be unmodifiable. For example, if a List is unmodifiable, the List
38 | * returned by {@link java.util.List#subList List.subList} is also unmodifiable.
39 | *
40 | *
41 | * An unmodifiable collection is not necessarily immutable. If the contained
42 | * elements are mutable, the entire collection is clearly mutable, even though
43 | * it might be unmodifiable. For example, consider two unmodifiable lists
44 | * containing mutable elements. The result of calling
45 | * {@code list1.equals(list2)} might differ from one call to the next if the
46 | * elements had been mutated, even though both lists are unmodifiable. However,
47 | * if an unmodifiable collection contains all immutable elements, it can be
48 | * considered effectively immutable.
49 | *
50 | *
52 | * Some classes, such as {@code java.util.Optional}, are value-based. Instances
53 | * of a value-based class:
54 | *
55 | *
56 | *
are final and immutable (though may contain references to mutable objects);
57 | *
have implementations of equals, hashCode, and toString which are computed
58 | * solely from the instance's state and not from its identity or the state of
59 | * any other object or variable;
60 | *
make no use of identity-sensitive operations such as reference equality
61 | * (==) between instances, identity hash code of instances, or synchronization
62 | * on an instances's intrinsic lock;
63 | *
are considered equal solely based on equals(), not based on reference
64 | * equality (==);
65 | *
do not have accessible constructors, but are instead instantiated through
66 | * factory methods which make no committment as to the identity of returned
67 | * instances;
68 | *
are freely substitutable when equal, meaning that interchanging any two
69 | * instances x and y that are equal according to equals() in any computation or
70 | * method invocation should produce no visible change in behavior.
71 | *
72 | *
73 | * A program may produce unpredictable results if it attempts to distinguish two
74 | * references to equal values of a value-based class, whether directly via
75 | * reference equality or indirectly via an appeal to synchronization, identity
76 | * hashing, serialization, or any other identity-sensitive mechanism. Use of such
77 | * identity-sensitive operations on instances of value-based classes may have
78 | * unpredictable effects and should be avoided.
79 | *