140 * structured cases where child threads are started and terminate within the bounded
141 * period of execution by a parent thread. When using a {@link StructuredTaskScope},
142 * scoped value bindings are <em>captured</em> when creating a {@code StructuredTaskScope}
143 * and inherited by all threads started in that task scope with the
144 * {@link StructuredTaskScope#fork(java.util.concurrent.Callable) fork} method.
145 *
146 * <p> A {@code ScopedValue} that is shared across threads requires that the value be an
147 * immutable object or for all access to the value to be appropriately synchronized.
148 *
149 * <p> In the following example, the {@code ScopedValue} {@code NAME} is bound to the
150 * value "{@code duke}" for the execution of a runnable operation. The code in the {@code
151 * run} method creates a {@code StructuredTaskScope} that forks three tasks. Code executed
152 * directly or indirectly by these threads running {@code childTask1()}, {@code childTask2()},
153 * and {@code childTask3()} that invokes {@code NAME.get()} will read the value
154 * "{@code duke}".
155 *
156 * {@snippet lang=java :
157 * private static final ScopedValue<String> NAME = ScopedValue.newInstance();
158
159 * ScopedValue.where(NAME, "duke").run(() -> {
160 * try (var scope = new StructuredTaskScope<String>()) {
161 *
162 * // @link substring="fork" target="StructuredTaskScope#fork(java.util.concurrent.Callable)" :
163 * scope.fork(() -> childTask1());
164 * scope.fork(() -> childTask2());
165 * scope.fork(() -> childTask3());
166 *
167 * // @link substring="join" target="StructuredTaskScope#join()" :
168 * scope.join();
169 *
170 * ..
171 * }
172 * });
173 * }
174 *
175 * <p> Unless otherwise specified, passing a {@code null} argument to a method in this
176 * class will cause a {@link NullPointerException} to be thrown.
177 *
178 * @apiNote
179 * A {@code ScopedValue} should be preferred over a {@link ThreadLocal} for cases where
180 * the goal is "one-way transmission" of data without using method parameters. While a
|
140 * structured cases where child threads are started and terminate within the bounded
141 * period of execution by a parent thread. When using a {@link StructuredTaskScope},
142 * scoped value bindings are <em>captured</em> when creating a {@code StructuredTaskScope}
143 * and inherited by all threads started in that task scope with the
144 * {@link StructuredTaskScope#fork(java.util.concurrent.Callable) fork} method.
145 *
146 * <p> A {@code ScopedValue} that is shared across threads requires that the value be an
147 * immutable object or for all access to the value to be appropriately synchronized.
148 *
149 * <p> In the following example, the {@code ScopedValue} {@code NAME} is bound to the
150 * value "{@code duke}" for the execution of a runnable operation. The code in the {@code
151 * run} method creates a {@code StructuredTaskScope} that forks three tasks. Code executed
152 * directly or indirectly by these threads running {@code childTask1()}, {@code childTask2()},
153 * and {@code childTask3()} that invokes {@code NAME.get()} will read the value
154 * "{@code duke}".
155 *
156 * {@snippet lang=java :
157 * private static final ScopedValue<String> NAME = ScopedValue.newInstance();
158
159 * ScopedValue.where(NAME, "duke").run(() -> {
160 * // @link substring="open" target="StructuredTaskScope#open()" :
161 * try (var scope = StructuredTaskScope.open()) {
162 *
163 * // @link substring="fork" target="StructuredTaskScope#fork(java.util.concurrent.Callable)" :
164 * scope.fork(() -> childTask1());
165 * scope.fork(() -> childTask2());
166 * scope.fork(() -> childTask3());
167 *
168 * // @link substring="join" target="StructuredTaskScope#join()" :
169 * scope.join();
170 *
171 * ..
172 * }
173 * });
174 * }
175 *
176 * <p> Unless otherwise specified, passing a {@code null} argument to a method in this
177 * class will cause a {@link NullPointerException} to be thrown.
178 *
179 * @apiNote
180 * A {@code ScopedValue} should be preferred over a {@link ThreadLocal} for cases where
181 * the goal is "one-way transmission" of data without using method parameters. While a
|