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