added example of Structured Concurrency in Java 19

Author: wesleyegberto

java-19/README.md

@@ -12,6 +12,12 @@ To run each example use: `java --enable-preview --source 19 <FileName.java>`
     * definition: guard is the boolean expression, guarded pattern is the case with guard
       * guarded pattern: `case Hero h when h.getCity() == Cities.NEW_YORK`
       * guard: `h.getCity() == Cities.NEW_YORK`
+* Record patterns
+  * added suport to deconstruct record values in pattern matcher
+    * record pattern: `Point(int x, int y)`
+  * now we can use type pattern and record pattern together
+  * we can check the type and extract the record components using `instanceof` operator
+    * `o instanceOf Point(int x, int y)`
 * Virtual Threads:
   * also called user-mode threads or [fiber](https://en.wikipedia.org/wiki/Fiber_(computer_science))
   * more notes about Project Loom [here](../java-loom/)
@@ -67,12 +73,27 @@ To run each example use: `java --enable-preview --source 19 <FileName.java>`
     * `Thread.ofPlatform().start(() -> {})`;
     * **do not use** any cached method from `Executors`.
   * [here](platform-thread-vs-virtual-thread.md) is some details about the Platform Thread vs Virtual Thread examples
-* Record patterns
-  * added suport to deconstruct record values in pattern matcher
-    * record pattern: `Point(int x, int y)`
-  * now we can use type pattern and record pattern together
-  * we can check the type and extract the record components using `instanceof` operator
-    * `o instanceOf Point(int x, int y)`
+* Structured Concurrency
+  * goal is simplify multithreaded programming;
+  * treats multiple tasks running in different threads as a single unit of work:
+    * streamlining error handling and cancellation
+    * improving reliability
+    * enhancing observability
+  * steps to use:
+    * create a scope (using `StructuredTaskScope`);
+    * fork concurrent subtasks in the scope:
+      * any subtask or the scope owner can call `shutdown` to request cancelation of all remaining subtasks;
+    * scope's owner joins the scope:
+      * blocks until all subtasks either complete (sucessfully or not) or any call shutdown;
+    * after joining, handle any errors and process theirs results;
+    * close the scope (implicity when using try-with-resources).
+  * characteristics:
+    * each fork creates its own thread (by default is a virtual thread)
+    * allow nested scope (when creating a scope in a subtask)
+    * shutdown causes the threads of all forks that are still active in the scope to be interrupted
+    * when calling `close`, it propagates the the state of the unit of work (either awaits all subtasks to finish or cancel each one of them)
+  * [output from the structured concurrency example](structured-concurrency-example.md):
+
 
 ## JEPs
 

java-19/StructuredConcurrencyMotivation.java

@@ -0,0 +1,109 @@
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+
+import javax.management.RuntimeErrorException;
+
+import jdk.incubator.concurrent.StructuredTaskScope;
+
+/**
+ * This class shows an example of unstructured concurrency shown in the JEP.
+ *
+ * To run: `java --source 19 --enable-preview --add-modules jdk.incubator.concurrent StructuredConcurrencyMotivation.java`
+ */
+public class StructuredConcurrencyMotivation {
+	public static void main(String[] args) throws Exception {
+		var example = new StructuredConcurrencyMotivation();
+
+		System.out.println("\nExecutorService:");
+		try {
+			// at subtask exception, the other subtasks will continue to run
+			System.out.println(example.unstructuredHandle());
+		} catch (Exception ex) {
+			ex.printStackTrace();
+		}
+
+		System.out.println("\nStructuredTaskScope:");
+		try {
+			// at subtask failure, we can see other subtasks will be canceled (and return much earlier)
+			System.out.println(example.structuredHandle());
+		} catch (Exception ex) {
+			ex.printStackTrace();
+		}
+	}
+
+	/**
+	 * Problems:
+	 * - If findUser throws, then handle will throw when calling user.get(). fetchOrder will continue to run in its own
+	 *    thread even after handle has failed. This is a thread leak, which, at best, wastes resources;
+	 *    at worst, fetchOrder will interfere with other tasks.
+	 * - If the thread executing handle is interrupted, the interruption is not propagated to subtasks. Both the findUser
+	 *    and fetchOrder threads will leak, continuing to run even after handle has failed.
+	 * - If findUser takes a long time to execute, but fetchOrder fails in the meantime, then handle will wait unnecessarily
+	 *    for findUser by blocking on user.get() rather than canceling it. Only after findUser completes and user.get()
+	 *    returns will order.get() throw, causing handle to fail.
+	 */
+	Response unstructuredHandle() throws ExecutionException, InterruptedException {
+		var es = Executors.newCachedThreadPool();
+		try {
+			Future<String> user = es.submit(() -> findUser());
+			Future<Integer> order = es.submit(() -> fetchOrder());
+			String theUser = user.get(); // Join findUser
+			int theOrder = order.get(); // Join fetchOrder
+			return new Response(theUser, theOrder);
+		} finally {
+			es.shutdown();
+		}
+	}
+
+	/**
+	 * Benefits:
+	 * - Error handling with short-circuiting: If either findUser or fetchOrder fail, the other will be cancelled if it
+	 *    hasn't yet completed (this is managed by the cancellation policy implemented by ShutdownOnFailure;
+	 *    other policies are possible too).
+	 * - Cancellation Propagation: If the thread running handle is interrupted before or during the call to join, both
+	 *    forks will be automatically cancelled when the scope is exited.
+	 * - Clarity: The above code has a clear structure: set up the child subtasks, wait for them (either to complete
+	 *    or to becanceled), and then decide whether to succeed (and process the results of the child tasks, which are
+	 *    already finished) or fail (and the subtasks are already finished, so there's nothing more to clean up.)
+	 * - Observability: A thread dump, as described below, will clearly demonstrate the task hierarchy, with the threads
+	 *    running findUser and fetchOrder shown as children of the scope.
+	 */
+	Response structuredHandle() throws ExecutionException, InterruptedException {
+		try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
+			Future<String> user = scope.fork(() -> findUser());
+			Future<Integer> order = scope.fork(() -> fetchOrder());
+
+			scope.join(); // Join both forks
+			scope.throwIfFailed(); // ... and propagate errors
+
+			// Here, both forks have succeeded, so compose their results
+			return new Response(user.resultNow(), order.resultNow());
+		}
+	}
+
+	String findUser() {
+		System.out.println("Finding user");
+		sleep("Finding user");
+		System.out.println("Found user");
+		return "Marley";
+	}
+
+	Integer fetchOrder() {
+		System.out.println("Fetching order");
+		// sleep("Fetching order");
+		throw new RuntimeException();
+		// System.out.println("Fetched order");
+		// return Integer.valueOf(42);
+	}
+
+	void sleep(String task) {
+		try {
+			Thread.sleep(10000);
+		} catch (Exception ex) {
+			System.out.println(task + " canceled");
+		}
+	}
+}
+
+record Response(String user, Integer order) {}

java-19/img/2022-06-12-17-50-45.png

@@ -0,0 +1,15 @@
+# Example of Structured Concurrency
+
+The output that we can see that the `StructuredTaskScope` canceled other subtask (throwing a `InterruptedException`):
+
+![](img/2022-06-12-18-08-57.png)
+
+Thread view of concurrency using `ExecutorService`:
+
+![](img/2022-06-12-17-50-45.png)
+
+Thread view of concurency using `StructuredTaskScope`:
+
+![](img/2022-06-12-17-51-30.png)
+
+We can not the virtual thread running with ForkJoinPool.