diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..820afeff
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,115 @@
+# Instructions
+
+## Introcution
+
+At the beginning, provide a detailed, in-depth description of the topic covered. 
+
+## Code Descriptions
+
+When asked to add a description:  
+
+- Include a brief summary directly below the section title
+- Follow with a detailed explanation beneath the code block, at least 2-3 sentences,
+  more for more complex examples.   
+- Limit text to **80 characters per line**, ending each line with **two spaces**  
+- Maintain consistency with existing documents in the repository  
+
+##  Example Structure
+
+Examples should build progressively—from simple to advanced concepts.  
+Avoid numbering section titles (e.g. *Example 1: Basic types*).  
+Use plain titles like *Basic types*, following standard Java naming conventions.  
+
+Use a **dark theme** for all code blocks.  
+
+## Language Features
+
+Utilize modern Java features up to **Java 25**, including:  
+
+- **Compact source files**  
+- **Instance main methods**  
+- **Implicit imports** (e.g. `List`, `Map`, `IO`)  
+- **Type inference with `var`**  
+- **Pattern matching and enhanced switch (where relevant)**  
+
+Here’s a Markdown table listing the **implicitly imported types** in Java 25 compact source files,  
+based on [JEP 512](https://openjdk.org/jeps/512) and Oracle’s documentation:
+
+
+
+---
+
+### 📦 Implicit Imports in Java 25 Compact Source Files
+
+| Package         | Class / Interface     | Description                                      |
+|----------------|------------------------|--------------------------------------------------|
+| `java.lang`     | `String`              | Textual data                                     |
+| `java.lang`     | `System`              | Standard input/output streams                    |
+| `java.lang`     | `Math`                | Mathematical functions                           |
+| `java.lang`     | `Object`              | Root class of all Java objects                   |
+| `java.lang`     | `Exception`           | Base class for exceptions                        |
+| `java.lang`     | `IO`                  | Simplified console I/O (new in Java 25)          |
+| `java.util`     | `List`                | Ordered collection interface                     |
+| `java.util`     | `Map`                 | Key-value mapping interface                      |
+| `java.util`     | `Set`                 | Unordered collection of unique elements          |
+| `java.util`     | `ArrayList`           | Resizable list implementation                    |
+| `java.util`     | `HashMap`             | Hash-based key-value store                       |
+
+---
+
+These types are available without needing explicit `import` statements in compact source files. 
+
+
+## Code Format
+
+Each example should follow this structure:
+
+```java
+void main() {
+
+    // Using List (implicitly imported)
+    var fruits = List.of("apple", "banana", "cherry");
+
+    // Using Set (implicitly imported)
+    var uniqueFruits = Set.of("apple", "banana", "apple");
+
+    // Using Map (implicitly imported)
+    var fruitColors = Map.of(
+        "apple", "red",
+        "banana", "yellow",
+        "cherry", "dark red"
+    );
+
+    // Using ArrayList (implicitly imported)
+    var mutableList = new ArrayList<String>();
+    mutableList.add("grape");
+    mutableList.addAll(fruits);
+
+    // Using HashMap (implicitly imported)
+    var mutableMap = new HashMap<String, String>();
+    mutableMap.put("grape", "purple");
+    mutableMap.putAll(fruitColors);
+
+    // Using IO (new in Java 25)
+    IO.println("Fruits:");
+    for (var fruit : mutableList) {
+        IO.println("- " + fruit + " (" + mutableMap.get(fruit) + ")");
+    }
+
+    // Using Math and System (from java.lang)
+    IO.println("Total fruits: " + Math.max(mutableList.size(), 0));
+    System.exit(0); // Clean exit
+}
+```
+
+Use a simple `main` function as the entry point. Avoid classes and static methods  
+unless demonstrating specific language features. Use spaces after Section headings,  
+description text and the example, and the `void main() {` method.  
+
+## Terminology
+
+When referencing functions or methods:  
+
+- Use names without parentheses (e.g. *the `main` function*, not *`main()`*)  
+- Be precise and consistent in terminology across examples  
+
diff --git a/CapitalizeWords.java b/CapitalizeWords.java
index a22e30ff..2573df36 100644
--- a/CapitalizeWords.java
+++ b/CapitalizeWords.java
@@ -1,28 +1,36 @@
-package com.zetcode;
 
-import java.util.ArrayList;
-import java.util.List;
+void main() {
 
-// latin characters only
+    // works for Latin, more complex languages need a different solution
 
-public class CapitalizeWords {
+    List<String> words = List.of("rock", "forest", "sky", "cloud", "water");
 
-    public static void main(String[] args) {
+    System.out.println(capitalize(words));
+    System.out.println(capitalize2(words));
+}
 
-        List<String> words = List.of("rock", "forest", "sky", "cloud", "water");
-        List<String> capitalized = new ArrayList<>();
+List<String> capitalize(List<String> words) {
 
-        for (var word : words) {
+    List<String> capitalized = new ArrayList<>();
 
-            var sb = new StringBuilder(word);
+    for (var word : words) {
 
-            char c = sb.charAt(0);
-            char upperCased = Character.toUpperCase(c);
-            sb.setCharAt(0, upperCased);
+        var sb = new StringBuilder(word);
 
-            capitalized.add(sb.toString());
-        }
+        char c = sb.charAt(0);
+        char upperCased = Character.toUpperCase(c);
+        sb.setCharAt(0, upperCased);
 
-        System.out.println(capitalized);
+        capitalized.add(sb.toString());
     }
+
+    return capitalized;
+}
+
+List<String> capitalize2(List<String> words) {
+
+    return words.stream()
+            .map(word -> Character.toUpperCase(word.charAt(0)) + word.substring(1))
+            .toList();
+
 }
diff --git a/JSoupValidateAndSum.java b/JSoupValidateAndSum.java
index bd0342c2..9c7a7677 100644
--- a/JSoupValidateAndSum.java
+++ b/JSoupValidateAndSum.java
@@ -1,52 +1,46 @@
-package com.zetcode;
 
 import org.jsoup.Jsoup;
 import org.jsoup.nodes.Document;
 
-import java.io.IOException;
-
 // the program reads data from a web page, validates it and 
 // calculates sum from them
 // uses custom validation method
 
-public class JSoupValidateAndSum {
-
-    public static void main(String[] args) throws IOException {
-
-        String url = "http://test.webcode.me/data.txt";
+void main(String[] args) throws IOException {
 
-        Document doc = Jsoup.connect(url).get();
+  String url = "https://test.webcode.me/data.txt";
 
-        String content = doc.body().text();
-        System.out.println(content);
+  Document doc = Jsoup.connect(url).get();
 
-        String[] vals = content.split(",\\s+");
+  String content = doc.body().text();
+  System.out.println(content);
 
-        int sum = 0;
+  String[] vals = content.split(",\\s+");
 
-        for (String val : vals) {
+  int sum = 0;
 
-            if (isNumeric(val)) {
+  for (String val : vals) {
 
-                sum += Integer.parseInt(val);
-            }
-        }
+    if (isNumeric(val)) {
 
-        System.out.println(sum);
+      sum += Integer.parseInt(val);
     }
+  }
 
-    public static boolean isNumeric(String val) {
+  System.out.println(sum);
+}
 
-        int len = val.length();
+boolean isNumeric(String val) {
 
-        for (int i = 0; i < len; i++) {
+  int len = val.length();
 
-            if (!Character.isDigit(val.charAt(i))) {
+  for (int i = 0; i < len; i++) {
 
-                return false;
-            }
-        }
+    if (!Character.isDigit(val.charAt(i))) {
 
-        return true;
+      return false;
     }
+  }
+
+  return true;
 }
diff --git a/NinetyNineBottles.java b/NinetyNineBottles.java
index 5b7b5d29..09984e2f 100644
--- a/NinetyNineBottles.java
+++ b/NinetyNineBottles.java
@@ -1,29 +1,24 @@
-package com.zetcode;
 
-public class NinetyNineBottles {
+void main() {
 
+    // 99 bottles of beer on the wall, 99 bottles of beer.
+    // Take one down, pass it around, 98 bottles of beer on the wall
 
-    public static void main(String[] args) {
+    int nOfbottles = 99;
 
-        // 99 bottles of beer on the wall, 99 bottles of beer.
-        // Take one down, pass it around, 98 bottles of beer on the wall
+    for (int i = nOfbottles; i >= 1; i--) {
 
-        int nOfbottles = 99;
+        if (i == 1) {
 
-        for (int i = nOfbottles; i >= 1; i--) {
+            System.out.printf("%d bottle of beer on the wall, %d bottle of beer.%n", i, i);
+            System.out.println("Take one down, pass it around, no bottles of beer on the wall.");
+            System.out.println();
 
-            if (i == 1) {
+        } else {
 
-                System.out.printf("%d bottle of beer on the wall, %d bottle of beer.%n", i, i);
-                System.out.println("Take one down, pass it around, no bottles of beer on the wall.");
-                System.out.println();
-
-            } else {
-
-                System.out.printf("%d bottles of beer on the wall, %d bottles of beer.%n", i, i);
-                System.out.printf("Take one down, pass it around, %d bottles of beer on the wall.%n", i - 1);
-                System.out.println();
-            }
+            System.out.printf("%d bottles of beer on the wall, %d bottles of beer.%n", i, i);
+            System.out.printf("Take one down, pass it around, %d bottles of beer on the wall.%n", i - 1);
+            System.out.println();
         }
     }
 }
diff --git a/PropsEnv.java b/PropsEnv.java
index 14a91e20..d66f1358 100644
--- a/PropsEnv.java
+++ b/PropsEnv.java
@@ -1,26 +1,25 @@
-package com.zetcode;
+void main() {
 
-public class PropsEnv {
+  var path = System.getenv("PATH");
 
-    public static void main(String[] args) {
+  // Split using the system-specific path separator
+  String[] directories = path.split(System.getProperty("path.separator"));
 
-        var path = System.getenv("PATH");
+  for (var directory : directories) {
 
-        String[] directories = path.split(";");
+    IO.println(directory);
+  }
 
-        for (var directory : directories) {
+  IO.println(String.format("There are %d items in the PATH variable%n",
+      directories.length));
 
-            System.out.println(directory);
-        }
+  String os_version = System.getProperty("os.name");
+  String user_name = System.getProperty("user.name");
+  String java_version = System.getProperty("java.version");
+  String java_home = System.getProperty("java.home");
 
-        System.out.printf("There are %d items in the PATH variable%n", directories.length);
-
-        String os_version = System.getProperty("os.name");
-        String java_version = System.getProperty("java.version");
-        String java_home = System.getProperty("java.home");
-
-        System.out.println(os_version);
-        System.out.println(java_version);
-        System.out.println(java_home);
-    }
+  IO.println(os_version);
+  IO.println(user_name);
+  IO.println(java_version);
+  IO.println(java_home);
 }
diff --git a/README.md b/README.md
index ad68d657..f86438d3 100644
--- a/README.md
+++ b/README.md
@@ -3,3 +3,38 @@ Examples for Advanced Java course
 https://zetcode.com/
 
 Available under 2-Clause BSD License https://opensource.org/licenses/BSD-2-Clause
+
+
+## VS Code
+
+Extensions:
+
+- Java Platforma Support
+- Trailing
+- vscode-icons
+- Rewrap
+
+
+The project `settings.json`
+
+```json
+{
+    "jdk.runConfig.vmOptions": "--enable-preview --source 22",
+    "jdk.jdkhome": "c:\\Users\\Jano\\.jdks\\jdk22.0.0_36",
+}
+```
+
+
+The `settings.json`
+
+```json
+{
+    "editor.rulers": [
+        80
+    ],
+    "workbench.iconTheme": "vscode-icons",
+    "terminal.integrated.defaultProfile.windows": "Command Prompt",
+    "jdk.jdkhome": "c:\\Users\\Jano\\.jdks\\jdk22.0.0_36",
+    "editor.stickyScroll.enabled": false,
+    "editor.minimap.enabled": false,
+}
diff --git a/ReadTodosEx.java b/ReadTodosEx.java
index 67a19f3f..2adba943 100644
--- a/ReadTodosEx.java
+++ b/ReadTodosEx.java
@@ -1,70 +1,65 @@
-package com.zetcode;
-
 import com.google.gson.Gson;
 import com.google.gson.GsonBuilder;
 import com.google.gson.annotations.Expose;
 
-import java.io.IOException;
 import java.net.URI;
 import java.net.http.HttpClient;
 import java.net.http.HttpRequest;
 import java.net.http.HttpResponse;
 
-class Todo {
 
-    private int userId;
+record Todo(int userId, int id, @Expose String title, boolean completed) {
+}
 
-    private int id;
+void main(String[] args) throws IOException, InterruptedException {
 
-    @Expose
-    private String title;
+  String url = "https://jsonplaceholder.typicode.com/todos";
 
-    private boolean completed;
+  HttpClient client = HttpClient.newHttpClient();
+  HttpRequest request = HttpRequest.newBuilder().uri(URI.create(url)).build();
 
-    public Todo(int userId, int id, String title, boolean completed) {
-        this.userId = userId;
-        this.id = id;
-        this.title = title;
-        this.completed = completed;
-    }
+  HttpResponse<String> response = client.send(request,
+      HttpResponse.BodyHandlers.ofString());
 
-    @Override
-    public String toString() {
-        final StringBuilder sb = new StringBuilder("Todo{");
-        sb.append("userId=").append(userId);
-        sb.append(", id=").append(id);
-        sb.append(", title='").append(title).append('\'');
-        sb.append(", completed=").append(completed);
-        sb.append('}');
-        return sb.toString();
-    }
-}
+  var jsonString = response.body();
 
-public class ReadTodosEx {
+  System.out.println(jsonString);
 
-    public static void main(String[] args) throws IOException, InterruptedException {
+  Gson gson = new GsonBuilder().excludeFieldsWithoutExposeAnnotation()
+      .setPrettyPrinting().create();
 
-        String url = "https://jsonplaceholder.typicode.com/todos";
+  Todo[] todos = gson.fromJson(jsonString, Todo[].class);
 
-        HttpClient client = HttpClient.newHttpClient();
-        HttpRequest request = HttpRequest.newBuilder()
-                .uri(URI.create(url))
-                .build();
+  gson.toJson(todos, System.out);
+}
 
-        HttpResponse<String> response = client.send(request,
-                HttpResponse.BodyHandlers.ofString());
 
-        var jsonString = response.body();
+// class Todo {
 
-        System.out.println(jsonString);
+//     private int userId;
 
-        Gson gson = new GsonBuilder()
-                .excludeFieldsWithoutExposeAnnotation()
-                .setPrettyPrinting()
-                .create();
+//     private int id;
 
-        Todo[] todos = gson.fromJson(jsonString, Todo[].class);
+//     @Expose
+//     private String title;
 
-        gson.toJson(todos, System.out);
-    }
-}
+//     private boolean completed;
+
+//     public Todo(int userId, int id, String title, boolean completed) {
+//         this.userId = userId;
+//         this.id = id;
+//         this.title = title;
+//         this.completed = completed;
+//     }
+
+//     @Override
+//     public String toString() {
+//         final StringBuilder sb = new StringBuilder("Todo{");
+//         sb.append("userId=").append(userId);
+//         sb.append(", id=").append(id);
+//         sb.append(", title='").append(title).append('\'');
+//         sb.append(", completed=").append(completed);
+//         sb.append('}');
+//         return sb.toString();
+//     }
+// }
diff --git a/UniqueNames.java b/UniqueNames.java
index e49ef30c..ddd694d4 100644
--- a/UniqueNames.java
+++ b/UniqueNames.java
@@ -1,27 +1,38 @@
-package com.zetcode;
+void main() {
 
-import java.util.ArrayList;
-import java.util.List;
+    List<String> names = List.of("Martin", "Lucy", "Peter",
+            "Martin", "Robert", "Peter");
 
-public class UniqueNames {
+    System.out.println(unique(names));
+    System.out.println(unique2(names));
+    System.out.println(unique3(names));
+}
+
+List<String> unique(List<String> names) {
+
+    List<String> uniqueNames = new ArrayList<>();
+
+    names.forEach(e -> {
 
-    public static void main(String[] args) {
+        if (!uniqueNames.contains(e)) {
 
-        List<String> names = List.of("Martin", "Lucy", "Peter",
-                "Martin", "Robert", "Peter");
+            uniqueNames.add(e);
+        }
+    });
 
-        List<String> uniqueNames = new ArrayList<>();
+    return uniqueNames;
+}
+
+List<String> unique2(List<String> names) {
 
-        names.forEach(e -> {
+    return names.stream().distinct().toList();
+
+}
 
-            if (!uniqueNames.contains(e)) {
+List<String> unique3(List<String> names) {
 
-                uniqueNames.add(e);
-            }
-        });
+    HashSet<String> uniqueNames = new HashSet<>(names);
 
-        System.out.println(names);
-        System.out.println(uniqueNames);
+    return new ArrayList<String>(uniqueNames);
 
-    }
 }
diff --git a/apps/test/classic.md b/apps/test/classic.md
new file mode 100644
index 00000000..fe75f88d
--- /dev/null
+++ b/apps/test/classic.md
@@ -0,0 +1,117 @@
+# Apps
+
+## Classic console app
+
+```
+javac -d bin -cp lib\jsoup-1.17.2.jar src\main\java\com\example\Main.java src\main\java\com\example\utils\*.java
+java -cp bin;lib\jsoup-1.17.2.jar com.example.Main https://webcode.me
+jar -cvfm main.jar manifest.txt com ../lib
+java -jar main.jar
+```
+
+
+```manifest
+Manifest-Version: 1.0
+Main-Class: com.example.Main
+Class-Path: ../lib/jsoup-1.17.2.jar
+```
+
+
+```java
+package com.example;
+
+import com.example.utils.Scraper;
+import com.example.utils.Utils;
+import java.io.IOException;
+
+public class Main {
+
+    public static void main(String[] args) throws IOException {
+
+        String word = new Utils().getRandomWord();
+        System.out.println(word);
+
+        String url = "https://example.com";
+
+        if (args.length > 0) {
+            url = args[0];
+        }
+
+        var scraper = new Scraper(url);
+
+        String title = scraper.getTitle();
+        System.err.println(title);
+    }
+}
+```
+
+```java
+package com.example.utils;
+
+import org.jsoup.Jsoup;
+import org.jsoup.nodes.Document;
+import java.io.IOException;
+
+public final class Scraper {
+
+    private final String url;
+
+    public Scraper(String url) {
+        this.url = url;
+    }
+
+    public String getTitle() throws IOException {
+
+        Document doc = Jsoup.connect(url).get();
+        return doc.title();
+    }
+}
+```
+
+```java
+package com.example.utils;
+
+import java.util.List;
+import java.util.Random;
+
+final public class Utils {
+
+    List<String> words = List.of("sky", "town", "blue", "forest", "snake",
+        "book", "pen", "cloud", "cup");
+
+    public String getRandomWord() {
+
+        int idx = new Random().nextInt(words.size());
+        return words.get(idx);
+    }
+}
+```
+
+## Modern console app
+
+`java --enable-preview --source 22 -cp lib\jsoup-1.17.2.jar Main.java https://root.cz`  
+
+```java
+import utils.Scraper;
+import utils.Utils;
+import java.io.IOException;
+
+void main(String[] args) throws IOException {
+    
+    String word = new Utils().getRandomWord();
+    System.out.println(word);
+
+    String url = "https://example.com";
+
+    if (args.length > 0) {
+        url = args[0];
+    }
+
+    var scraper = new Scraper(url);
+
+    String title = scraper.getTitle();
+    System.err.println(title);
+}
+```
+
+
diff --git a/bigo.md b/bigo.md
new file mode 100644
index 00000000..8b137891
--- /dev/null
+++ b/bigo.md
@@ -0,0 +1 @@
+
diff --git a/class-loading.md b/class-loading.md
new file mode 100644
index 00000000..410b5c7c
--- /dev/null
+++ b/class-loading.md
@@ -0,0 +1,1356 @@
+# Java Class Loading and Custom ClassLoaders
+
+Class loading is one of the fundamental mechanisms of the Java Virtual Machine  
+(JVM) that enables the dynamic loading of classes at runtime. Unlike languages  
+where all code is linked at compile time, Java loads classes on demand as they  
+are needed during program execution. This lazy loading strategy reduces memory  
+footprint and startup time while enabling powerful features like plugins,  
+hot deployment, and runtime code generation.  
+
+The class loading mechanism is essential for understanding how Java applications  
+work at a deeper level. Every time you instantiate an object, call a static  
+method, or reference a class constant, the JVM's class loading subsystem ensures  
+that the required class is available in memory. This process involves locating  
+the bytecode, verifying its correctness, and preparing it for execution.  
+
+For advanced Java development, understanding class loaders is crucial. They form  
+the foundation for application servers, OSGi containers, plugin systems, and  
+module frameworks. Misunderstanding class loading can lead to subtle bugs like  
+`ClassCastException` between seemingly identical classes, memory leaks from  
+unreleased class loaders, and security vulnerabilities from improperly isolated  
+code.  
+
+## Class Loading Process Overview  
+
+The JVM loads classes through a well-defined three-phase process:  
+
+1. **Loading**: The class loader reads the `.class` file (bytecode) from the  
+   file system, network, or other sources and creates a `Class` object in memory.  
+
+2. **Linking**: This phase has three sub-phases:  
+   - **Verification**: Ensures the bytecode is valid and doesn't violate JVM  
+     security constraints  
+   - **Preparation**: Allocates memory for static variables and initializes them  
+     to default values  
+   - **Resolution**: Converts symbolic references to direct references  
+
+3. **Initialization**: Executes static initializers and initializes static  
+   variables with their defined values. This happens lazily, only when the class  
+   is first actively used.  
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           Class Loading Lifecycle                            │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│    .class file                                                              │
+│         │                                                                   │
+│         ▼                                                                   │
+│    ┌─────────┐    ┌─────────────────────────────────────┐    ┌───────────┐ │
+│    │ Loading │───▶│              Linking                │───▶│Initialize │ │
+│    └─────────┘    │ ┌────────┐ ┌────────┐ ┌──────────┐ │    └───────────┘ │
+│                   │ │Verify  │▶│Prepare │▶│ Resolve  │ │                   │
+│                   │ └────────┘ └────────┘ └──────────┘ │                   │
+│                   └─────────────────────────────────────┘                   │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Class Loader Hierarchy  
+
+Java uses a hierarchical class loader architecture with a parent delegation model.  
+Each class loader has a parent (except the Bootstrap ClassLoader), and class  
+loading requests are first delegated to the parent before the class loader  
+attempts to load the class itself.  
+
+| Class Loader | Description | Location |
+|--------------|-------------|----------|
+| Bootstrap ClassLoader | Loads core Java classes | `JAVA_HOME/lib` |
+| Platform ClassLoader | Loads platform modules | Java modules |
+| Application ClassLoader | Loads application classes | Classpath |
+| Custom ClassLoader | User-defined loaders | Custom sources |
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         Class Loader Hierarchy                               │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│                        ┌───────────────────────┐                            │
+│                        │ Bootstrap ClassLoader │ (Native code)              │
+│                        │   java.lang, etc.     │                            │
+│                        └───────────┬───────────┘                            │
+│                                    │                                        │
+│                                    ▼                                        │
+│                        ┌───────────────────────┐                            │
+│                        │ Platform ClassLoader  │ (Java 9+)                  │
+│                        │   java.sql, etc.      │                            │
+│                        └───────────┬───────────┘                            │
+│                                    │                                        │
+│                                    ▼                                        │
+│                        ┌───────────────────────┐                            │
+│                        │Application ClassLoader│                            │
+│                        │   Your application    │                            │
+│                        └───────────┬───────────┘                            │
+│                                    │                                        │
+│                                    ▼                                        │
+│                        ┌───────────────────────┐                            │
+│                        │ Custom ClassLoader(s) │                            │
+│                        │   Plugins, modules    │                            │
+│                        └───────────────────────┘                            │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+
+## Examining class loaders
+
+This example demonstrates how to examine the class loader hierarchy by printing  
+the class loaders for various classes in the system.  
+
+```java
+void main() {
+
+    // Get the class loader of our main class
+    var appLoader = getClass().getClassLoader();
+    println("Application class loader: " + appLoader);
+
+    // Get the parent class loaders
+    var platformLoader = appLoader.getParent();
+    println("Platform class loader: " + platformLoader);
+
+    // Bootstrap class loader returns null
+    var bootstrapLoader = platformLoader.getParent();
+    println("Bootstrap class loader: " + bootstrapLoader);
+
+    // Different classes are loaded by different class loaders
+    println("\nClass loader examples:");
+    println("String.class loader: " + String.class.getClassLoader());
+    println("ArrayList.class loader: " + java.util.ArrayList.class.getClassLoader());
+    println("This class loader: " + getClass().getClassLoader());
+}
+```
+
+This example shows the three-tier class loader hierarchy in Java. The `String`  
+class returns `null` for its class loader because it's loaded by the Bootstrap  
+ClassLoader, which is implemented in native code. The application class is  
+loaded by the Application ClassLoader, and we can traverse up the parent chain  
+to see the Platform ClassLoader.  
+
+
+## Finding where a class was loaded from
+
+This example shows how to determine the physical location from which a class  
+was loaded using the `ProtectionDomain` and `CodeSource` APIs.  
+
+```java
+void main() {
+
+    // Find where core Java classes are loaded from
+    var stringLocation = String.class.getProtectionDomain()
+        .getCodeSource();
+    println("String loaded from: " + stringLocation);
+
+    // Find where ArrayList is loaded from
+    var listLocation = java.util.ArrayList.class.getProtectionDomain()
+        .getCodeSource();
+    println("ArrayList loaded from: " + listLocation);
+
+    // Find where this class is loaded from
+    var thisLocation = getClass().getProtectionDomain()
+        .getCodeSource();
+    println("This class loaded from: " + 
+        (thisLocation != null ? thisLocation.getLocation() : "unknown"));
+
+    // Find where a third-party library class would be loaded from
+    try {
+        var objectMapper = Class.forName("com.fasterxml.jackson.databind.ObjectMapper");
+        var location = objectMapper.getProtectionDomain().getCodeSource();
+        println("ObjectMapper loaded from: " + location.getLocation());
+    } catch (ClassNotFoundException e) {
+        println("Jackson not available in classpath");
+    }
+}
+```
+
+Understanding where classes are loaded from is essential for debugging classpath  
+issues and version conflicts. The `getCodeSource` method returns the location  
+of the JAR file or directory from which the class was loaded. For bootstrap  
+classes, this may return null since they are loaded from the JVM's internal  
+modules.  
+
+
+## Loading classes dynamically with Class.forName
+
+The `Class.forName` method is the standard way to load classes dynamically at  
+runtime. This is useful when the class name is determined at runtime.  
+
+```java
+void main() {
+
+    // Load a class by name
+    try {
+        var listClass = Class.forName("java.util.ArrayList");
+        println("Loaded: " + listClass.getName());
+        println("Simple name: " + listClass.getSimpleName());
+        println("Package: " + listClass.getPackageName());
+        
+        // Create an instance using reflection
+        @SuppressWarnings("unchecked")
+        var list = (java.util.List<String>) listClass.getDeclaredConstructor()
+            .newInstance();
+        list.add("Hello");
+        list.add("World");
+        println("List contents: " + list);
+        
+    } catch (Exception e) {
+        println("Failed to load class: " + e.getMessage());
+    }
+
+    // Load a class without initializing it
+    try {
+        var mapClass = Class.forName("java.util.HashMap", false, 
+            ClassLoader.getSystemClassLoader());
+        println("\nLoaded without initialization: " + mapClass.getName());
+    } catch (ClassNotFoundException e) {
+        println("Class not found: " + e.getMessage());
+    }
+}
+```
+
+The `Class.forName` method has two variants. The simple version loads and  
+initializes the class, which means static initializers run immediately. The  
+three-argument version allows you to specify whether to initialize the class  
+and which class loader to use, giving you more control over the loading process.  
+
+
+## Understanding class initialization order
+
+This example demonstrates when static initialization occurs during class loading  
+and how the order affects program behavior.  
+
+```java
+class FirstClass {
+    static {
+        System.out.println("FirstClass static block executed");
+    }
+    static String value = initValue();
+    
+    static String initValue() {
+        System.out.println("FirstClass.initValue() called");
+        return "First";
+    }
+}
+
+class SecondClass {
+    static {
+        System.out.println("SecondClass static block executed");
+    }
+    static String value = "Second";
+}
+
+void main() {
+
+    println("Before any class access...\n");
+
+    // Accessing FirstClass triggers its initialization
+    println("Accessing FirstClass.value:");
+    var first = FirstClass.value;
+    println("Got: " + first + "\n");
+
+    // Accessing SecondClass triggers its initialization
+    println("Accessing SecondClass.value:");
+    var second = SecondClass.value;
+    println("Got: " + second + "\n");
+
+    // Loading without initialization
+    println("Loading ThirdClass without initialization:");
+    try {
+        Class.forName("ThirdClass", false, 
+            ClassLoader.getSystemClassLoader());
+        println("ThirdClass loaded but not initialized");
+    } catch (ClassNotFoundException e) {
+        println("ThirdClass not found (expected)");
+    }
+}
+
+class ThirdClass {
+    static {
+        System.out.println("ThirdClass static block - should not appear!");
+    }
+}
+```
+
+Static initializers run in the order they appear in the source code, but only  
+when the class is first actively used. Using `Class.forName` with the second  
+parameter set to `false` loads the class without triggering initialization,  
+which can be useful when you need to inspect a class without running its static  
+code.  
+
+
+## Parent delegation model
+
+This example illustrates how class loaders delegate to their parents before  
+attempting to load a class themselves.  
+
+```java
+void main() {
+
+    // Create a custom class loader that logs delegation
+    var loggingLoader = new ClassLoader(getClass().getClassLoader()) {
+        @Override
+        public Class<?> loadClass(String name) throws ClassNotFoundException {
+            println("Attempting to load: " + name);
+            
+            // First, check if already loaded
+            var loaded = findLoadedClass(name);
+            if (loaded != null) {
+                println("  -> Already loaded");
+                return loaded;
+            }
+            
+            // Delegate to parent first (standard behavior)
+            try {
+                println("  -> Delegating to parent");
+                return getParent().loadClass(name);
+            } catch (ClassNotFoundException e) {
+                println("  -> Parent couldn't load, trying ourselves");
+                throw e;
+            }
+        }
+    };
+
+    // Try loading a standard library class
+    println("Loading String class:");
+    try {
+        var stringClass = loggingLoader.loadClass("java.lang.String");
+        println("Loaded by: " + stringClass.getClassLoader() + "\n");
+    } catch (ClassNotFoundException e) {
+        println("Failed: " + e.getMessage());
+    }
+
+    // Try loading ArrayList
+    println("Loading ArrayList class:");
+    try {
+        var listClass = loggingLoader.loadClass("java.util.ArrayList");
+        println("Loaded by: " + listClass.getClassLoader());
+    } catch (ClassNotFoundException e) {
+        println("Failed: " + e.getMessage());
+    }
+}
+```
+
+The parent delegation model ensures that core Java classes are always loaded by  
+the Bootstrap ClassLoader, preventing malicious code from replacing system  
+classes. When a class loader receives a request to load a class, it first asks  
+its parent. Only if the parent cannot load the class does the child attempt to  
+load it.  
+
+
+## Simple custom class loader from bytes
+
+This example demonstrates creating a minimal custom class loader that loads a  
+class from a byte array representation.  
+
+```java
+void main() {
+
+    // A simple class represented as bytecode
+    // This is the compiled bytecode for:
+    // public class DynamicClass { 
+    //     public String getMessage() { return "Hello from dynamic class!"; }
+    // }
+    
+    var customLoader = new ClassLoader(getClass().getClassLoader()) {
+        @Override
+        protected Class<?> findClass(String name) throws ClassNotFoundException {
+            if ("DynamicClass".equals(name)) {
+                // In a real scenario, you would read bytes from a file or network
+                // Here we're simulating with a placeholder
+                throw new ClassNotFoundException(
+                    "DynamicClass bytecode not available - this is a demonstration");
+            }
+            throw new ClassNotFoundException(name);
+        }
+    };
+
+    println("Custom class loader created: " + customLoader);
+    println("Parent: " + customLoader.getParent());
+    println("System class loader: " + ClassLoader.getSystemClassLoader());
+
+    // Demonstrate that standard classes still work through delegation
+    try {
+        var stringClass = customLoader.loadClass("java.lang.String");
+        println("\nLoaded String via custom loader: " + 
+            stringClass.getClassLoader());
+    } catch (ClassNotFoundException e) {
+        println("Unexpected error: " + e.getMessage());
+    }
+
+    // Try to load a custom class
+    try {
+        customLoader.loadClass("DynamicClass");
+    } catch (ClassNotFoundException e) {
+        println("\nExpected: " + e.getMessage());
+    }
+}
+```
+
+Custom class loaders extend the `ClassLoader` class and override the `findClass`  
+method to specify how classes are located and loaded. The `defineClass` method  
+is then used to convert the raw bytecode into a `Class` object. This pattern is  
+the foundation for plugin systems and dynamic code loading.  
+
+
+## File-based custom class loader
+
+This example shows a practical custom class loader that loads classes from a  
+specific directory on the file system.  
+
+```java
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+class FileSystemClassLoader extends ClassLoader {
+    private final Path classesDir;
+
+    FileSystemClassLoader(Path classesDir, ClassLoader parent) {
+        super(parent);
+        this.classesDir = classesDir;
+    }
+
+    @Override
+    protected Class<?> findClass(String name) throws ClassNotFoundException {
+        var classFile = classesDir.resolve(name.replace('.', '/') + ".class");
+        
+        if (!Files.exists(classFile)) {
+            throw new ClassNotFoundException(name + " not found in " + classesDir);
+        }
+
+        try {
+            var bytes = Files.readAllBytes(classFile);
+            return defineClass(name, bytes, 0, bytes.length);
+        } catch (IOException e) {
+            throw new ClassNotFoundException("Error reading " + classFile, e);
+        }
+    }
+
+    @Override
+    public String toString() {
+        return "FileSystemClassLoader[" + classesDir + "]";
+    }
+}
+
+void main() {
+
+    // Create a class loader for a specific directory
+    var classesDir = Path.of("/tmp/custom-classes");
+    var loader = new FileSystemClassLoader(classesDir, getClass().getClassLoader());
+
+    println("Created: " + loader);
+    println("Looking for classes in: " + classesDir);
+
+    // Attempt to load a class (will fail if directory doesn't exist)
+    try {
+        var customClass = loader.loadClass("com.example.CustomClass");
+        println("Loaded: " + customClass.getName());
+    } catch (ClassNotFoundException e) {
+        println("Class not found: " + e.getMessage());
+        println("(This is expected if the directory doesn't contain classes)");
+    }
+
+    // Standard library classes still work via delegation
+    try {
+        var listClass = loader.loadClass("java.util.ArrayList");
+        println("\nArrayList loaded by: " + listClass.getClassLoader());
+    } catch (ClassNotFoundException e) {
+        println("Error: " + e.getMessage());
+    }
+}
+```
+
+A file-based class loader reads `.class` files from a directory structure that  
+mirrors the package hierarchy. The `defineClass` method converts the raw bytes  
+into a `Class` object. This pattern is commonly used for loading plugins or  
+modules from a specific location outside the main classpath.  
+
+
+## URL class loader for loading classes from JARs
+
+The `URLClassLoader` is a built-in class loader that can load classes from URLs,  
+including JAR files and directories.  
+
+```java
+import java.net.URL;
+import java.net.URLClassLoader;
+import java.nio.file.Path;
+
+void main() {
+
+    // Create URLs for class loading
+    try {
+        // Create a URL for a local directory (convert path to URL)
+        var localDir = Path.of("/tmp/plugin-libs").toUri().toURL();
+        println("Local directory URL: " + localDir);
+
+        // Create a URLClassLoader with multiple sources
+        var urls = new URL[] { localDir };
+        
+        try (var urlLoader = new URLClassLoader(urls, getClass().getClassLoader())) {
+            println("Created URLClassLoader with " + urls.length + " URL(s)");
+            println("Parent: " + urlLoader.getParent());
+
+            // List the URLs this loader will search
+            println("\nSearch URLs:");
+            for (var url : urlLoader.getURLs()) {
+                println("  - " + url);
+            }
+
+            // Try loading a class from the URL
+            try {
+                var pluginClass = urlLoader.loadClass("com.example.Plugin");
+                println("\nLoaded plugin: " + pluginClass.getName());
+            } catch (ClassNotFoundException e) {
+                println("\nPlugin class not found (expected if directory is empty)");
+            }
+
+            // Standard classes still work
+            var stringClass = urlLoader.loadClass("java.lang.String");
+            println("String loaded by: " + stringClass.getClassLoader());
+        }
+
+    } catch (Exception e) {
+        println("Error: " + e.getMessage());
+    }
+}
+```
+
+`URLClassLoader` is the most commonly used class loader for dynamically loading  
+external code. It supports loading from JAR files, directories, and even remote  
+URLs. The loader searches its URLs in order and uses parent delegation to  
+ensure core classes are loaded from the system class loader.  
+
+
+## Class loader isolation
+
+This example demonstrates how different class loaders provide isolation,  
+allowing the same class to be loaded multiple times as different `Class` objects.  
+
+```java
+import java.net.URL;
+import java.net.URLClassLoader;
+import java.nio.file.Path;
+
+void main() {
+
+    try {
+        var classPath = Path.of(".").toUri().toURL();
+        
+        // Create two independent class loaders with no parent relationship
+        var loader1 = new URLClassLoader(new URL[]{classPath}, null);
+        var loader2 = new URLClassLoader(new URL[]{classPath}, null);
+
+        println("Loader 1: " + loader1);
+        println("Loader 2: " + loader2);
+        println();
+
+        // Both loaders can load the same class name
+        // but they will be different Class objects
+        try {
+            var class1 = loader1.loadClass("java.util.ArrayList");
+            var class2 = loader2.loadClass("java.util.ArrayList");
+
+            println("Class 1: " + class1.getName());
+            println("Class 1 loader: " + class1.getClassLoader());
+            println("Class 2: " + class2.getName());
+            println("Class 2 loader: " + class2.getClassLoader());
+
+            println("\nAre they the same class object? " + (class1 == class2));
+            println("Are they equals? " + class1.equals(class2));
+
+        } catch (ClassNotFoundException e) {
+            println("Error: " + e.getMessage());
+        }
+
+        loader1.close();
+        loader2.close();
+
+    } catch (Exception e) {
+        println("Error: " + e.getMessage());
+    }
+}
+```
+
+When two class loaders load the same class, they create distinct `Class` objects.  
+Objects created by one loader cannot be cast to the same class loaded by another  
+loader, even if the bytecode is identical. This isolation is the foundation for  
+plugin systems and OSGi containers that need to load different versions of the  
+same library.  
+
+
+## Context class loader
+
+The thread context class loader is a class loader associated with each thread,  
+commonly used by frameworks to load resources and classes.  
+
+```java
+void main() throws InterruptedException {
+
+    // Get the context class loader of the current thread
+    var contextLoader = Thread.currentThread().getContextClassLoader();
+    println("Main thread context loader: " + contextLoader);
+    println("Class class loader: " + getClass().getClassLoader());
+    println("Are they the same? " + (contextLoader == getClass().getClassLoader()));
+
+    // Create a thread with a custom context class loader
+    var customLoader = new ClassLoader(contextLoader) {
+        @Override
+        public String toString() {
+            return "CustomContextLoader";
+        }
+    };
+
+    var thread = new Thread(() -> {
+        var loader = Thread.currentThread().getContextClassLoader();
+        println("\nWorker thread context loader: " + loader);
+        
+        // Use context class loader to load a resource
+        var resource = loader.getResource("java/lang/String.class");
+        println("Found String.class resource: " + (resource != null));
+    });
+
+    thread.setContextClassLoader(customLoader);
+    thread.start();
+    thread.join();
+
+    println("\nContext loader is useful for SPI and framework code");
+    println("It allows libraries to load classes in the caller's context");
+}
+```
+
+The context class loader allows framework code to load classes in the context  
+of the calling application. This is essential for Service Provider Interface  
+(SPI) mechanisms like JDBC drivers, where the driver code needs to load classes  
+using the application's class loader rather than its own.  
+
+
+## Loading resources with class loaders
+
+Class loaders are used not only for loading classes but also for loading  
+resources like configuration files, images, and other assets.  
+
+```java
+import java.io.BufferedReader;
+import java.io.InputStreamReader;
+
+void main() {
+
+    var loader = getClass().getClassLoader();
+
+    // Find a resource on the classpath
+    var resourceUrl = loader.getResource("java/lang/Object.class");
+    println("Object.class URL: " + resourceUrl);
+
+    // Try to find a properties file
+    var propsUrl = loader.getResource("application.properties");
+    if (propsUrl != null) {
+        println("Found application.properties: " + propsUrl);
+    } else {
+        println("application.properties not found in classpath");
+    }
+
+    // Get system resources (searches all class loaders)
+    println("\nSearching for all manifest files:");
+    try {
+        var manifests = loader.getResources("META-INF/MANIFEST.MF");
+        int count = 0;
+        while (manifests.hasMoreElements() && count < 3) {
+            println("  " + manifests.nextElement());
+            count++;
+        }
+        if (count == 3) {
+            println("  ... (more manifests exist)");
+        }
+    } catch (Exception e) {
+        println("Error: " + e.getMessage());
+    }
+
+    // Read a resource as a stream
+    var stream = loader.getResourceAsStream("java/lang/String.class");
+    if (stream != null) {
+        println("\nString.class first bytes: ");
+        try {
+            var bytes = stream.readNBytes(8);
+            for (var b : bytes) {
+                System.out.printf("%02X ", b);
+            }
+            println("");
+            stream.close();
+        } catch (Exception e) {
+            println("Error reading: " + e.getMessage());
+        }
+    }
+}
+```
+
+Resources are loaded using the same delegation model as classes. The `getResource`  
+method returns a URL to the resource, while `getResourceAsStream` returns an  
+input stream for reading the content. The `getResources` method returns all  
+matching resources from all class loaders in the hierarchy.  
+
+
+## Reloading classes at runtime
+
+This example demonstrates the concept of class reloading, which requires  
+creating new class loader instances to load updated versions of classes.  
+
+```java
+import java.net.URL;
+import java.net.URLClassLoader;
+import java.nio.file.Path;
+
+void main() throws Exception {
+
+    var classPath = Path.of("/tmp/hot-reload").toUri().toURL();
+    println("Hot reload directory: " + classPath);
+
+    // Simulate class reloading by creating new class loaders
+    for (int version = 1; version <= 3; version++) {
+        println("\n--- Loading version " + version + " ---");
+        
+        // Create a new class loader for each version
+        var loader = new URLClassLoader(
+            new URL[]{classPath}, 
+            getClass().getClassLoader()
+        );
+
+        try {
+            // Attempt to load a class
+            var serviceClass = loader.loadClass("com.example.Service");
+            println("Loaded: " + serviceClass.getName());
+            println("Class loader: " + serviceClass.getClassLoader());
+            println("Identity hash: " + System.identityHashCode(serviceClass));
+
+            // Create an instance
+            var service = serviceClass.getDeclaredConstructor().newInstance();
+            println("Instance: " + service);
+
+        } catch (ClassNotFoundException e) {
+            println("Service class not found (place a compiled class in the directory)");
+        } finally {
+            loader.close();
+        }
+    }
+
+    println("\nNote: Each version uses a different class loader instance.");
+    println("The old class remains in memory until its loader is garbage collected.");
+}
+```
+
+Java does not support true class reloading where an existing `Class` object is  
+modified. Instead, hot reloading is achieved by creating a new class loader and  
+loading a fresh copy of the class. The old class remains in memory until its  
+class loader is garbage collected, which requires all references to classes  
+loaded by that loader to be released.  
+
+
+## Module system interaction
+
+In Java 9+, the module system (JPMS) interacts with class loading through  
+module layers and module class loaders.  
+
+```java
+void main() {
+
+    // Get information about the module system
+    var thisModule = getClass().getModule();
+    println("This class module: " + thisModule);
+    println("Is named module: " + thisModule.isNamed());
+    println("Module name: " + thisModule.getName());
+
+    // Examine java.base module
+    var baseModule = String.class.getModule();
+    println("\njava.base module: " + baseModule);
+    println("Module layer: " + baseModule.getLayer());
+
+    // List some packages in java.base
+    println("\nSome packages in java.base:");
+    baseModule.getPackages().stream()
+        .filter(p -> p.startsWith("java.lang") || p.startsWith("java.util"))
+        .limit(5)
+        .forEach(p -> println("  - " + p));
+
+    // Get the boot layer
+    var bootLayer = ModuleLayer.boot();
+    println("\nBoot layer: " + bootLayer);
+    println("Modules in boot layer: " + bootLayer.modules().size());
+
+    // Check module exports
+    println("\njava.base exports java.lang to: " + 
+        (baseModule.isExported("java.lang") ? "everyone" : "no one"));
+
+    // Class loading in modular environment
+    var loader = String.class.getClassLoader();
+    println("\nString class loader: " + loader);
+    println("This suggests bootstrap classes are in unnamed modules for the loader");
+}
+```
+
+The Java Platform Module System introduces a new layer of encapsulation on top  
+of class loading. Modules define which packages are exported and which are  
+internal. Class loaders work alongside the module system, with each module layer  
+potentially having its own class loader configuration.  
+
+
+## Service Provider Interface (SPI) loading
+
+This example shows how the `ServiceLoader` mechanism uses class loaders to  
+discover and load service implementations dynamically.  
+
+```java
+import java.nio.charset.spi.CharsetProvider;
+import java.util.ServiceLoader;
+import java.util.spi.LocaleServiceProvider;
+
+void main() {
+
+    // ServiceLoader uses the context class loader
+    var contextLoader = Thread.currentThread().getContextClassLoader();
+    println("Context class loader: " + contextLoader);
+
+    // Load CharsetProvider services
+    println("\nCharset Providers:");
+    var charsetProviders = ServiceLoader.load(CharsetProvider.class);
+    for (var provider : charsetProviders) {
+        println("  - " + provider.getClass().getName());
+        println("    Loaded by: " + provider.getClass().getClassLoader());
+    }
+
+    // Load with a specific class loader
+    println("\nLocale Service Providers (via system loader):");
+    var localeProviders = ServiceLoader.load(
+        LocaleServiceProvider.class, 
+        ClassLoader.getSystemClassLoader()
+    );
+    int count = 0;
+    for (var provider : localeProviders) {
+        println("  - " + provider.getClass().getName());
+        count++;
+        if (count >= 3) {
+            println("  ... (more providers exist)");
+            break;
+        }
+    }
+
+    // Demonstrate lazy loading nature of ServiceLoader
+    println("\nServiceLoader loads services lazily on iteration");
+    println("Services are discovered via META-INF/services files");
+}
+```
+
+The `ServiceLoader` uses the thread context class loader to discover service  
+implementations listed in `META-INF/services` files. This mechanism enables  
+loose coupling between service interfaces and their implementations, allowing  
+applications to discover implementations at runtime without hard-coded  
+dependencies.  
+
+
+## Security and class loading
+
+Class loaders play a crucial role in Java's security model by defining security  
+domains and enforcing access controls.  
+
+```java
+void main() {
+
+    // Examine protection domains
+    var stringPD = String.class.getProtectionDomain();
+    println("String ProtectionDomain: " + stringPD);
+
+    var thisPD = getClass().getProtectionDomain();
+    println("\nThis class ProtectionDomain: " + thisPD);
+
+    // Check code source
+    var thisCodeSource = thisPD.getCodeSource();
+    println("Code source: " + thisCodeSource);
+
+    if (thisCodeSource != null) {
+        println("Location: " + thisCodeSource.getLocation());
+        var certs = thisCodeSource.getCertificates();
+        println("Certificates: " + (certs != null ? certs.length : 0));
+    }
+
+    // Check permissions
+    var permissions = thisPD.getPermissions();
+    println("\nPermissions type: " + permissions.getClass().getSimpleName());
+
+    // Security best practices for custom class loaders
+    println("\nSecurity Best Practices:");
+    println("1. Always use parent delegation");
+    println("2. Validate bytecode before loading");
+    println("3. Set appropriate protection domains");
+    println("4. Don't expose class loader to untrusted code");
+    println("5. Consider using SecurityManager (deprecated in Java 17+)");
+
+    // Modern approach: use module system for encapsulation
+    println("\nModern approach: Use JPMS for encapsulation instead of SecurityManager");
+}
+```
+
+Each class is associated with a `ProtectionDomain` that defines its code source  
+and permissions. Custom class loaders should properly assign protection domains  
+to loaded classes. While the `SecurityManager` is deprecated, class loader  
+security remains important through proper code isolation and module system  
+encapsulation.  
+
+
+## Memory leak prevention
+
+Improper handling of class loaders can cause memory leaks. This example shows  
+how to properly manage class loader lifecycle.  
+
+```java
+import java.lang.ref.WeakReference;
+import java.net.URL;
+import java.net.URLClassLoader;
+import java.nio.file.Path;
+
+void main() {
+
+    println("Demonstrating class loader memory management\n");
+
+    // Create and properly close a class loader
+    WeakReference<ClassLoader> loaderRef;
+
+    try {
+        var url = Path.of("/tmp").toUri().toURL();
+        var loader = new URLClassLoader(new URL[]{url});
+        loaderRef = new WeakReference<>(loader);
+
+        println("Created class loader: " + loader);
+        println("Weak reference: " + loaderRef.get());
+
+        // Use the loader
+        try {
+            loader.loadClass("java.lang.String");
+        } catch (ClassNotFoundException e) {
+            // Expected for non-delegating loader
+        }
+
+        // Close the loader when done
+        loader.close();
+        println("Closed class loader");
+
+    } catch (Exception e) {
+        println("Error: " + e.getMessage());
+        return;
+    }
+
+    // Clear strong reference and suggest GC
+    System.gc();
+    Thread.yield();
+
+    println("\nAfter GC:");
+    println("Weak reference: " + loaderRef.get());
+
+    // Common memory leak causes
+    println("\nCommon Class Loader Memory Leak Causes:");
+    println("1. ThreadLocal variables not cleaned up");
+    println("2. Shutdown hooks not removed");
+    println("3. Static references to loaded classes");
+    println("4. JDBC drivers not deregistered");
+    println("5. Logging frameworks holding references");
+    println("6. JMX MBeans not unregistered");
+}
+```
+
+Class loader memory leaks occur when class loaders cannot be garbage collected  
+due to lingering references. Common causes include thread-local variables,  
+shutdown hooks, and static fields in loaded classes. Always close `URLClassLoader`  
+instances when done and clean up any resources that might hold references to  
+loaded classes.  
+
+
+## Handling ClassNotFoundException and NoClassDefFoundError
+
+Understanding the difference between these two exceptions is crucial for  
+debugging class loading issues.  
+
+```java
+void main() {
+
+    println("ClassNotFoundException vs NoClassDefFoundError\n");
+
+    // ClassNotFoundException: explicit loading fails
+    println("1. ClassNotFoundException:");
+    println("   Thrown when Class.forName or ClassLoader.loadClass fails");
+    try {
+        Class.forName("com.nonexistent.MyClass");
+    } catch (ClassNotFoundException e) {
+        println("   Caught: " + e.getClass().getSimpleName());
+        println("   Message: " + e.getMessage());
+    }
+
+    // NoClassDefFoundError: implicit loading fails
+    println("\n2. NoClassDefFoundError:");
+    println("   Thrown when JVM cannot find a class needed during execution");
+    println("   Usually caused by a class that was available at compile time");
+    println("   but missing at runtime");
+
+    // Simulate scenario that could cause NoClassDefFoundError
+    println("\n3. Common causes:");
+    println("   - Missing JAR file at runtime");
+    println("   - Class path misconfiguration");
+    println("   - Static initializer failure");
+
+    // ExceptionInInitializerError
+    println("\n4. ExceptionInInitializerError:");
+    println("   Thrown when a static initializer fails");
+
+    // Demonstrate with a failing static initializer
+    try {
+        Class.forName("FailingClass");
+    } catch (ExceptionInInitializerError e) {
+        println("   Caught: " + e.getClass().getSimpleName());
+        println("   Cause: " + e.getCause());
+    } catch (ClassNotFoundException e) {
+        println("   FailingClass not defined in this example");
+    }
+
+    // LinkageError hierarchy
+    println("\n5. Error Hierarchy:");
+    println("   Throwable");
+    println("   └── Error");
+    println("       └── LinkageError");
+    println("           ├── NoClassDefFoundError");
+    println("           ├── ClassCircularityError");
+    println("           ├── ClassFormatError");
+    println("           └── IncompatibleClassChangeError");
+}
+
+// Uncomment to demonstrate ExceptionInInitializerError
+// class FailingClass {
+//     static {
+//         if (true) throw new RuntimeException("Static init failed!");
+//     }
+// }
+```
+
+`ClassNotFoundException` is a checked exception thrown when explicit class  
+loading fails. `NoClassDefFoundError` is an error thrown when the JVM cannot  
+find a class that was available at compile time. The key difference is that  
+`ClassNotFoundException` occurs during dynamic loading, while `NoClassDefFoundError`  
+typically indicates a deployment or classpath configuration problem.  
+
+
+## Custom class loader for encrypted classes
+
+This example demonstrates a class loader that could decrypt classes before  
+loading them, useful for protecting proprietary code.  
+
+```java
+import javax.crypto.Cipher;
+import javax.crypto.spec.SecretKeySpec;
+import java.util.Base64;
+
+class EncryptedClassLoader extends ClassLoader {
+    private final byte[] key;
+
+    EncryptedClassLoader(String keyString, ClassLoader parent) {
+        super(parent);
+        this.key = keyString.getBytes();
+    }
+
+    // Simulated decryption method
+    byte[] decrypt(byte[] encrypted) throws Exception {
+        var keySpec = new SecretKeySpec(key, 0, 16, "AES");
+        var cipher = Cipher.getInstance("AES");
+        cipher.init(Cipher.DECRYPT_MODE, keySpec);
+        return cipher.doFinal(encrypted);
+    }
+
+    // Simulated encryption method for demonstration
+    byte[] encrypt(byte[] data) throws Exception {
+        var keySpec = new SecretKeySpec(key, 0, 16, "AES");
+        var cipher = Cipher.getInstance("AES");
+        cipher.init(Cipher.ENCRYPT_MODE, keySpec);
+        return cipher.doFinal(data);
+    }
+
+    @Override
+    protected Class<?> findClass(String name) throws ClassNotFoundException {
+        // In a real implementation, you would:
+        // 1. Read encrypted bytecode from file/network
+        // 2. Decrypt the bytecode
+        // 3. Call defineClass with decrypted bytes
+        throw new ClassNotFoundException(
+            "Encrypted class loading demonstration - no encrypted classes available");
+    }
+}
+
+void main() {
+
+    println("Encrypted Class Loader Demonstration\n");
+
+    // In production, retrieve key from secure storage (e.g., environment variable,
+    // key management service, or hardware security module)
+    var key = System.getenv("CLASS_ENCRYPTION_KEY");
+    if (key == null || key.length() < 16) {
+        // Fallback for demonstration only - never use hardcoded keys in production
+        key = "DemoKeyOnly16byt";
+        println("WARNING: Using demo key - set CLASS_ENCRYPTION_KEY env var in production\n");
+    }
+
+    var loader = new EncryptedClassLoader(key, ClassLoader.getSystemClassLoader());
+
+    println("Created encrypted class loader");
+    println("Key length: " + key.length() + " characters\n");
+
+    // Demonstrate encryption/decryption
+    try {
+        var original = "Hello, World!".getBytes();
+        println("Original: " + new String(original));
+
+        var encrypted = loader.encrypt(original);
+        println("Encrypted: " + Base64.getEncoder().encodeToString(encrypted));
+
+        var decrypted = loader.decrypt(encrypted);
+        println("Decrypted: " + new String(decrypted));
+
+    } catch (Exception e) {
+        println("Encryption error: " + e.getMessage());
+    }
+
+    // Try loading an encrypted class
+    println("\nAttempting to load encrypted class:");
+    try {
+        loader.loadClass("com.secret.ProtectedClass");
+    } catch (ClassNotFoundException e) {
+        println("Expected: " + e.getMessage());
+    }
+
+    println("\nUse Cases:");
+    println("- Protecting proprietary algorithms");
+    println("- License enforcement");
+    println("- Code obfuscation");
+    println("\nSecurity Note: Always use secure key management in production!");
+}
+```
+
+An encrypted class loader decrypts bytecode before passing it to `defineClass`.  
+This technique can protect proprietary code from reverse engineering. However,  
+it's not foolproof since the decryption key must be available at runtime, and  
+determined attackers can still extract the decrypted bytecode from memory.  
+Always use secure key management (environment variables, key management services,  
+or hardware security modules) rather than hardcoding keys in source code.  
+
+
+## Parallel class loading
+
+Java supports parallel class loading to improve performance when loading many  
+classes concurrently.  
+
+```java
+import java.util.concurrent.CountDownLatch;
+
+class ParallelCapableLoader extends ClassLoader {
+    static {
+        // Register this class loader as parallel capable
+        ClassLoader.registerAsParallelCapable();
+    }
+
+    ParallelCapableLoader(ClassLoader parent) {
+        super(parent);
+    }
+
+    @Override
+    protected Class<?> findClass(String name) throws ClassNotFoundException {
+        println("  Finding: " + name + " on " + Thread.currentThread().getName());
+        
+        // Simulate some loading time
+        try {
+            Thread.sleep(100);
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+        }
+
+        throw new ClassNotFoundException(name);
+    }
+}
+
+void main() throws InterruptedException {
+
+    println("Parallel Class Loading Demonstration\n");
+
+    var loader = new ParallelCapableLoader(getClass().getClassLoader());
+    var numThreads = 5;
+    var latch = new CountDownLatch(numThreads);
+
+    println("Starting " + numThreads + " concurrent class loading attempts:\n");
+
+    for (int i = 0; i < numThreads; i++) {
+        var className = "com.example.Class" + i;
+        new Thread(() -> {
+            try {
+                loader.loadClass(className);
+            } catch (ClassNotFoundException e) {
+                // Expected
+            } finally {
+                latch.countDown();
+            }
+        }, "Loader-" + i).start();
+    }
+
+    latch.await();
+
+    println("\nAll loading attempts completed");
+    println("\nBenefits of Parallel Class Loading:");
+    println("1. Improved startup time for large applications");
+    println("2. Better multi-core CPU utilization");
+    println("3. Reduced lock contention");
+    println("4. Required for modern application servers");
+}
+```
+
+By default, class loading is synchronized using a single lock per class loader.  
+Calling `registerAsParallelCapable` allows the class loader to load different  
+classes concurrently, significantly improving startup time for applications that  
+load many classes. Modern application servers and frameworks rely on parallel  
+class loading for performance.  
+
+
+## Class unloading and garbage collection
+
+This example explores how classes are unloaded when their class loader becomes  
+unreachable and is garbage collected.  
+
+```java
+import java.lang.ref.WeakReference;
+import java.net.URL;
+import java.net.URLClassLoader;
+import java.nio.file.Path;
+
+void main() throws Exception {
+
+    println("Class Unloading Demonstration\n");
+
+    // Track class references
+    WeakReference<Class<?>> classRef;
+    WeakReference<ClassLoader> loaderRef;
+
+    {
+        var url = Path.of(".").toUri().toURL();
+        var loader = new URLClassLoader(new URL[]{url});
+        loaderRef = new WeakReference<>(loader);
+
+        // Load a standard library class
+        var loadedClass = loader.loadClass("java.util.ArrayList");
+        classRef = new WeakReference<>(loadedClass);
+
+        println("Class loaded: " + loadedClass.getName());
+        println("Loader: " + loader);
+        println("Class identity: " + System.identityHashCode(loadedClass));
+
+        // Close the loader
+        loader.close();
+        println("\nLoader closed");
+
+        // Clear references
+        loader = null;
+        loadedClass = null;
+    }
+
+    // Request garbage collection
+    println("\nRequesting garbage collection...");
+    for (int i = 0; i < 5; i++) {
+        System.gc();
+        Thread.sleep(100);
+    }
+
+    println("\nAfter GC:");
+    println("Loader reference: " + loaderRef.get());
+    println("Class reference: " + classRef.get());
+
+    println("\nClass Unloading Rules:");
+    println("1. All instances of the class must be GC'd");
+    println("2. The Class object must be unreachable");
+    println("3. The ClassLoader must be unreachable");
+    println("4. Bootstrap-loaded classes are never unloaded");
+    println("5. System class loader classes are never unloaded");
+}
+```
+
+Classes can only be unloaded when their defining class loader is garbage  
+collected, which requires that no references exist to the class loader or any  
+classes it loaded. Classes loaded by the bootstrap or system class loaders  
+are never unloaded. This is why proper class loader management is essential  
+in long-running applications with plugin architectures.  
+
+
+## Best practices summary
+
+This final example summarizes the key best practices for working with class  
+loaders in Java applications.  
+
+```java
+void main() {
+
+    println("╔══════════════════════════════════════════════════════════════════╗");
+    println("║           Class Loader Best Practices Summary                    ║");
+    println("╚══════════════════════════════════════════════════════════════════╝");
+
+    println("\n┌─ DESIGN PRINCIPLES ─────────────────────────────────────────────┐");
+    println("│ 1. Always follow parent delegation unless you have a good reason │");
+    println("│ 2. Override findClass, not loadClass, in custom loaders          │");
+    println("│ 3. Use URLClassLoader for file/JAR loading when possible         │");
+    println("│ 4. Make class loaders closeable and implement close properly     │");
+    println("│ 5. Consider thread context class loader for library code         │");
+    println("└──────────────────────────────────────────────────────────────────┘");
+
+    println("\n┌─ MEMORY MANAGEMENT ─────────────────────────────────────────────┐");
+    println("│ 1. Always close URLClassLoader instances when done               │");
+    println("│ 2. Remove ThreadLocal values before unloading                    │");
+    println("│ 3. Deregister JDBC drivers before unloading                      │");
+    println("│ 4. Clear any static references to loaded classes                 │");
+    println("│ 5. Unregister JMX MBeans before unloading                        │");
+    println("└──────────────────────────────────────────────────────────────────┘");
+
+    println("\n┌─ SECURITY ─────────────────────────────────────────────────────┐");
+    println("│ 1. Validate bytecode before loading from untrusted sources       │");
+    println("│ 2. Set appropriate protection domains                            │");
+    println("│ 3. Use JPMS for encapsulation in modern Java                     │");
+    println("│ 4. Avoid exposing class loaders to untrusted code                │");
+    println("│ 5. Be cautious with URL class loading from remote sources        │");
+    println("└──────────────────────────────────────────────────────────────────┘");
+
+    println("\n┌─ DEBUGGING ────────────────────────────────────────────────────┐");
+    println("│ 1. Use -verbose:class to trace class loading                     │");
+    println("│ 2. Check getCodeSource for class origin                          │");
+    println("│ 3. Traverse class loader hierarchy for debugging                 │");
+    println("│ 4. Use heap dumps to find class loader leaks                     │");
+    println("│ 5. Monitor Metaspace for class loading issues                    │");
+    println("└──────────────────────────────────────────────────────────────────┘");
+
+    println("\n┌─ WHEN TO USE CUSTOM CLASS LOADERS ─────────────────────────────┐");
+    println("│ ✓ Plugin/module systems with isolation requirements              │");
+    println("│ ✓ Hot deployment and class reloading                             │");
+    println("│ ✓ Loading classes from non-standard locations                    │");
+    println("│ ✓ Bytecode transformation and instrumentation                    │");
+    println("│ ✗ Avoid for simple applications (use standard loaders)           │");
+    println("└──────────────────────────────────────────────────────────────────┘");
+
+    // Demonstrate JVM class loading flags
+    println("\n┌─ USEFUL JVM FLAGS ──────────────────────────────────────────────┐");
+    println("│ -verbose:class          Show class loading details               │");
+    println("│ -Xlog:class+load=info   JVM unified logging for class loading    │");
+    println("│ -XX:+TraceClassLoading  Trace class loading (deprecated)         │");
+    println("│ -XX:+TraceClassUnloading Trace class unloading                   │");
+    println("└──────────────────────────────────────────────────────────────────┘");
+}
+```
+
+Following these best practices will help you avoid common pitfalls when working  
+with class loaders. The key is to understand the parent delegation model, manage  
+class loader lifecycle properly, and use custom class loaders only when standard  
+mechanisms are insufficient. Always clean up resources and references when  
+unloading class loaders to prevent memory leaks.  
diff --git a/collections/eclipse-collections.md b/collections/eclipse-collections.md
new file mode 100644
index 00000000..ae12e332
--- /dev/null
+++ b/collections/eclipse-collections.md
@@ -0,0 +1,28 @@
+# Eclipse collections
+
+Place the two JARS into the `lib` and run on command line: `java -cp "lib\*" Main.java`
+
+```java
+import org.eclipse.collections.api.list.MutableList;
+import org.eclipse.collections.impl.factory.Lists;
+
+void main() {
+
+    MutableList<User> users = Lists.mutable.with(
+            new User("Sally", "Smith"),
+            new User("Ted", "Watson"),
+            new User("Paul", "Smith"),
+            new User("Mary", "Williams"));
+
+    MutableList<User> smiths = users.select(user -> user.lastNameEquals("Smith"));
+    String res = smiths.collect(User::lastName).makeString();
+    System.out.println(res);
+}
+
+record User(String firstName, String lastName) {
+    public boolean lastNameEquals(String name) {
+        return name.equals(this.lastName);
+    }
+}
+```
+
diff --git a/comparesort/CompareListsEx3.java b/comparesort/CompareListsEx3.java
deleted file mode 100644
index 6948402b..00000000
--- a/comparesort/CompareListsEx3.java
+++ /dev/null
@@ -1,14 +0,0 @@
-package com.zetcode;
-
-import java.util.ArrayList;
-import java.util.Comparator;
-import java.util.List;
-
-public class CompareListsEx3 {
-
-    public static void main(String[] args) {
-
-
-    }
-}
-
diff --git a/completablefuture.md b/completablefuture.md
new file mode 100644
index 00000000..4c0e0fed
--- /dev/null
+++ b/completablefuture.md
@@ -0,0 +1,1368 @@
+# CompletableFuture and Asynchronous Programming
+
+Asynchronous programming enables non-blocking execution of tasks, allowing  
+applications to remain responsive while performing time-consuming operations.  
+`CompletableFuture`, introduced in Java 8, provides a powerful and flexible API  
+for composing asynchronous computations. This document explores the fundamental  
+concepts, practical patterns, and best practices for mastering asynchronous  
+programming in Java.  
+
+## Why Asynchronous Programming Matters  
+
+Traditional synchronous programming executes operations sequentially, blocking  
+the current thread until each operation completes. While simple to understand,  
+this approach leads to poor resource utilization and unresponsive applications,  
+especially when dealing with I/O operations, network calls, or database queries.  
+
+Consider a web server handling thousands of concurrent requests. If each request  
+blocks a thread while waiting for a database response, the server quickly runs  
+out of available threads, leading to increased latency and reduced throughput.  
+Asynchronous programming addresses this by allowing threads to handle other work  
+while waiting for slow operations to complete.  
+
+| Aspect | Synchronous | Asynchronous |
+|--------|-------------|--------------|
+| Execution | Sequential, blocking | Concurrent, non-blocking |
+| Thread usage | One thread per task | Threads shared across tasks |
+| Responsiveness | Can freeze UI/server | Remains responsive |
+| Complexity | Simple control flow | Callback management |
+| Scalability | Limited by threads | Highly scalable |
+
+## Evolution of Java Concurrency  
+
+Java's concurrency model has evolved significantly over the years:  
+
+**Java 1.0 (1996)**: Basic `Thread` class and `Runnable` interface introduced  
+low-level thread management. Developers manually created and synchronized threads,  
+leading to complex and error-prone code.  
+
+**Java 5 (2004)**: The `java.util.concurrent` package brought `ExecutorService`,  
+`Future`, and thread pools. This abstracted thread lifecycle management but still  
+required blocking calls to retrieve results.  
+
+**Java 8 (2014)**: `CompletableFuture` revolutionized async programming with  
+fluent APIs for chaining, combining, and handling errors in asynchronous  
+computations.  
+
+**Java 21 (2023)**: Virtual threads and structured concurrency further simplified  
+concurrent programming, making thread-per-request architectures practical.  
+
+## Limitations of Future  
+
+The `Future` interface, while useful, has significant limitations that  
+`CompletableFuture` addresses:  
+
+```java
+import java.util.concurrent.Callable;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+
+void main() throws Exception {
+
+    ExecutorService executor = Executors.newSingleThreadExecutor();
+
+    Future<String> future = executor.submit(() -> {
+        Thread.sleep(1000);
+        return "Result from Future";
+    });
+
+    // Blocking call - thread waits here
+    String result = future.get();
+    println("Received: " + result);
+
+    executor.shutdown();
+}
+```
+
+The traditional `Future` requires blocking calls to retrieve results. There is  
+no way to chain operations, combine multiple futures, or handle exceptions in  
+a functional style. `CompletableFuture` solves all of these limitations by  
+providing callback-based completion, fluent chaining APIs, and comprehensive  
+exception handling mechanisms.  
+
+## Creating a CompletableFuture  
+
+`CompletableFuture` can be created in several ways, from simple completed  
+futures to asynchronous suppliers.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+
+void main() throws Exception {
+
+    // Create an already completed future
+    var completed = CompletableFuture.completedFuture("Hello");
+    println("Completed value: " + completed.get());
+
+    // Create an empty future to complete later
+    var manual = new CompletableFuture<String>();
+    manual.complete("Manually completed");
+    println("Manual value: " + manual.get());
+
+    // Create a failed future
+    var failed = CompletableFuture.<String>failedFuture(
+        new RuntimeException("Intentional failure")
+    );
+    println("Failed: " + failed.isCompletedExceptionally());
+}
+```
+
+These factory methods provide flexibility for different scenarios. Completed  
+futures are useful for testing or when a value is immediately available.  
+Manually completing futures enables integration with callback-based APIs or  
+external systems that don't return `CompletableFuture` directly.  
+
+## Asynchronous execution with supplyAsync  
+
+The `supplyAsync` method runs a `Supplier` asynchronously and returns a  
+`CompletableFuture` with the result.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+
+void main() throws Exception {
+
+    var future = CompletableFuture.supplyAsync(() -> {
+        println("Computing in: " + Thread.currentThread().getName());
+        try {
+            Thread.sleep(1000);
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+        }
+        return 42;
+    });
+
+    println("Main thread continues immediately...");
+    println("Result: " + future.get());
+}
+```
+
+By default, `supplyAsync` uses the common `ForkJoinPool`. The computation runs  
+in a separate thread while the main thread continues. Calling `get` blocks  
+until the result is available, but the async computation has already started  
+in parallel.  
+
+## Fire-and-forget with runAsync  
+
+When you don't need a return value, use `runAsync` to execute a `Runnable`  
+asynchronously.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+
+void main() throws Exception {
+
+    var future = CompletableFuture.runAsync(() -> {
+        println("Logging in: " + Thread.currentThread().getName());
+        try {
+            Thread.sleep(500);
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+        }
+        println("Log entry saved");
+    });
+
+    println("Main thread not blocked");
+    future.join();
+    println("Logging complete");
+}
+```
+
+The `runAsync` method returns `CompletableFuture<Void>` since there's no result.  
+Using `join` instead of `get` avoids checked exceptions but still blocks until  
+completion. This pattern is ideal for side effects like logging, notifications,  
+or cache updates.  
+
+## Transforming results with thenApply  
+
+The `thenApply` method transforms the result of a `CompletableFuture` using a  
+function, similar to `map` on streams.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+
+void main() {
+
+    var result = CompletableFuture.supplyAsync(() -> "hello")
+        .thenApply(s -> s.toUpperCase())
+        .thenApply(s -> s + " WORLD")
+        .thenApply(s -> s.length())
+        .join();
+
+    println("Final length: " + result);
+}
+```
+
+Each `thenApply` creates a new stage in the async pipeline. The transformations  
+execute sequentially after the previous stage completes. This enables fluent,  
+functional-style processing of async results without manual callback nesting.  
+
+## Consuming results with thenAccept  
+
+Use `thenAccept` when you want to consume the result without producing a new  
+value.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+
+void main() throws Exception {
+
+    CompletableFuture.supplyAsync(() -> {
+        try { Thread.sleep(500); } catch (InterruptedException e) {}
+        return List.of("apple", "banana", "cherry");
+    })
+    .thenAccept(fruits -> {
+        println("Received " + fruits.size() + " fruits:");
+        fruits.forEach(f -> println("  - " + f));
+    })
+    .join();
+}
+```
+
+The `thenAccept` method returns `CompletableFuture<Void>` since the consumer  
+doesn't produce a value. This is useful for final processing steps like  
+displaying results, sending notifications, or updating UI elements.  
+
+## Running actions with thenRun  
+
+The `thenRun` method executes a `Runnable` after completion, ignoring both the  
+result and any transformation.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+
+void main() {
+
+    CompletableFuture.supplyAsync(() -> {
+        println("Step 1: Fetching data...");
+        try { Thread.sleep(500); } catch (InterruptedException e) {}
+        return "data";
+    })
+    .thenRun(() -> println("Step 2: Processing complete notification"))
+    .thenRun(() -> println("Step 3: Cleanup started"))
+    .join();
+
+    println("All steps finished");
+}
+```
+
+Use `thenRun` for actions that don't depend on the result, such as cleanup,  
+logging, or triggering follow-up processes. Multiple `thenRun` calls chain  
+sequentially, each waiting for the previous to complete.  
+
+## Async variants for non-blocking chains  
+
+Each chaining method has an `Async` variant that runs in a separate thread.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+
+void main() {
+
+    CompletableFuture.supplyAsync(() -> {
+        println("Supply: " + Thread.currentThread().getName());
+        return "hello";
+    })
+    .thenApplyAsync(s -> {
+        println("Apply: " + Thread.currentThread().getName());
+        return s.toUpperCase();
+    })
+    .thenAcceptAsync(s -> {
+        println("Accept: " + Thread.currentThread().getName());
+        println("Result: " + s);
+    })
+    .join();
+}
+```
+
+Without the `Async` suffix, callbacks run in the same thread that completed the  
+previous stage. With `Async`, each stage may run in a different thread from the  
+common pool. Use async variants when transformations are CPU-intensive or when  
+you need to avoid blocking the completing thread.  
+
+## Combining two futures with thenCombine  
+
+The `thenCombine` method waits for two independent futures and combines their  
+results.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+
+void main() {
+
+    var priceFuture = CompletableFuture.supplyAsync(() -> {
+        try { Thread.sleep(800); } catch (InterruptedException e) {}
+        return 100.0;
+    });
+
+    var discountFuture = CompletableFuture.supplyAsync(() -> {
+        try { Thread.sleep(500); } catch (InterruptedException e) {}
+        return 0.15;
+    });
+
+    var finalPrice = priceFuture
+        .thenCombine(discountFuture, (price, discount) -> 
+            price * (1 - discount))
+        .join();
+
+    println("Final price: $" + finalPrice);
+}
+```
+
+Both futures run concurrently. When both complete, the combining function  
+executes with their results. This is ideal for aggregating data from multiple  
+independent sources, such as fetching user profile and preferences  
+simultaneously.  
+
+## Sequential composition with thenCompose  
+
+Use `thenCompose` when the next async operation depends on the result of the  
+previous one, similar to `flatMap` on streams.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+
+void main() {
+
+    var result = fetchUserId("alice")
+        .thenCompose(userId -> fetchUserDetails(userId))
+        .thenCompose(details -> fetchUserOrders(details))
+        .join();
+
+    println("Orders: " + result);
+}
+
+CompletableFuture<Integer> fetchUserId(String username) {
+    return CompletableFuture.supplyAsync(() -> {
+        println("Fetching user ID for: " + username);
+        try { Thread.sleep(300); } catch (InterruptedException e) {}
+        return 42;
+    });
+}
+
+CompletableFuture<String> fetchUserDetails(int userId) {
+    return CompletableFuture.supplyAsync(() -> {
+        println("Fetching details for user: " + userId);
+        try { Thread.sleep(300); } catch (InterruptedException e) {}
+        return "UserDetails{id=" + userId + "}";
+    });
+}
+
+CompletableFuture<List<String>> fetchUserOrders(String details) {
+    return CompletableFuture.supplyAsync(() -> {
+        println("Fetching orders for: " + details);
+        try { Thread.sleep(300); } catch (InterruptedException e) {}
+        return List.of("Order1", "Order2", "Order3");
+    });
+}
+```
+
+Unlike `thenApply`, which would return `CompletableFuture<CompletableFuture<T>>`,  
+`thenCompose` flattens the result. This creates clean, readable chains for  
+dependent async operations like database lookups or API calls.  
+
+## Handling exceptions with exceptionally  
+
+The `exceptionally` method provides a fallback value when an exception occurs.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+
+void main() {
+
+    var result = CompletableFuture.supplyAsync(() -> {
+        if (Math.random() > 0.5) {
+            throw new RuntimeException("Random failure!");
+        }
+        return "Success";
+    })
+    .exceptionally(ex -> {
+        println("Caught: " + ex.getMessage());
+        return "Fallback value";
+    })
+    .join();
+
+    println("Result: " + result);
+}
+```
+
+The `exceptionally` callback receives the exception and returns a replacement  
+value of the same type. This enables graceful degradation, like returning  
+cached data or default values when a service call fails.  
+
+## Comprehensive handling with handle  
+
+The `handle` method processes both success and failure cases in a single  
+callback.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+
+void main() {
+
+    processValue(10);
+    processValue(-5);
+}
+
+void processValue(int input) {
+    var result = CompletableFuture.supplyAsync(() -> {
+        if (input < 0) {
+            throw new IllegalArgumentException("Negative not allowed: " + input);
+        }
+        return input * 2;
+    })
+    .handle((value, ex) -> {
+        if (ex != null) {
+            println("Error for " + input + ": " + ex.getCause().getMessage());
+            return 0;
+        }
+        return value;
+    })
+    .join();
+
+    println("Processed " + input + " -> " + result);
+}
+```
+
+Unlike `exceptionally`, `handle` always executes, receiving either the result  
+or the exception (one will be null). This is useful for logging, cleanup, or  
+transforming both success and failure into a unified response format.  
+
+## Observing completion with whenComplete  
+
+The `whenComplete` method runs a callback after completion without transforming  
+the result.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+
+void main() {
+
+    CompletableFuture.supplyAsync(() -> {
+        if (Math.random() > 0.5) {
+            throw new RuntimeException("Task failed");
+        }
+        return "Task succeeded";
+    })
+    .whenComplete((result, ex) -> {
+        if (ex != null) {
+            println("Completed with error: " + ex.getMessage());
+        } else {
+            println("Completed with result: " + result);
+        }
+    })
+    .exceptionally(ex -> "Recovered")
+    .thenAccept(r -> println("Final: " + r))
+    .join();
+}
+```
+
+The `whenComplete` callback observes the result but doesn't change it. Unlike  
+`handle`, exceptions propagate to downstream stages. This is perfect for  
+logging, metrics, or auditing without affecting the pipeline's result.  
+
+## Waiting for all futures with allOf  
+
+The `allOf` method creates a future that completes when all provided futures  
+complete.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+
+void main() {
+
+    var futures = List.of(
+        fetchData("Service A", 1000),
+        fetchData("Service B", 500),
+        fetchData("Service C", 750)
+    );
+
+    CompletableFuture.allOf(futures.toArray(new CompletableFuture[0]))
+        .thenRun(() -> {
+            println("All services responded:");
+            futures.forEach(f -> println("  - " + f.join()));
+        })
+        .join();
+}
+
+CompletableFuture<String> fetchData(String service, int delay) {
+    return CompletableFuture.supplyAsync(() -> {
+        try { Thread.sleep(delay); } catch (InterruptedException e) {}
+        return service + " data";
+    });
+}
+```
+
+All futures execute concurrently. The combined future completes when the  
+slowest one finishes. Note that `allOf` returns `CompletableFuture<Void>`, so  
+you must access individual futures to get their results.  
+
+## Racing futures with anyOf  
+
+The `anyOf` method completes as soon as any of the provided futures completes.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+
+void main() {
+
+    var primary = queryServer("Primary", 1000);
+    var backup = queryServer("Backup", 500);
+    var fallback = queryServer("Fallback", 750);
+
+    var fastest = CompletableFuture.anyOf(primary, backup, fallback)
+        .thenApply(result -> (String) result)
+        .join();
+
+    println("Fastest response: " + fastest);
+}
+
+CompletableFuture<String> queryServer(String name, int responseTime) {
+    return CompletableFuture.supplyAsync(() -> {
+        try { Thread.sleep(responseTime); } catch (InterruptedException e) {}
+        println(name + " responded");
+        return name + " data";
+    });
+}
+```
+
+This pattern is useful for redundant requests to multiple servers, taking the  
+fastest response. The other futures continue running unless explicitly  
+cancelled. Note that `anyOf` returns `CompletableFuture<Object>`, requiring a  
+cast.  
+
+## Collecting results from multiple futures  
+
+Aggregating results from multiple `CompletableFutures` into a single list  
+requires combining `allOf` with stream operations.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+import java.util.stream.Stream;
+
+void main() {
+
+    var productIds = List.of(1, 2, 3, 4, 5);
+
+    var futures = productIds.stream()
+        .map(id -> fetchProduct(id))
+        .toList();
+
+    var allProducts = CompletableFuture.allOf(
+            futures.toArray(new CompletableFuture[0]))
+        .thenApply(v -> futures.stream()
+            .map(CompletableFuture::join)
+            .toList())
+        .join();
+
+    println("Fetched " + allProducts.size() + " products:");
+    allProducts.forEach(p -> println("  " + p));
+}
+
+CompletableFuture<String> fetchProduct(int id) {
+    return CompletableFuture.supplyAsync(() -> {
+        try { Thread.sleep((long)(Math.random() * 500)); } 
+        catch (InterruptedException e) {}
+        return "Product-" + id;
+    });
+}
+```
+
+This pattern launches all fetches concurrently, waits for all to complete,  
+then collects results into a list. The total time is approximately that of the  
+slowest fetch, not the sum of all fetches.  
+
+## Using custom executors  
+
+You can provide a custom `Executor` to control where async tasks run.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+
+void main() {
+
+    ExecutorService customPool = Executors.newFixedThreadPool(4, r -> {
+        var thread = new Thread(r);
+        thread.setName("CustomWorker-" + thread.getId());
+        return thread;
+    });
+
+    try {
+        var result = CompletableFuture.supplyAsync(() -> {
+            println("Running in: " + Thread.currentThread().getName());
+            return "Hello";
+        }, customPool)
+        .thenApplyAsync(s -> {
+            println("Transforming in: " + Thread.currentThread().getName());
+            return s.toUpperCase();
+        }, customPool)
+        .join();
+
+        println("Result: " + result);
+    } finally {
+        customPool.shutdown();
+    }
+}
+```
+
+Custom executors allow tuning pool sizes for specific workloads, isolating  
+different task types, or implementing custom thread naming for debugging.  
+Always shut down custom executors to prevent resource leaks.  
+
+## Virtual thread executor integration  
+
+Java 21's virtual threads work seamlessly with `CompletableFuture` for highly  
+scalable async operations.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.Executors;
+
+void main() {
+
+    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+        var futures = new ArrayList<CompletableFuture<String>>();
+
+        for (int i = 1; i <= 100; i++) {
+            int id = i;
+            futures.add(CompletableFuture.supplyAsync(() -> {
+                try { Thread.sleep(100); } catch (InterruptedException e) {}
+                return "Task-" + id + " on " + Thread.currentThread();
+            }, executor));
+        }
+
+        CompletableFuture.allOf(futures.toArray(new CompletableFuture[0]))
+            .join();
+
+        println("Completed " + futures.size() + " tasks");
+        println("Sample: " + futures.get(0).join());
+    }
+}
+```
+
+Virtual threads are lightweight and ideal for I/O-bound tasks. Each task gets  
+its own virtual thread without the overhead of platform threads, enabling  
+millions of concurrent operations.  
+
+## Timeout handling  
+
+The `orTimeout` and `completeOnTimeout` methods provide built-in timeout  
+support.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.TimeUnit;
+
+void main() {
+
+    // Fails with TimeoutException
+    try {
+        CompletableFuture.supplyAsync(() -> {
+            try { Thread.sleep(2000); } catch (InterruptedException e) {}
+            return "Slow result";
+        })
+        .orTimeout(1, TimeUnit.SECONDS)
+        .join();
+    } catch (Exception e) {
+        println("Timed out: " + e.getCause().getClass().getSimpleName());
+    }
+
+    // Completes with default value on timeout
+    var result = CompletableFuture.supplyAsync(() -> {
+        try { Thread.sleep(2000); } catch (InterruptedException e) {}
+        return "Slow result";
+    })
+    .completeOnTimeout("Default value", 1, TimeUnit.SECONDS)
+    .join();
+
+    println("Result: " + result);
+}
+```
+
+Use `orTimeout` when timeouts should fail fast and propagate errors. Use  
+`completeOnTimeout` when you want a graceful fallback. Both methods were  
+added in Java 9 and simplify timeout handling compared to manual approaches.  
+
+## Delayed execution  
+
+The `delayedExecutor` method creates an executor that delays task execution.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+
+void main() {
+
+    var delayedExecutor = CompletableFuture.delayedExecutor(
+        2, TimeUnit.SECONDS
+    );
+
+    println("Starting at: " + java.time.LocalTime.now());
+
+    CompletableFuture.supplyAsync(() -> {
+        println("Executing at: " + java.time.LocalTime.now());
+        return "Delayed result";
+    }, delayedExecutor)
+    .thenAccept(r -> println("Received: " + r))
+    .join();
+}
+```
+
+This is useful for implementing retry delays, scheduled tasks, or rate  
+limiting. The delayed executor wraps the common pool by default but can  
+wrap a custom executor for more control.  
+
+## Parallel API calls  
+
+A common use case is fetching data from multiple APIs concurrently.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+
+void main() {
+
+    var startTime = System.currentTimeMillis();
+
+    var userFuture = fetchFromApi("/users/1", 500);
+    var ordersFuture = fetchFromApi("/orders?user=1", 700);
+    var preferencesFuture = fetchFromApi("/preferences/1", 300);
+
+    var combined = userFuture
+        .thenCombine(ordersFuture, (user, orders) -> 
+            "User: " + user + ", Orders: " + orders)
+        .thenCombine(preferencesFuture, (partial, prefs) -> 
+            partial + ", Prefs: " + prefs)
+        .join();
+
+    var elapsed = System.currentTimeMillis() - startTime;
+    println("Combined result: " + combined);
+    println("Total time: " + elapsed + "ms (parallel, not 1500ms)");
+}
+
+CompletableFuture<String> fetchFromApi(String endpoint, int latency) {
+    return CompletableFuture.supplyAsync(() -> {
+        try { Thread.sleep(latency); } catch (InterruptedException e) {}
+        return endpoint.substring(1).replace("/", "_");
+    });
+}
+```
+
+By launching all requests simultaneously, the total time is limited by the  
+slowest request (~700ms) rather than the sum (~1500ms). This pattern  
+dramatically improves response times in microservices architectures.  
+
+## Processing a stream asynchronously  
+
+Combining streams with `CompletableFuture` enables parallel data processing.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+
+void main() {
+
+    var items = List.of("apple", "banana", "cherry", "date", "elderberry");
+
+    var processedFutures = items.stream()
+        .map(item -> processAsync(item))
+        .toList();
+
+    var results = processedFutures.stream()
+        .map(CompletableFuture::join)
+        .toList();
+
+    println("Processed items:");
+    results.forEach(r -> println("  " + r));
+}
+
+CompletableFuture<String> processAsync(String item) {
+    return CompletableFuture.supplyAsync(() -> {
+        try { 
+            Thread.sleep((long)(Math.random() * 500)); 
+        } catch (InterruptedException e) {}
+        return item.toUpperCase() + " (processed)";
+    });
+}
+```
+
+Each item is processed concurrently. The `map` to `CompletableFuture` launches  
+tasks immediately, then `join` collects results. This pattern is more flexible  
+than parallel streams when you need fine-grained control over execution.  
+
+## Retry pattern with CompletableFuture  
+
+Implementing retry logic for transient failures.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.atomic.AtomicInteger;
+
+void main() {
+
+    var result = retryAsync(() -> unreliableOperation(), 3)
+        .exceptionally(ex -> "All retries failed: " + ex.getMessage())
+        .join();
+
+    println("Final result: " + result);
+}
+
+AtomicInteger attempts = new AtomicInteger(0);
+
+CompletableFuture<String> unreliableOperation() {
+    return CompletableFuture.supplyAsync(() -> {
+        int attempt = attempts.incrementAndGet();
+        println("Attempt " + attempt);
+        if (attempt < 3) {
+            throw new RuntimeException("Transient failure");
+        }
+        return "Success on attempt " + attempt;
+    });
+}
+
+<T> CompletableFuture<T> retryAsync(
+    java.util.function.Supplier<CompletableFuture<T>> operation, 
+    int maxRetries
+) {
+    return operation.get().exceptionallyCompose(ex -> {
+        if (maxRetries > 0) {
+            println("Retrying... " + maxRetries + " attempts left");
+            return retryAsync(operation, maxRetries - 1);
+        }
+        return CompletableFuture.failedFuture(ex);
+    });
+}
+```
+
+The `exceptionallyCompose` method enables returning a new `CompletableFuture`  
+on failure, perfect for retry scenarios. This pattern handles transient  
+failures gracefully without blocking the calling thread.  
+
+## Cache-aside pattern  
+
+Implementing asynchronous cache lookups with fallback to the source.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.ConcurrentHashMap;
+
+void main() {
+
+    var cache = new ConcurrentHashMap<String, String>();
+
+    // First call - cache miss, fetches from source
+    var result1 = getWithCache("user:123", cache).join();
+    println("First call: " + result1);
+
+    // Second call - cache hit
+    var result2 = getWithCache("user:123", cache).join();
+    println("Second call: " + result2);
+}
+
+CompletableFuture<String> getWithCache(
+    String key, 
+    ConcurrentHashMap<String, String> cache
+) {
+    var cached = cache.get(key);
+    if (cached != null) {
+        println("Cache hit for: " + key);
+        return CompletableFuture.completedFuture(cached);
+    }
+
+    println("Cache miss for: " + key);
+    return fetchFromDatabase(key)
+        .thenApply(value -> {
+            cache.put(key, value);
+            return value;
+        });
+}
+
+CompletableFuture<String> fetchFromDatabase(String key) {
+    return CompletableFuture.supplyAsync(() -> {
+        try { Thread.sleep(500); } catch (InterruptedException e) {}
+        return "Data for " + key + " from DB";
+    });
+}
+```
+
+This pattern checks the cache synchronously (fast path) and only goes async  
+for cache misses. The cache is updated after fetching, benefiting subsequent  
+requests. Consider using `computeIfAbsent` for atomic cache population.  
+
+## Circuit breaker integration  
+
+Implementing a simple circuit breaker to prevent cascading failures.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.concurrent.atomic.AtomicLong;
+
+void main() {
+
+    var breaker = new CircuitBreaker(3, 5000);
+
+    for (int i = 1; i <= 10; i++) {
+        int call = i;
+        breaker.execute(() -> unreliableService(call))
+            .exceptionally(ex -> "Call " + call + " failed: " + ex.getMessage())
+            .thenAccept(r -> println(r))
+            .join();
+    }
+}
+
+CompletableFuture<String> unreliableService(int callNum) {
+    return CompletableFuture.supplyAsync(() -> {
+        if (callNum <= 4) {
+            throw new RuntimeException("Service unavailable");
+        }
+        return "Call " + callNum + " succeeded";
+    });
+}
+
+class CircuitBreaker {
+    private final int threshold;
+    private final long resetTimeout;
+    private final AtomicInteger failures = new AtomicInteger(0);
+    private final AtomicLong lastFailure = new AtomicLong(0);
+
+    CircuitBreaker(int threshold, long resetTimeout) {
+        this.threshold = threshold;
+        this.resetTimeout = resetTimeout;
+    }
+
+    <T> CompletableFuture<T> execute(
+        java.util.function.Supplier<CompletableFuture<T>> operation
+    ) {
+        if (isOpen()) {
+            return CompletableFuture.failedFuture(
+                new RuntimeException("Circuit breaker is OPEN")
+            );
+        }
+
+        return operation.get()
+            .whenComplete((result, ex) -> {
+                if (ex != null) {
+                    failures.incrementAndGet();
+                    lastFailure.set(System.currentTimeMillis());
+                } else {
+                    failures.set(0);
+                }
+            });
+    }
+
+    boolean isOpen() {
+        if (failures.get() >= threshold) {
+            if (System.currentTimeMillis() - lastFailure.get() > resetTimeout) {
+                failures.set(0);
+                return false;
+            }
+            return true;
+        }
+        return false;
+    }
+}
+```
+
+The circuit breaker tracks failures and "opens" after a threshold, rejecting  
+requests without attempting the operation. After a timeout, it "half-opens"  
+to test recovery. This prevents overwhelming failing services.  
+
+## Fan-out fan-in pattern  
+
+Distributing work across multiple workers and aggregating results.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+
+void main() {
+
+    var data = List.of(1, 2, 3, 4, 5, 6, 7, 8, 9, 10);
+    var partitionSize = 3;
+
+    ExecutorService workers = Executors.newFixedThreadPool(4);
+
+    try {
+        // Fan-out: partition data and process concurrently
+        var partitions = partition(data, partitionSize);
+        
+        var futures = partitions.stream()
+            .map(partition -> CompletableFuture.supplyAsync(
+                () -> processPartition(partition), workers))
+            .toList();
+
+        // Fan-in: aggregate results
+        var total = CompletableFuture.allOf(
+            futures.toArray(new CompletableFuture[0]))
+            .thenApply(v -> futures.stream()
+                .mapToInt(CompletableFuture::join)
+                .sum())
+            .join();
+
+        println("Total sum: " + total);
+    } finally {
+        workers.shutdown();
+    }
+}
+
+int processPartition(List<Integer> partition) {
+    println("Processing " + partition + " on " + 
+        Thread.currentThread().getName());
+    try { Thread.sleep(500); } catch (InterruptedException e) {}
+    return partition.stream().mapToInt(Integer::intValue).sum();
+}
+
+<T> List<List<T>> partition(List<T> list, int size) {
+    var result = new ArrayList<List<T>>();
+    for (int i = 0; i < list.size(); i += size) {
+        result.add(list.subList(i, Math.min(i + size, list.size())));
+    }
+    return result;
+}
+```
+
+This pattern divides work into partitions processed concurrently, then  
+combines results. It's effective for parallel aggregations, map-reduce  
+operations, or batch processing.  
+
+## Event-driven completion  
+
+Using `CompletableFuture` to bridge callback-based APIs.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+import java.util.function.Consumer;
+
+void main() {
+
+    // Simulated async API with callbacks
+    var result = toCompletableFuture(callback -> {
+        new Thread(() -> {
+            try { Thread.sleep(500); } catch (InterruptedException e) {}
+            callback.accept("Data from callback API");
+        }).start();
+    }).join();
+
+    println("Result: " + result);
+}
+
+<T> CompletableFuture<T> toCompletableFuture(
+    Consumer<Consumer<T>> asyncOperation
+) {
+    var future = new CompletableFuture<T>();
+    asyncOperation.accept(future::complete);
+    return future;
+}
+```
+
+Many legacy APIs use callbacks instead of returning futures. This adapter  
+pattern creates a `CompletableFuture` and completes it from the callback,  
+enabling integration with modern async pipelines.  
+
+## Structured concurrency with CompletableFuture  
+
+Ensuring related tasks are properly scoped and managed together.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.CancellationException;
+
+void main() {
+
+    try {
+        var result = fetchUserProfile(42).join();
+        println("Profile: " + result);
+    } catch (Exception e) {
+        println("Failed: " + e.getMessage());
+    }
+}
+
+CompletableFuture<String> fetchUserProfile(int userId) {
+    var userFuture = fetchUser(userId);
+    var settingsFuture = fetchSettings(userId);
+    var avatarFuture = fetchAvatar(userId);
+
+    return userFuture
+        .thenCombine(settingsFuture, (user, settings) -> 
+            user + " | " + settings)
+        .thenCombine(avatarFuture, (partial, avatar) -> 
+            partial + " | " + avatar)
+        .exceptionally(ex -> {
+            // Cancel remaining futures on failure
+            userFuture.cancel(true);
+            settingsFuture.cancel(true);
+            avatarFuture.cancel(true);
+            throw new CancellationException("Profile fetch cancelled");
+        });
+}
+
+CompletableFuture<String> fetchUser(int id) {
+    return CompletableFuture.supplyAsync(() -> {
+        try { Thread.sleep(300); } catch (InterruptedException e) {}
+        return "User-" + id;
+    });
+}
+
+CompletableFuture<String> fetchSettings(int id) {
+    return CompletableFuture.supplyAsync(() -> {
+        try { Thread.sleep(200); } catch (InterruptedException e) {}
+        return "Settings-" + id;
+    });
+}
+
+CompletableFuture<String> fetchAvatar(int id) {
+    return CompletableFuture.supplyAsync(() -> {
+        try { Thread.sleep(400); } catch (InterruptedException e) {}
+        return "Avatar-" + id;
+    });
+}
+```
+
+While not true structured concurrency (which Java 21+ provides via  
+`StructuredTaskScope`), this pattern groups related operations and handles  
+cancellation. All sub-tasks share a common lifecycle and failure handling.  
+
+## Comparison with parallel streams  
+
+Understanding when to use `CompletableFuture` versus parallel streams.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+import java.util.stream.IntStream;
+
+void main() {
+
+    var data = IntStream.rangeClosed(1, 10).boxed().toList();
+
+    // Parallel Stream - uses ForkJoinPool, limited control
+    var startParallel = System.currentTimeMillis();
+    var parallelResult = data.parallelStream()
+        .map(n -> {
+            try { Thread.sleep(100); } catch (InterruptedException e) {}
+            return n * n;
+        })
+        .toList();
+    println("Parallel stream: " + (System.currentTimeMillis() - startParallel) + 
+        "ms, sum=" + parallelResult.stream().mapToInt(i -> i).sum());
+
+    // CompletableFuture - more control over execution
+    var startCF = System.currentTimeMillis();
+    var futures = data.stream()
+        .map(n -> CompletableFuture.supplyAsync(() -> {
+            try { Thread.sleep(100); } catch (InterruptedException e) {}
+            return n * n;
+        }))
+        .toList();
+    var cfResult = futures.stream()
+        .map(CompletableFuture::join)
+        .toList();
+    println("CompletableFuture: " + (System.currentTimeMillis() - startCF) + 
+        "ms, sum=" + cfResult.stream().mapToInt(i -> i).sum());
+}
+```
+
+| Feature | Parallel Streams | CompletableFuture |
+|---------|------------------|-------------------|
+| Control | Limited | Full control |
+| Executor | Common ForkJoinPool | Any executor |
+| Chaining | Limited | Extensive |
+| Error handling | Exceptions propagate | exceptionally, handle |
+| Use case | CPU-bound, simple | I/O-bound, complex |
+
+## Best practices summary  
+
+Following established patterns ensures robust async code.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+
+void main() {
+
+    // 1. Use custom executors for I/O tasks
+    ExecutorService ioPool = Executors.newFixedThreadPool(10);
+
+    try {
+        // 2. Always handle exceptions
+        var result = CompletableFuture.supplyAsync(() -> 
+            riskyOperation(), ioPool)
+            .exceptionally(ex -> {
+                println("Handled error: " + ex.getMessage());
+                return "fallback";
+            })
+            // 3. Use timeouts for external calls
+            .orTimeout(5, TimeUnit.SECONDS)
+            // 4. Log completion status
+            .whenComplete((r, ex) -> 
+                println("Completed: " + (ex == null ? "success" : "failure")))
+            .join();
+
+        println("Result: " + result);
+    } finally {
+        // 5. Always shutdown executors
+        ioPool.shutdown();
+    }
+}
+
+String riskyOperation() {
+    if (Math.random() > 0.7) {
+        throw new RuntimeException("Random failure");
+    }
+    return "success";
+}
+```
+
+Key best practices include: using dedicated thread pools for different  
+workload types, always handling exceptions, applying timeouts to prevent  
+indefinite waits, logging for observability, and properly shutting down  
+resources.  
+
+## Common pitfall: blocking inside async  
+
+Blocking operations inside async tasks can cause thread starvation.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.ForkJoinPool;
+
+void main() {
+
+    println("Common pool parallelism: " + 
+        ForkJoinPool.commonPool().getParallelism());
+
+    // BAD: Blocking inside supplyAsync uses up pool threads
+    var badFutures = new ArrayList<CompletableFuture<String>>();
+    for (int i = 0; i < 20; i++) {
+        int id = i;
+        badFutures.add(CompletableFuture.supplyAsync(() -> {
+            try { 
+                Thread.sleep(1000); // Blocking!
+            } catch (InterruptedException e) {}
+            return "Task-" + id;
+        }));
+    }
+
+    var start = System.currentTimeMillis();
+    CompletableFuture.allOf(badFutures.toArray(new CompletableFuture[0])).join();
+    println("With blocking: " + (System.currentTimeMillis() - start) + "ms");
+
+    // The common pool has limited threads, so tasks queue up
+    // Use virtual threads or a larger pool for blocking I/O
+}
+```
+
+The common `ForkJoinPool` has limited threads (typically CPU count - 1).  
+Blocking operations exhaust these threads, preventing other tasks from  
+running. Use virtual threads, dedicated I/O pools, or truly async APIs.  
+
+## Common pitfall: ignoring exceptions  
+
+Unhandled exceptions in async chains are silently swallowed.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+
+void main() throws Exception {
+
+    // BAD: Exception is lost
+    CompletableFuture.runAsync(() -> {
+        throw new RuntimeException("Silent failure!");
+    });
+
+    Thread.sleep(500);
+    println("No exception visible - it was swallowed!");
+
+    // GOOD: Always handle or observe exceptions
+    CompletableFuture.runAsync(() -> {
+        throw new RuntimeException("Visible failure!");
+    })
+    .exceptionally(ex -> {
+        println("Caught: " + ex.getMessage());
+        return null;
+    })
+    .join();
+
+    println("Exception was properly handled");
+}
+```
+
+Without `exceptionally`, `handle`, or calling `join`/`get`, exceptions  
+disappear silently. Always attach exception handlers or use `join` which  
+will throw `CompletionException` for failures.  
+
+## Common pitfall: deadlock with join  
+
+Calling `join` inside a `CompletableFuture` can cause deadlock.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.Executors;
+
+void main() {
+
+    // Using a single-thread executor to demonstrate
+    var executor = Executors.newSingleThreadExecutor();
+
+    try {
+        // This will deadlock with a single-thread executor!
+        // The outer task waits for inner, but inner can't start
+        // because outer holds the only thread
+
+        // var result = CompletableFuture.supplyAsync(() -> {
+        //     var inner = CompletableFuture.supplyAsync(() -> "inner", executor);
+        //     return "outer-" + inner.join(); // DEADLOCK
+        // }, executor).join();
+
+        // GOOD: Use thenCompose for dependent async operations
+        var result = CompletableFuture.supplyAsync(() -> "outer", executor)
+            .thenComposeAsync(outer -> 
+                CompletableFuture.supplyAsync(() -> outer + "-inner", executor),
+                executor)
+            .join();
+
+        println("Result: " + result);
+    } finally {
+        executor.shutdown();
+    }
+}
+```
+
+Using `join` inside async tasks creates dependency cycles. If all pool  
+threads are waiting, no thread is available to complete the inner future.  
+Use `thenCompose` for dependent async operations instead.  
+
+## Conclusion  
+
+`CompletableFuture` transforms asynchronous programming in Java from complex  
+callback-based code into clean, composable pipelines. Its fluent API enables  
+chaining transformations, combining independent operations, and handling errors  
+gracefully—all without blocking threads unnecessarily.  
+
+Key takeaways from this guide:  
+
+1. **Prefer non-blocking operations**: Use `thenApply`, `thenCompose`, and  
+   `thenCombine` over `get` and `join` where possible  
+
+2. **Handle exceptions properly**: Always attach `exceptionally` or `handle`  
+   to prevent silent failures  
+
+3. **Choose the right executor**: Use virtual threads for I/O-bound work,  
+   dedicated pools for CPU-intensive tasks  
+
+4. **Apply timeouts**: Use `orTimeout` or `completeOnTimeout` for external  
+   service calls  
+
+5. **Avoid blocking in async contexts**: Never call `join` inside a  
+   `CompletableFuture` running on a limited thread pool  
+
+As Java continues to evolve with virtual threads and structured concurrency,  
+`CompletableFuture` remains essential for building responsive, scalable  
+applications. Whether you're implementing microservices, processing data  
+pipelines, or building reactive systems, mastering `CompletableFuture` is  
+fundamental to modern Java development.  
diff --git a/concurrency.md b/concurrency.md
new file mode 100644
index 00000000..f4a63bdf
--- /dev/null
+++ b/concurrency.md
@@ -0,0 +1,1877 @@
+# Java Concurrency
+
+Concurrency in Java refers to the ability of a program to execute multiple tasks  
+simultaneously, allowing for more efficient use of system resources and improved  
+application performance. Java provides a rich set of APIs and language features  
+for building concurrent applications, from low-level thread management to  
+high-level abstractions like executors and concurrent collections.  
+
+**Concurrency** is the composition of independently executing processes, while  
+**parallelism** is the simultaneous execution of computations. In Java, threads  
+are the fundamental unit of concurrency. A thread is a lightweight subprocess,  
+the smallest unit of processing that can be scheduled by the operating system.  
+
+Java's concurrency model is built around shared memory and synchronization. When  
+multiple threads access shared data, proper synchronization is essential to  
+prevent race conditions, deadlocks, and other concurrency issues. The Java  
+Memory Model (JMM) defines how threads interact through memory and what  
+behaviors are allowed in concurrent programs.  
+
+## Key Concepts  
+
+- **Thread**: A single sequential flow of control within a program  
+- **Process**: An executing instance of a program with its own memory space  
+- **Race Condition**: When multiple threads access shared data concurrently and  
+  at least one modifies it, leading to unpredictable results  
+- **Deadlock**: When two or more threads are blocked forever, each waiting for  
+  the other to release a resource  
+- **Starvation**: When a thread is unable to gain regular access to shared  
+  resources and is unable to make progress  
+- **Livelock**: When threads are not blocked but cannot make progress because  
+  they keep responding to each other  
+- **Critical Section**: A code segment that accesses shared resources and must  
+  not be executed by more than one thread at a time  
+- **Mutual Exclusion**: Ensuring that only one thread can execute a critical  
+  section at a time  
+- **Atomicity**: An operation that completes in a single step relative to other  
+  threads  
+- **Visibility**: Ensuring that changes made by one thread are visible to other  
+  threads  
+- **Ordering**: The order in which operations appear to execute  
+
+## Thread Lifecycle  
+
+A thread in Java can be in one of the following states:  
+
+1. **NEW**: Thread has been created but not yet started  
+2. **RUNNABLE**: Thread is executing or ready to execute  
+3. **BLOCKED**: Thread is waiting to acquire a monitor lock  
+4. **WAITING**: Thread is waiting indefinitely for another thread  
+5. **TIMED_WAITING**: Thread is waiting for a specified time  
+6. **TERMINATED**: Thread has completed execution  
+
+
+## Creating a thread by extending Thread  
+
+The simplest way to create a thread is by extending the `Thread` class and  
+overriding the `run` method.  
+
+```java
+void main() {
+
+    var thread = new Thread() {
+        @Override
+        public void run() {
+            println("Hello from thread: " + Thread.currentThread().getName());
+        }
+    };
+
+    thread.start();
+    println("Main thread: " + Thread.currentThread().getName());
+}
+```
+
+This example demonstrates the basic thread creation pattern. The `run` method  
+contains the code that executes in the new thread. Calling `start` creates a  
+new thread and invokes `run` asynchronously. The main thread continues executing  
+while the new thread runs concurrently.  
+
+
+## Creating a thread with Runnable  
+
+Implementing `Runnable` is the preferred approach as it separates the task from  
+the thread mechanism and allows the class to extend another class.  
+
+```java
+void main() {
+
+    Runnable task = () -> {
+        println("Running in: " + Thread.currentThread().getName());
+    };
+
+    var thread = new Thread(task);
+    thread.start();
+
+    println("Main thread continues...");
+}
+```
+
+Using a lambda expression for `Runnable` provides clean, concise code. This  
+approach is more flexible because the task logic is decoupled from the thread  
+creation, making it easier to submit tasks to thread pools later.  
+
+
+## Thread sleep  
+
+The `sleep` method pauses the current thread for a specified duration without  
+releasing any locks it holds.  
+
+```java
+void main() throws InterruptedException {
+
+    println("Starting...");
+
+    for (int i = 1; i <= 5; i++) {
+        Thread.sleep(1000);
+        println("Tick " + i);
+    }
+
+    println("Done!");
+}
+```
+
+The `sleep` method throws `InterruptedException` if another thread interrupts  
+the sleeping thread. This is useful for creating delays, polling, or simulating  
+time-consuming operations in examples and tests.  
+
+
+## Thread join  
+
+The `join` method allows one thread to wait for the completion of another  
+thread before continuing execution.  
+
+```java
+void main() throws InterruptedException {
+
+    var worker = new Thread(() -> {
+        for (int i = 0; i < 5; i++) {
+            println("Working... " + i);
+            try {
+                Thread.sleep(500);
+            } catch (InterruptedException e) {
+                Thread.currentThread().interrupt();
+            }
+        }
+    });
+
+    worker.start();
+    println("Waiting for worker to complete...");
+
+    worker.join();
+    println("Worker completed!");
+}
+```
+
+Without `join`, the main thread would continue immediately. With `join`, the  
+main thread blocks until the worker thread finishes. This is essential when  
+you need results from a thread before proceeding.  
+
+
+## Thread interrupt  
+
+Interruption is a cooperative mechanism for signaling a thread that it should  
+stop what it's doing.  
+
+```java
+void main() throws InterruptedException {
+
+    var worker = new Thread(() -> {
+        while (!Thread.currentThread().isInterrupted()) {
+            println("Working...");
+            try {
+                Thread.sleep(1000);
+            } catch (InterruptedException e) {
+                println("Interrupted during sleep!");
+                Thread.currentThread().interrupt();
+                break;
+            }
+        }
+        println("Worker stopped.");
+    });
+
+    worker.start();
+    Thread.sleep(3500);
+    worker.interrupt();
+    worker.join();
+}
+```
+
+Threads should regularly check their interrupt status and respond appropriately.  
+When `sleep` or `wait` is interrupted, an `InterruptedException` is thrown and  
+the interrupt status is cleared, so it must be restored or handled.  
+
+
+## Multiple threads  
+
+Running multiple threads concurrently demonstrates true parallel execution on  
+multi-core systems.  
+
+```java
+void main() throws InterruptedException {
+
+    var threads = new ArrayList<Thread>();
+
+    for (int i = 1; i <= 5; i++) {
+        int threadNum = i;
+        var thread = new Thread(() -> {
+            println("Thread " + threadNum + " started");
+            try {
+                Thread.sleep((long) (Math.random() * 1000));
+            } catch (InterruptedException e) {
+                Thread.currentThread().interrupt();
+            }
+            println("Thread " + threadNum + " finished");
+        });
+        threads.add(thread);
+        thread.start();
+    }
+
+    for (var thread : threads) {
+        thread.join();
+    }
+
+    println("All threads completed");
+}
+```
+
+Each thread executes independently and may complete in any order. The random  
+sleep simulates varying workloads. Using `join` on all threads ensures the main  
+thread waits for all workers before proceeding.  
+
+
+## Daemon threads  
+
+Daemon threads are background threads that don't prevent the JVM from exiting  
+when all user threads have finished.  
+
+```java
+void main() throws InterruptedException {
+
+    var daemon = new Thread(() -> {
+        while (true) {
+            println("Daemon running...");
+            try {
+                Thread.sleep(500);
+            } catch (InterruptedException e) {
+                break;
+            }
+        }
+    });
+
+    daemon.setDaemon(true);
+    daemon.start();
+
+    Thread.sleep(2000);
+    println("Main thread exiting...");
+}
+```
+
+When the main thread exits after 2 seconds, the daemon thread is automatically  
+terminated. Daemon threads are useful for background services like garbage  
+collection or monitoring that shouldn't keep the application alive.  
+
+
+## Thread priority  
+
+Thread priority hints to the scheduler about the relative importance of threads,  
+though behavior is platform-dependent.  
+
+```java
+void main() throws InterruptedException {
+
+    Runnable task = () -> {
+        var name = Thread.currentThread().getName();
+        var priority = Thread.currentThread().getPriority();
+        println(name + " with priority " + priority + " running");
+    };
+
+    var lowPriority = new Thread(task, "LowPriority");
+    var normalPriority = new Thread(task, "NormalPriority");
+    var highPriority = new Thread(task, "HighPriority");
+
+    lowPriority.setPriority(Thread.MIN_PRIORITY);
+    normalPriority.setPriority(Thread.NORM_PRIORITY);
+    highPriority.setPriority(Thread.MAX_PRIORITY);
+
+    lowPriority.start();
+    normalPriority.start();
+    highPriority.start();
+
+    lowPriority.join();
+    normalPriority.join();
+    highPriority.join();
+}
+```
+
+Priority values range from 1 (MIN_PRIORITY) to 10 (MAX_PRIORITY), with 5  
+(NORM_PRIORITY) as default. Higher priority threads may get more CPU time, but  
+this is not guaranteed and depends on the OS scheduler.  
+
+
+## Race condition demonstration  
+
+A race condition occurs when multiple threads access shared data without proper  
+synchronization.  
+
+```java
+void main() throws InterruptedException {
+
+    var counter = new int[]{0};
+    var threads = new ArrayList<Thread>();
+
+    for (int i = 0; i < 10; i++) {
+        var thread = new Thread(() -> {
+            for (int j = 0; j < 1000; j++) {
+                counter[0]++;
+            }
+        });
+        threads.add(thread);
+        thread.start();
+    }
+
+    for (var thread : threads) {
+        thread.join();
+    }
+
+    println("Expected: 10000, Actual: " + counter[0]);
+}
+```
+
+The increment operation `counter[0]++` is not atomic; it involves read, modify,  
+and write steps. Without synchronization, threads may overwrite each other's  
+updates, resulting in a count less than expected.  
+
+
+## Synchronized method  
+
+The `synchronized` keyword ensures that only one thread can execute a method  
+on an object at a time.  
+
+```java
+class Counter {
+    private int count = 0;
+
+    synchronized void increment() {
+        count++;
+    }
+
+    synchronized int getCount() {
+        return count;
+    }
+}
+
+void main() throws InterruptedException {
+
+    var counter = new Counter();
+    var threads = new ArrayList<Thread>();
+
+    for (int i = 0; i < 10; i++) {
+        var thread = new Thread(() -> {
+            for (int j = 0; j < 1000; j++) {
+                counter.increment();
+            }
+        });
+        threads.add(thread);
+        thread.start();
+    }
+
+    for (var thread : threads) {
+        thread.join();
+    }
+
+    println("Count: " + counter.getCount());
+}
+```
+
+The `synchronized` keyword acquires the object's intrinsic lock before entering  
+the method. This ensures mutual exclusion—only one thread can execute any  
+synchronized method on the same object at a time.  
+
+
+## Synchronized block  
+
+Synchronized blocks allow finer-grained locking by synchronizing only the  
+critical section rather than the entire method.  
+
+```java
+class BankAccount {
+    private int balance = 1000;
+    private final Object lock = new Object();
+
+    void withdraw(int amount) {
+        synchronized (lock) {
+            if (balance >= amount) {
+                balance -= amount;
+                println(Thread.currentThread().getName() + 
+                    " withdrew " + amount + ", balance: " + balance);
+            }
+        }
+    }
+
+    int getBalance() {
+        synchronized (lock) {
+            return balance;
+        }
+    }
+}
+
+void main() throws InterruptedException {
+
+    var account = new BankAccount();
+    var threads = new ArrayList<Thread>();
+
+    for (int i = 0; i < 5; i++) {
+        var thread = new Thread(() -> {
+            account.withdraw(100);
+        });
+        threads.add(thread);
+        thread.start();
+    }
+
+    for (var thread : threads) {
+        thread.join();
+    }
+
+    println("Final balance: " + account.getBalance());
+}
+```
+
+Using a private lock object is preferred over `synchronized(this)` because it  
+prevents external code from acquiring the same lock. This provides better  
+encapsulation and reduces the risk of unintended lock contention.  
+
+
+## Volatile keyword  
+
+The `volatile` keyword ensures visibility of changes across threads but does not  
+provide atomicity.  
+
+```java
+class Flag {
+    volatile boolean running = true;
+}
+
+void main() throws InterruptedException {
+
+    var flag = new Flag();
+
+    var worker = new Thread(() -> {
+        long count = 0;
+        while (flag.running) {
+            count++;
+        }
+        println("Counted to: " + count);
+    });
+
+    worker.start();
+    Thread.sleep(100);
+    flag.running = false;
+    worker.join();
+    println("Worker stopped");
+}
+```
+
+Without `volatile`, the worker thread might cache the `running` variable and  
+never see the update. The `volatile` keyword forces reads and writes to go  
+directly to main memory, ensuring visibility across threads.  
+
+
+## AtomicInteger  
+
+`AtomicInteger` provides thread-safe operations on integers without explicit  
+synchronization.  
+
+```java
+import java.util.concurrent.atomic.AtomicInteger;
+
+void main() throws InterruptedException {
+
+    var counter = new AtomicInteger(0);
+    var threads = new ArrayList<Thread>();
+
+    for (int i = 0; i < 10; i++) {
+        var thread = new Thread(() -> {
+            for (int j = 0; j < 1000; j++) {
+                counter.incrementAndGet();
+            }
+        });
+        threads.add(thread);
+        thread.start();
+    }
+
+    for (var thread : threads) {
+        thread.join();
+    }
+
+    println("Count: " + counter.get());
+}
+```
+
+`AtomicInteger` uses compare-and-swap (CAS) operations implemented at the  
+hardware level. This is more efficient than synchronization for simple atomic  
+operations and is lock-free, avoiding potential deadlocks.  
+
+
+## AtomicLong and AtomicBoolean  
+
+Other atomic classes provide thread-safe operations for different primitive  
+types.  
+
+```java
+import java.util.concurrent.atomic.AtomicLong;
+import java.util.concurrent.atomic.AtomicBoolean;
+
+void main() throws InterruptedException {
+
+    var sum = new AtomicLong(0);
+    var isComplete = new AtomicBoolean(false);
+
+    var threads = new ArrayList<Thread>();
+
+    for (int i = 1; i <= 5; i++) {
+        int value = i * 100;
+        var thread = new Thread(() -> {
+            sum.addAndGet(value);
+        });
+        threads.add(thread);
+        thread.start();
+    }
+
+    for (var thread : threads) {
+        thread.join();
+    }
+
+    isComplete.set(true);
+    println("Sum: " + sum.get());
+    println("Complete: " + isComplete.get());
+}
+```
+
+`AtomicLong` is useful for counters and accumulators in concurrent code.  
+`AtomicBoolean` is commonly used as a thread-safe flag for signaling between  
+threads, such as for graceful shutdown.  
+
+
+## AtomicReference  
+
+`AtomicReference` provides atomic operations on object references, enabling  
+lock-free algorithms.  
+
+```java
+import java.util.concurrent.atomic.AtomicReference;
+
+record User(String name, int age) {}
+
+void main() throws InterruptedException {
+
+    var userRef = new AtomicReference<>(new User("Alice", 25));
+
+    var updater = new Thread(() -> {
+        var current = userRef.get();
+        var updated = new User(current.name(), current.age() + 1);
+        userRef.compareAndSet(current, updated);
+    });
+
+    updater.start();
+    updater.join();
+
+    println("Updated user: " + userRef.get());
+}
+```
+
+`compareAndSet` atomically updates the reference only if it equals the expected  
+value. This is the foundation of many lock-free data structures and algorithms,  
+enabling safe concurrent updates without locks.  
+
+
+## ReentrantLock  
+
+`ReentrantLock` provides more flexibility than synchronized blocks, including  
+tryLock, timed lock, and interruptible lock acquisition.  
+
+```java
+import java.util.concurrent.locks.ReentrantLock;
+
+void main() throws InterruptedException {
+
+    var lock = new ReentrantLock();
+    var counter = new int[]{0};
+
+    Runnable task = () -> {
+        for (int i = 0; i < 1000; i++) {
+            lock.lock();
+            try {
+                counter[0]++;
+            } finally {
+                lock.unlock();
+            }
+        }
+    };
+
+    var threads = new ArrayList<Thread>();
+    for (int i = 0; i < 10; i++) {
+        var thread = new Thread(task);
+        threads.add(thread);
+        thread.start();
+    }
+
+    for (var thread : threads) {
+        thread.join();
+    }
+
+    println("Count: " + counter[0]);
+}
+```
+
+Unlike `synchronized`, `ReentrantLock` must be explicitly unlocked in a finally  
+block to ensure release even if an exception occurs. The lock is reentrant,  
+meaning the same thread can acquire it multiple times.  
+
+
+## TryLock  
+
+The `tryLock` method attempts to acquire a lock without blocking, useful for  
+avoiding deadlocks.  
+
+```java
+import java.util.concurrent.locks.ReentrantLock;
+
+void main() throws InterruptedException {
+
+    var lock = new ReentrantLock();
+
+    Runnable task = () -> {
+        if (lock.tryLock()) {
+            try {
+                println(Thread.currentThread().getName() + " acquired lock");
+                Thread.sleep(1000);
+            } catch (InterruptedException e) {
+                Thread.currentThread().interrupt();
+            } finally {
+                lock.unlock();
+            }
+        } else {
+            println(Thread.currentThread().getName() + " could not acquire lock");
+        }
+    };
+
+    var t1 = new Thread(task, "Thread-1");
+    var t2 = new Thread(task, "Thread-2");
+
+    t1.start();
+    Thread.sleep(100);
+    t2.start();
+
+    t1.join();
+    t2.join();
+}
+```
+
+`tryLock` returns immediately with `true` if the lock was acquired, or `false`  
+if not. This enables non-blocking algorithms and timeout-based lock acquisition  
+to prevent threads from waiting indefinitely.  
+
+
+## ReadWriteLock  
+
+`ReadWriteLock` allows multiple readers or a single writer, optimizing for  
+read-heavy workloads.  
+
+```java
+import java.util.concurrent.locks.ReadWriteLock;
+import java.util.concurrent.locks.ReentrantReadWriteLock;
+
+class Cache {
+    private final Map<String, String> data = new HashMap<>();
+    private final ReadWriteLock lock = new ReentrantReadWriteLock();
+
+    String get(String key) {
+        lock.readLock().lock();
+        try {
+            return data.get(key);
+        } finally {
+            lock.readLock().unlock();
+        }
+    }
+
+    void put(String key, String value) {
+        lock.writeLock().lock();
+        try {
+            data.put(key, value);
+        } finally {
+            lock.writeLock().unlock();
+        }
+    }
+}
+
+void main() throws InterruptedException {
+
+    var cache = new Cache();
+    cache.put("key1", "value1");
+
+    var threads = new ArrayList<Thread>();
+
+    for (int i = 0; i < 5; i++) {
+        int num = i;
+        var reader = new Thread(() -> {
+            println("Reader " + num + ": " + cache.get("key1"));
+        });
+        threads.add(reader);
+        reader.start();
+    }
+
+    for (var thread : threads) {
+        thread.join();
+    }
+}
+```
+
+Multiple threads can hold the read lock simultaneously as long as no thread  
+holds the write lock. This significantly improves throughput for data structures  
+that are read more often than written.  
+
+
+## Condition variables  
+
+`Condition` provides a means for one thread to suspend execution until notified  
+by another thread.  
+
+```java
+import java.util.concurrent.locks.Condition;
+import java.util.concurrent.locks.ReentrantLock;
+
+void main() throws InterruptedException {
+
+    var lock = new ReentrantLock();
+    var condition = lock.newCondition();
+    var ready = new boolean[]{false};
+
+    var waiter = new Thread(() -> {
+        lock.lock();
+        try {
+            while (!ready[0]) {
+                println("Waiting...");
+                condition.await();
+            }
+            println("Received signal!");
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+        } finally {
+            lock.unlock();
+        }
+    });
+
+    var signaler = new Thread(() -> {
+        lock.lock();
+        try {
+            Thread.sleep(1000);
+            ready[0] = true;
+            condition.signal();
+            println("Signal sent!");
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+        } finally {
+            lock.unlock();
+        }
+    });
+
+    waiter.start();
+    Thread.sleep(100);
+    signaler.start();
+
+    waiter.join();
+    signaler.join();
+}
+```
+
+`Condition` is associated with a lock and must be used while holding that lock.  
+Unlike `Object.wait/notify`, multiple conditions can be associated with a single  
+lock, providing finer-grained control.  
+
+
+## ExecutorService with fixed thread pool  
+
+`ExecutorService` manages a pool of threads, abstracting thread lifecycle  
+management.  
+
+```java
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+
+void main() throws InterruptedException {
+
+    ExecutorService executor = Executors.newFixedThreadPool(3);
+
+    for (int i = 1; i <= 6; i++) {
+        int taskId = i;
+        executor.submit(() -> {
+            println("Task " + taskId + " running on " + 
+                Thread.currentThread().getName());
+            try {
+                Thread.sleep(1000);
+            } catch (InterruptedException e) {
+                Thread.currentThread().interrupt();
+            }
+        });
+    }
+
+    executor.shutdown();
+    executor.awaitTermination(10, TimeUnit.SECONDS);
+    println("All tasks completed");
+}
+```
+
+A fixed thread pool reuses a fixed number of threads, queuing tasks when all  
+threads are busy. This prevents resource exhaustion from creating too many  
+threads and improves performance through thread reuse.  
+
+
+## Cached thread pool  
+
+A cached thread pool creates new threads as needed and reuses idle threads.  
+
+```java
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+
+void main() throws InterruptedException {
+
+    ExecutorService executor = Executors.newCachedThreadPool();
+
+    for (int i = 1; i <= 10; i++) {
+        int taskId = i;
+        executor.submit(() -> {
+            println("Task " + taskId + " on " + 
+                Thread.currentThread().getName());
+            try {
+                Thread.sleep(500);
+            } catch (InterruptedException e) {
+                Thread.currentThread().interrupt();
+            }
+        });
+    }
+
+    executor.shutdown();
+    executor.awaitTermination(10, TimeUnit.SECONDS);
+}
+```
+
+Cached thread pools are suitable for executing many short-lived tasks. Idle  
+threads are terminated after 60 seconds. However, for unbounded task submission,  
+this can create too many threads and exhaust system resources.  
+
+
+## Single thread executor  
+
+A single thread executor ensures tasks execute sequentially in submission order.  
+
+```java
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+
+void main() throws InterruptedException {
+
+    ExecutorService executor = Executors.newSingleThreadExecutor();
+
+    for (int i = 1; i <= 5; i++) {
+        int taskId = i;
+        executor.submit(() -> {
+            println("Processing task " + taskId);
+            try {
+                Thread.sleep(500);
+            } catch (InterruptedException e) {
+                Thread.currentThread().interrupt();
+            }
+        });
+    }
+
+    executor.shutdown();
+    executor.awaitTermination(10, TimeUnit.SECONDS);
+    println("All tasks processed in order");
+}
+```
+
+Single thread executors guarantee sequential execution and are useful when tasks  
+must not run concurrently, such as writing to a log file or processing messages  
+in order.  
+
+
+## ScheduledExecutorService  
+
+`ScheduledExecutorService` executes tasks after a delay or periodically.  
+
+```java
+import java.util.concurrent.Executors;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.TimeUnit;
+
+void main() throws InterruptedException {
+
+    ScheduledExecutorService scheduler = Executors.newScheduledThreadPool(2);
+
+    scheduler.schedule(() -> {
+        println("Delayed task executed after 2 seconds");
+    }, 2, TimeUnit.SECONDS);
+
+    scheduler.scheduleAtFixedRate(() -> {
+        println("Fixed rate task: " + System.currentTimeMillis());
+    }, 0, 1, TimeUnit.SECONDS);
+
+    Thread.sleep(5000);
+    scheduler.shutdown();
+}
+```
+
+`scheduleAtFixedRate` runs tasks at fixed intervals regardless of task duration.  
+`scheduleWithFixedDelay` waits a fixed delay after each task completes before  
+starting the next. Both are useful for periodic maintenance tasks.  
+
+
+## Callable and Future  
+
+`Callable` returns a result and can throw exceptions, unlike `Runnable`.  
+`Future` represents the pending result.  
+
+```java
+import java.util.concurrent.Callable;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+
+void main() throws Exception {
+
+    ExecutorService executor = Executors.newSingleThreadExecutor();
+
+    Callable<Integer> task = () -> {
+        Thread.sleep(1000);
+        return 42;
+    };
+
+    Future<Integer> future = executor.submit(task);
+    println("Task submitted, doing other work...");
+
+    Integer result = future.get();
+    println("Result: " + result);
+
+    executor.shutdown();
+}
+```
+
+`Future.get` blocks until the result is available. It throws  
+`ExecutionException` if the task threw an exception, or `CancellationException`  
+if the task was cancelled. This enables asynchronous computation with results.  
+
+
+## Future with timeout  
+
+The `get` method can specify a timeout to avoid blocking indefinitely.  
+
+```java
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
+
+void main() throws Exception {
+
+    ExecutorService executor = Executors.newSingleThreadExecutor();
+
+    Future<String> future = executor.submit(() -> {
+        Thread.sleep(5000);
+        return "Result";
+    });
+
+    try {
+        String result = future.get(2, TimeUnit.SECONDS);
+        println("Result: " + result);
+    } catch (TimeoutException e) {
+        println("Task timed out!");
+        future.cancel(true);
+    }
+
+    executor.shutdown();
+}
+```
+
+When a timeout occurs, the task continues running unless explicitly cancelled.  
+Calling `cancel(true)` interrupts the running task. This pattern is essential  
+for preventing operations from hanging indefinitely.  
+
+
+## InvokeAll  
+
+`invokeAll` submits multiple callables and returns when all complete.  
+
+```java
+import java.util.concurrent.Callable;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+
+void main() throws Exception {
+
+    ExecutorService executor = Executors.newFixedThreadPool(3);
+
+    var tasks = List.<Callable<Integer>>of(
+        () -> { Thread.sleep(1000); return 1; },
+        () -> { Thread.sleep(2000); return 2; },
+        () -> { Thread.sleep(1500); return 3; }
+    );
+
+    var futures = executor.invokeAll(tasks);
+
+    int sum = 0;
+    for (var future : futures) {
+        sum += future.get();
+    }
+
+    println("Sum of all results: " + sum);
+    executor.shutdown();
+}
+```
+
+`invokeAll` blocks until all tasks complete or the timeout expires. It's useful  
+when you need to wait for multiple independent computations and aggregate their  
+results, such as fetching data from multiple sources.  
+
+
+## InvokeAny  
+
+`invokeAny` returns the result of the fastest completing task, cancelling the  
+others.  
+
+```java
+import java.util.concurrent.Callable;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+
+void main() throws Exception {
+
+    ExecutorService executor = Executors.newFixedThreadPool(3);
+
+    var tasks = List.<Callable<String>>of(
+        () -> { Thread.sleep(3000); return "Server A"; },
+        () -> { Thread.sleep(1000); return "Server B"; },
+        () -> { Thread.sleep(2000); return "Server C"; }
+    );
+
+    String fastest = executor.invokeAny(tasks);
+    println("Fastest response from: " + fastest);
+
+    executor.shutdown();
+}
+```
+
+This is useful for redundant operations where you need any successful result  
+quickly, such as querying multiple servers. Once one task completes, the others  
+are cancelled to conserve resources.  
+
+
+## CompletableFuture basics  
+
+`CompletableFuture` provides a powerful API for asynchronous programming with  
+chaining and combining.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+
+void main() throws Exception {
+
+    var future = CompletableFuture.supplyAsync(() -> {
+        println("Computing in: " + Thread.currentThread().getName());
+        return 42;
+    });
+
+    future.thenAccept(result -> {
+        println("Result: " + result);
+    });
+
+    Thread.sleep(1000);
+}
+```
+
+`supplyAsync` runs the supplier in the common fork-join pool. `thenAccept`  
+registers a callback that executes when the future completes. This enables  
+non-blocking asynchronous programming without explicit thread management.  
+
+
+## CompletableFuture chaining  
+
+Multiple stages can be chained together for complex asynchronous workflows.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+
+void main() throws Exception {
+
+    CompletableFuture.supplyAsync(() -> "Hello")
+        .thenApply(s -> s + " World")
+        .thenApply(String::toUpperCase)
+        .thenAccept(result -> println(result))
+        .join();
+}
+```
+
+Each `thenApply` transforms the result from the previous stage. The chain  
+executes asynchronously, with each stage starting when the previous completes.  
+`join` blocks until the entire chain finishes.  
+
+
+## CompletableFuture combining  
+
+Multiple futures can be combined to create complex async workflows.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+
+void main() throws Exception {
+
+    var future1 = CompletableFuture.supplyAsync(() -> {
+        try { Thread.sleep(1000); } catch (InterruptedException e) {}
+        return "Hello";
+    });
+
+    var future2 = CompletableFuture.supplyAsync(() -> {
+        try { Thread.sleep(500); } catch (InterruptedException e) {}
+        return "World";
+    });
+
+    future1.thenCombine(future2, (s1, s2) -> s1 + " " + s2)
+        .thenAccept(result -> println(result))
+        .join();
+}
+```
+
+`thenCombine` waits for both futures and combines their results. This is useful  
+when you need to merge results from independent async operations, like fetching  
+user data and preferences simultaneously.  
+
+
+## CompletableFuture exception handling  
+
+Exceptions in async chains can be handled with `exceptionally` or `handle`.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+
+void main() throws Exception {
+
+    CompletableFuture.supplyAsync(() -> {
+        if (true) throw new RuntimeException("Something went wrong!");
+        return "Result";
+    })
+    .exceptionally(ex -> {
+        println("Exception: " + ex.getMessage());
+        return "Default Value";
+    })
+    .thenAccept(result -> println("Result: " + result))
+    .join();
+}
+```
+
+`exceptionally` catches exceptions from any previous stage and provides a  
+fallback value. This enables graceful error handling in async chains without  
+breaking the flow or requiring try-catch blocks.  
+
+
+## CompletableFuture allOf  
+
+`allOf` waits for multiple futures to complete.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+
+void main() throws Exception {
+
+    var future1 = CompletableFuture.runAsync(() -> {
+        try { Thread.sleep(1000); } catch (InterruptedException e) {}
+        println("Task 1 done");
+    });
+
+    var future2 = CompletableFuture.runAsync(() -> {
+        try { Thread.sleep(500); } catch (InterruptedException e) {}
+        println("Task 2 done");
+    });
+
+    var future3 = CompletableFuture.runAsync(() -> {
+        try { Thread.sleep(750); } catch (InterruptedException e) {}
+        println("Task 3 done");
+    });
+
+    CompletableFuture.allOf(future1, future2, future3).join();
+    println("All tasks completed");
+}
+```
+
+Unlike `invokeAll`, `allOf` returns a `CompletableFuture<Void>`. To get results,  
+you must call `get` on individual futures after `allOf` completes. This is  
+useful for waiting on multiple async operations.  
+
+
+## ConcurrentHashMap  
+
+`ConcurrentHashMap` provides thread-safe operations without locking the entire  
+map.  
+
+```java
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+
+void main() throws InterruptedException {
+
+    var map = new ConcurrentHashMap<String, Integer>();
+
+    ExecutorService executor = Executors.newFixedThreadPool(4);
+
+    for (int i = 0; i < 1000; i++) {
+        int num = i;
+        executor.submit(() -> {
+            map.put("key" + (num % 10), num);
+            map.compute("counter", (k, v) -> v == null ? 1 : v + 1);
+        });
+    }
+
+    executor.shutdown();
+    executor.awaitTermination(10, TimeUnit.SECONDS);
+
+    println("Map size: " + map.size());
+    println("Counter: " + map.get("counter"));
+}
+```
+
+`ConcurrentHashMap` uses fine-grained locking (or lock-free operations in modern  
+versions) to allow concurrent reads and writes. Atomic operations like `compute`  
+ensure thread-safe updates without external synchronization.  
+
+
+## CopyOnWriteArrayList  
+
+`CopyOnWriteArrayList` creates a new copy on each modification, ideal for  
+read-heavy scenarios.  
+
+```java
+import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+
+void main() throws InterruptedException {
+
+    var list = new CopyOnWriteArrayList<String>();
+    list.add("initial");
+
+    ExecutorService executor = Executors.newFixedThreadPool(4);
+
+    for (int i = 0; i < 10; i++) {
+        int num = i;
+        executor.submit(() -> {
+            list.add("item" + num);
+        });
+    }
+
+    executor.submit(() -> {
+        for (String item : list) {
+            println("Reading: " + item);
+        }
+    });
+
+    executor.shutdown();
+    executor.awaitTermination(10, TimeUnit.SECONDS);
+
+    println("Final size: " + list.size());
+}
+```
+
+Iteration never throws `ConcurrentModificationException` because iterators  
+work on a snapshot. This is efficient when reads greatly outnumber writes, as  
+writes incur the cost of copying the entire array.  
+
+
+## BlockingQueue  
+
+`BlockingQueue` provides thread-safe queue operations with blocking methods for  
+producer-consumer patterns.  
+
+```java
+import java.util.concurrent.ArrayBlockingQueue;
+import java.util.concurrent.BlockingQueue;
+
+void main() throws InterruptedException {
+
+    BlockingQueue<String> queue = new ArrayBlockingQueue<>(5);
+
+    var producer = new Thread(() -> {
+        try {
+            for (int i = 1; i <= 10; i++) {
+                String item = "Item-" + i;
+                queue.put(item);
+                println("Produced: " + item);
+            }
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+        }
+    });
+
+    var consumer = new Thread(() -> {
+        try {
+            for (int i = 0; i < 10; i++) {
+                String item = queue.take();
+                println("Consumed: " + item);
+                Thread.sleep(500);
+            }
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+        }
+    });
+
+    producer.start();
+    consumer.start();
+
+    producer.join();
+    consumer.join();
+}
+```
+
+`put` blocks when the queue is full, and `take` blocks when empty. This  
+automatically coordinates producer and consumer threads without explicit  
+synchronization, implementing backpressure naturally.  
+
+
+## CountDownLatch  
+
+`CountDownLatch` allows threads to wait until a count reaches zero.  
+
+```java
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+
+void main() throws InterruptedException {
+
+    var latch = new CountDownLatch(3);
+    ExecutorService executor = Executors.newFixedThreadPool(3);
+
+    for (int i = 1; i <= 3; i++) {
+        int taskId = i;
+        executor.submit(() -> {
+            try {
+                Thread.sleep((long) (Math.random() * 2000));
+                println("Task " + taskId + " completed");
+            } catch (InterruptedException e) {
+                Thread.currentThread().interrupt();
+            } finally {
+                latch.countDown();
+            }
+        });
+    }
+
+    println("Waiting for tasks...");
+    latch.await();
+    println("All tasks completed!");
+
+    executor.shutdown();
+}
+```
+
+`countDown` decrements the count, and `await` blocks until it reaches zero.  
+Unlike `join`, multiple threads can wait on the same latch, and it can count  
+multiple completions from the same thread.  
+
+
+## CyclicBarrier  
+
+`CyclicBarrier` synchronizes a fixed number of threads at a common barrier  
+point.  
+
+```java
+import java.util.concurrent.CyclicBarrier;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+
+void main() throws InterruptedException {
+
+    var barrier = new CyclicBarrier(3, () -> {
+        println("All parties arrived at barrier!");
+    });
+
+    ExecutorService executor = Executors.newFixedThreadPool(3);
+
+    for (int i = 1; i <= 3; i++) {
+        int partyId = i;
+        executor.submit(() -> {
+            try {
+                println("Party " + partyId + " working...");
+                Thread.sleep((long) (Math.random() * 2000));
+                println("Party " + partyId + " waiting at barrier");
+                barrier.await();
+                println("Party " + partyId + " passed barrier");
+            } catch (Exception e) {
+                Thread.currentThread().interrupt();
+            }
+        });
+    }
+
+    Thread.sleep(5000);
+    executor.shutdown();
+}
+```
+
+Unlike `CountDownLatch`, a barrier can be reused after all threads pass. The  
+barrier action runs when all parties arrive. This is useful for iterative  
+algorithms where threads must synchronize at each step.  
+
+
+## Semaphore  
+
+`Semaphore` controls access to a limited number of resources through permits.  
+
+```java
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Semaphore;
+import java.util.concurrent.TimeUnit;
+
+void main() throws InterruptedException {
+
+    var semaphore = new Semaphore(3);
+    ExecutorService executor = Executors.newFixedThreadPool(10);
+
+    for (int i = 1; i <= 10; i++) {
+        int taskId = i;
+        executor.submit(() -> {
+            try {
+                semaphore.acquire();
+                println("Task " + taskId + " acquired permit");
+                Thread.sleep(1000);
+            } catch (InterruptedException e) {
+                Thread.currentThread().interrupt();
+            } finally {
+                println("Task " + taskId + " releasing permit");
+                semaphore.release();
+            }
+        });
+    }
+
+    executor.shutdown();
+    executor.awaitTermination(30, TimeUnit.SECONDS);
+}
+```
+
+Semaphores limit concurrent access to a resource pool, such as database  
+connections or API rate limits. Only three tasks run simultaneously, with others  
+waiting until a permit is released.  
+
+
+## Phaser  
+
+`Phaser` is a flexible synchronization barrier supporting dynamic party  
+registration.  
+
+```java
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Phaser;
+import java.util.concurrent.TimeUnit;
+
+void main() throws InterruptedException {
+
+    var phaser = new Phaser(1);
+    ExecutorService executor = Executors.newFixedThreadPool(3);
+
+    for (int i = 1; i <= 3; i++) {
+        phaser.register();
+        int partyId = i;
+        executor.submit(() -> {
+            for (int phase = 0; phase < 3; phase++) {
+                println("Party " + partyId + " phase " + phase);
+                phaser.arriveAndAwaitAdvance();
+            }
+            phaser.arriveAndDeregister();
+        });
+    }
+
+    phaser.arriveAndDeregister();
+    executor.shutdown();
+    executor.awaitTermination(10, TimeUnit.SECONDS);
+}
+```
+
+Unlike `CyclicBarrier`, parties can dynamically register and deregister.  
+`Phaser` supports multiple phases and can be used for complex multi-phase  
+computations where the number of participants may vary.  
+
+
+## Exchanger  
+
+`Exchanger` allows two threads to exchange data at a synchronization point.  
+
+```java
+import java.util.concurrent.Exchanger;
+
+void main() throws InterruptedException {
+
+    var exchanger = new Exchanger<String>();
+
+    var thread1 = new Thread(() -> {
+        try {
+            String data = "Data from Thread 1";
+            println("Thread 1 sending: " + data);
+            String received = exchanger.exchange(data);
+            println("Thread 1 received: " + received);
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+        }
+    });
+
+    var thread2 = new Thread(() -> {
+        try {
+            Thread.sleep(1000);
+            String data = "Data from Thread 2";
+            println("Thread 2 sending: " + data);
+            String received = exchanger.exchange(data);
+            println("Thread 2 received: " + received);
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+        }
+    });
+
+    thread1.start();
+    thread2.start();
+
+    thread1.join();
+    thread2.join();
+}
+```
+
+Both threads block at `exchange` until the partner arrives. This is useful for  
+genetic algorithms, pipeline designs, or any scenario where two threads need  
+to swap data synchronously.  
+
+
+## ForkJoinPool  
+
+`ForkJoinPool` is optimized for divide-and-conquer algorithms using work  
+stealing.  
+
+```java
+import java.util.concurrent.ForkJoinPool;
+import java.util.concurrent.RecursiveTask;
+
+class SumTask extends RecursiveTask<Long> {
+    private final long[] array;
+    private final int start, end;
+    private static final int THRESHOLD = 1000;
+
+    SumTask(long[] array, int start, int end) {
+        this.array = array;
+        this.start = start;
+        this.end = end;
+    }
+
+    @Override
+    protected Long compute() {
+        if (end - start <= THRESHOLD) {
+            long sum = 0;
+            for (int i = start; i < end; i++) {
+                sum += array[i];
+            }
+            return sum;
+        }
+        int mid = (start + end) / 2;
+        var left = new SumTask(array, start, mid);
+        var right = new SumTask(array, mid, end);
+        left.fork();
+        return right.compute() + left.join();
+    }
+}
+
+void main() {
+
+    var array = new long[10000];
+    for (int i = 0; i < array.length; i++) {
+        array[i] = i + 1;
+    }
+
+    var pool = ForkJoinPool.commonPool();
+    long sum = pool.invoke(new SumTask(array, 0, array.length));
+
+    println("Sum: " + sum);
+}
+```
+
+`RecursiveTask` splits work into smaller chunks until reaching a threshold.  
+Work stealing allows idle threads to take tasks from busy threads' queues,  
+maximizing CPU utilization for parallel algorithms.  
+
+
+## Virtual threads basics  
+
+Virtual threads (Project Loom) are lightweight threads managed by the JVM rather  
+than the OS.  
+
+```java
+void main() throws InterruptedException {
+
+    var threads = new ArrayList<Thread>();
+
+    for (int i = 1; i <= 10; i++) {
+        int taskId = i;
+        var thread = Thread.startVirtualThread(() -> {
+            println("Virtual thread " + taskId + " running");
+            try {
+                Thread.sleep(1000);
+            } catch (InterruptedException e) {
+                Thread.currentThread().interrupt();
+            }
+            println("Virtual thread " + taskId + " done");
+        });
+        threads.add(thread);
+    }
+
+    for (var thread : threads) {
+        thread.join();
+    }
+}
+```
+
+Virtual threads are cheap to create—millions can exist simultaneously. They  
+automatically unmount from carrier threads during blocking operations, enabling  
+high-throughput concurrent applications without the complexity of async code.  
+
+
+## Virtual thread executor  
+
+`Executors.newVirtualThreadPerTaskExecutor` creates a new virtual thread for  
+each task.  
+
+```java
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+
+void main() throws InterruptedException {
+
+    try (ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor()) {
+        for (int i = 1; i <= 100; i++) {
+            int taskId = i;
+            executor.submit(() -> {
+                println("Task " + taskId + " on " + Thread.currentThread());
+                try {
+                    Thread.sleep(100);
+                } catch (InterruptedException e) {
+                    Thread.currentThread().interrupt();
+                }
+            });
+        }
+    }
+
+    println("All tasks completed");
+}
+```
+
+This executor creates virtual threads on demand, suitable for I/O-bound  
+workloads with many concurrent tasks. The try-with-resources ensures proper  
+shutdown. Virtual threads make thread-per-request architectures practical.  
+
+
+## Structured concurrency  
+
+Structured concurrency ensures child tasks complete before the parent scope  
+exits.  
+
+```java
+import java.util.concurrent.StructuredTaskScope;
+
+void main() throws Exception {
+
+    try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
+        var user = scope.fork(() -> fetchUser());
+        var order = scope.fork(() -> fetchOrder());
+
+        scope.join();
+        scope.throwIfFailed();
+
+        println("User: " + user.get());
+        println("Order: " + order.get());
+    }
+}
+
+String fetchUser() throws InterruptedException {
+    Thread.sleep(500);
+    return "Alice";
+}
+
+String fetchOrder() throws InterruptedException {
+    Thread.sleep(300);
+    return "Order #12345";
+}
+```
+
+`StructuredTaskScope` binds the lifetime of forked tasks to the scope.  
+`ShutdownOnFailure` cancels remaining tasks if one fails. This simplifies  
+error handling and prevents orphaned threads.  
+
+
+## Thread-local storage  
+
+`ThreadLocal` provides thread-confined variables, each thread having its own  
+independent copy.  
+
+```java
+void main() throws InterruptedException {
+
+    ThreadLocal<String> userContext = ThreadLocal.withInitial(() -> "unknown");
+
+    var threads = new ArrayList<Thread>();
+
+    for (int i = 1; i <= 3; i++) {
+        String userId = "user-" + i;
+        var thread = new Thread(() -> {
+            userContext.set(userId);
+            println(Thread.currentThread().getName() + 
+                " context: " + userContext.get());
+            processRequest();
+            println(Thread.currentThread().getName() + 
+                " still: " + userContext.get());
+            userContext.remove();
+        });
+        threads.add(thread);
+        thread.start();
+    }
+
+    for (var thread : threads) {
+        thread.join();
+    }
+}
+
+void processRequest() {
+    try {
+        Thread.sleep(100);
+    } catch (InterruptedException e) {
+        Thread.currentThread().interrupt();
+    }
+}
+```
+
+Each thread sees its own value without interference. `ThreadLocal` is useful  
+for per-request context in web applications. Always call `remove` to prevent  
+memory leaks in thread pools.  
+
+
+## Deadlock demonstration  
+
+Deadlock occurs when threads wait on each other in a circular dependency.  
+
+```java
+void main() throws InterruptedException {
+
+    var lock1 = new Object();
+    var lock2 = new Object();
+
+    var thread1 = new Thread(() -> {
+        synchronized (lock1) {
+            println("Thread 1: Holding lock 1");
+            try { Thread.sleep(100); } catch (InterruptedException e) {}
+            println("Thread 1: Waiting for lock 2");
+            synchronized (lock2) {
+                println("Thread 1: Holding both locks");
+            }
+        }
+    });
+
+    var thread2 = new Thread(() -> {
+        synchronized (lock2) {
+            println("Thread 2: Holding lock 2");
+            try { Thread.sleep(100); } catch (InterruptedException e) {}
+            println("Thread 2: Waiting for lock 1");
+            synchronized (lock1) {
+                println("Thread 2: Holding both locks");
+            }
+        }
+    });
+
+    thread1.start();
+    thread2.start();
+
+    thread1.join(2000);
+    thread2.join(2000);
+
+    if (thread1.isAlive() || thread2.isAlive()) {
+        println("Deadlock detected!");
+    }
+}
+```
+
+Thread 1 holds lock1 and waits for lock2, while Thread 2 holds lock2 and waits  
+for lock1. Prevent deadlocks by acquiring locks in a consistent order, using  
+timeouts, or avoiding nested locks.  
+
+
+## Parallel streams  
+
+Parallel streams use the fork-join pool to process elements concurrently.  
+
+```java
+void main() {
+
+    var numbers = List.of(1, 2, 3, 4, 5, 6, 7, 8, 9, 10);
+
+    long sum = numbers.parallelStream()
+        .peek(n -> println("Processing " + n + " on " + 
+            Thread.currentThread().getName()))
+        .mapToLong(n -> n * n)
+        .sum();
+
+    println("Sum of squares: " + sum);
+}
+```
+
+Parallel streams automatically partition data and process partitions in  
+parallel. They're effective for CPU-intensive operations on large datasets but  
+have overhead that can hurt performance for small collections.  
+
+
+## Thread-safe lazy initialization  
+
+Double-checked locking with volatile provides efficient lazy initialization.  
+
+```java
+class ExpensiveObject {
+    ExpensiveObject() {
+        println("Creating expensive object...");
+        try { Thread.sleep(1000); } catch (InterruptedException e) {}
+    }
+}
+
+class Singleton {
+    private static volatile ExpensiveObject instance;
+
+    static ExpensiveObject getInstance() {
+        if (instance == null) {
+            synchronized (Singleton.class) {
+                if (instance == null) {
+                    instance = new ExpensiveObject();
+                }
+            }
+        }
+        return instance;
+    }
+}
+
+void main() throws InterruptedException {
+
+    var threads = new ArrayList<Thread>();
+
+    for (int i = 0; i < 5; i++) {
+        var thread = new Thread(() -> {
+            var obj = Singleton.getInstance();
+            println("Got instance: " + obj);
+        });
+        threads.add(thread);
+        thread.start();
+    }
+
+    for (var thread : threads) {
+        thread.join();
+    }
+}
+```
+
+The outer null check avoids synchronization overhead after initialization. The  
+`volatile` keyword ensures proper visibility of the fully constructed object.  
+This pattern is mostly unnecessary with the simpler holder class idiom.  
diff --git a/concurrency/SupervisorWorkerEx.java b/concurrency/SupervisorWorkerEx.java
index 2a5b6b1e..a8df4147 100644
--- a/concurrency/SupervisorWorkerEx.java
+++ b/concurrency/SupervisorWorkerEx.java
@@ -10,6 +10,8 @@
 import java.awt.Dimension;
 import java.awt.EventQueue;
 import java.awt.event.ActionEvent;
+import java.awt.event.WindowAdapter;
+import java.awt.event.WindowEvent;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Random;
@@ -20,8 +22,7 @@
 import static javax.swing.GroupLayout.Alignment.CENTER;
 
 /*
- * This program initiates a background search for
- * various image files in a user's home directory.
+ * This program creates a supervisor worker
  *
  */
 class MyLabel extends JLabel {
@@ -49,6 +50,7 @@ public class SupervisorWorkerEx extends JFrame {
     private final int NUMBER_OF_LABELS = 6;
     private ArrayList<MyLabel> labels;
     private JButton btn;
+    private ExecutorService executorService;
 
     public SupervisorWorkerEx() {
 
@@ -57,6 +59,8 @@ public SupervisorWorkerEx() {
 
     private void initUI() {
 
+        executorService = Executors.newFixedThreadPool(NUMBER_OF_LABELS);
+
         labels = new ArrayList<>(NUMBER_OF_LABELS);
 
         for (int i = 0; i < NUMBER_OF_LABELS; i++) {
@@ -67,6 +71,17 @@ private void initUI() {
         btn = new JButton("Start");
         btn.addActionListener(new StartAction());
 
+        var windowAdapter = new WindowAdapter()
+        {
+            public void windowClosing(WindowEvent we)
+            {
+                System.out.println("shutting down");
+                executorService.shutdown();
+            }
+        };
+
+        addWindowListener(windowAdapter);
+
         createLayout();
 
         setTitle("Supervisor worker");
@@ -83,7 +98,9 @@ private void createLayout() {
         gl.setAutoCreateContainerGaps(true);
 
         gl.setHorizontalGroup(gl.createParallelGroup(CENTER)
+
                 .addComponent(labels.get(0))
+                .addGap(40)
                 .addComponent(labels.get(1))
                 .addComponent(labels.get(2))
                 .addComponent(labels.get(3))
@@ -144,13 +161,12 @@ private void doStartWorkers() {
             btn.setEnabled(false);
 
             var latch = new CountDownLatch(NUMBER_OF_LABELS);
-            ExecutorService executor
-                    = Executors.newFixedThreadPool(NUMBER_OF_LABELS);
+//            executorService = Executors.newFixedThreadPool(NUMBER_OF_LABELS);
 
             for (JLabel label : labels) {
 
                 label.setBackground(Color.white);
-                executor.execute(new Counter(label, latch));
+                executorService.execute(new Counter(label, latch));
             }
 
             var supervisor = new Supervisor(latch);
@@ -158,6 +174,8 @@ private void doStartWorkers() {
         }
     }
 
+
+
     private class Supervisor extends SwingWorker<Void, Void> {
 
         private final CountDownLatch latch;
@@ -169,7 +187,7 @@ public Supervisor(CountDownLatch latch) {
 
         @Override
         protected Void doInBackground() throws InterruptedException {
-            
+
             latch.await();
             return null;
         }
@@ -211,7 +229,7 @@ protected Void doInBackground() throws InterruptedException {
 
         @Override
         protected void process(List<Integer> values) {
-            label.setText(values.get(values.size() - 1).toString());
+            label.setText(values.getLast().toString());
         }
 
         @Override
diff --git a/concurrency/threads.md b/concurrency/threads.md
new file mode 100644
index 00000000..8b137891
--- /dev/null
+++ b/concurrency/threads.md
@@ -0,0 +1 @@
+
diff --git a/concurrent-collections.md b/concurrent-collections.md
new file mode 100644
index 00000000..f85730b5
--- /dev/null
+++ b/concurrent-collections.md
@@ -0,0 +1,1237 @@
+# Concurrent Collections in Java
+
+Concurrent collections are specialized data structures designed for safe and  
+efficient access by multiple threads simultaneously. Unlike traditional  
+collections from the Java Collections Framework, concurrent collections provide  
+built-in thread safety without requiring external synchronization, while  
+offering significantly better performance than using synchronized wrappers.  
+
+In multithreaded applications, data structures are frequently shared across  
+threads. Traditional collections like `HashMap`, `ArrayList`, and `LinkedList`  
+are not thread-safe—concurrent modifications can lead to data corruption, lost  
+updates, or `ConcurrentModificationException`. While wrapping these collections  
+with `Collections.synchronizedList` or `Collections.synchronizedMap` provides  
+basic thread safety, it creates a performance bottleneck by forcing exclusive  
+access during any operation.  
+
+Concurrent collections solve these problems through sophisticated internal  
+synchronization mechanisms that allow multiple threads to read and often write  
+simultaneously. They use techniques like lock striping, copy-on-write semantics,  
+and lock-free algorithms to maximize throughput while maintaining correctness.  
+
+## Why Traditional Collections Fail in Concurrent Environments  
+
+Standard Java collections are designed for single-threaded access. When multiple  
+threads access them simultaneously, several problems can occur:  
+
+| Problem | Description |
+|---------|-------------|
+| Data Corruption | Concurrent modifications can leave the data structure in an inconsistent state |
+| Lost Updates | One thread's changes may overwrite another's without either being aware |
+| ConcurrentModificationException | Iterating while another thread modifies throws this exception |
+| Race Conditions | Non-atomic compound operations lead to unpredictable behavior |
+| Visibility Issues | Changes made by one thread may not be visible to others |
+
+```java
+void main() throws InterruptedException {
+
+    // UNSAFE: HashMap is not thread-safe
+    var map = new HashMap<String, Integer>();
+    var threads = new ArrayList<Thread>();
+
+    for (int i = 0; i < 10; i++) {
+        int threadNum = i;
+        var thread = new Thread(() -> {
+            for (int j = 0; j < 1000; j++) {
+                String key = "key" + (j % 100);
+                // This compound operation is not atomic!
+                map.merge(key, 1, Integer::sum);
+            }
+        });
+        threads.add(thread);
+        thread.start();
+    }
+
+    for (var thread : threads) {
+        thread.join();
+    }
+
+    // Expected: 10 * 1000 / 100 * 100 = 10000 per key average
+    // Actual: Usually less due to race conditions
+    int total = map.values().stream().mapToInt(Integer::intValue).sum();
+    println("Total count: " + total + " (expected 10000)");
+}
+```
+
+This example demonstrates the dangers of using a non-thread-safe collection in  
+a concurrent environment. The `merge` operation involves reading, computing,  
+and writing—multiple threads can interleave these steps, causing lost updates  
+and incorrect final counts.  
+
+## ConcurrentHashMap  
+
+`ConcurrentHashMap` is the most widely used concurrent collection, providing a  
+thread-safe hash table implementation with excellent performance. Unlike  
+`Hashtable`, which synchronizes every method, `ConcurrentHashMap` uses  
+fine-grained locking and lock-free reads to enable high concurrency.  
+
+### Design and Evolution  
+
+The design of `ConcurrentHashMap` has evolved significantly across Java  
+versions:  
+
+**Java 1.5-7 (Segment-based locking)**: The map was divided into 16 segments  
+(by default), each acting as an independent hash table with its own lock.  
+This allowed 16 threads to write simultaneously if they accessed different  
+segments.  
+
+**Java 8+ (CAS and bucket-level synchronization)**: The segment design was  
+replaced with a more efficient approach. Reads are lock-free using volatile  
+reads. Writes use CAS (Compare-And-Swap) for empty buckets and synchronized  
+blocks on the first node for occupied buckets. This provides finer granularity  
+and better scalability.  
+
+| Feature | HashMap | Hashtable | ConcurrentHashMap |
+|---------|---------|-----------|-------------------|
+| Thread-safe | No | Yes | Yes |
+| Null keys/values | Yes | No | No |
+| Locking | None | Method-level | Bucket-level/CAS |
+| Iteration | Fail-fast | Fail-fast | Weakly consistent |
+| Performance (concurrent) | N/A | Poor | Excellent |
+
+### Basic operations  
+
+`ConcurrentHashMap` supports all standard map operations with full thread  
+safety.  
+
+```java
+import java.util.concurrent.ConcurrentHashMap;
+
+void main() {
+
+    var map = new ConcurrentHashMap<String, Integer>();
+
+    // Basic put and get
+    map.put("apple", 10);
+    map.put("banana", 20);
+    map.put("cherry", 30);
+
+    println("Apple count: " + map.get("apple"));
+    println("Contains banana: " + map.containsKey("banana"));
+    println("Map size: " + map.size());
+
+    // Thread-safe iteration (weakly consistent)
+    for (var entry : map.entrySet()) {
+        println(entry.getKey() + " -> " + entry.getValue());
+    }
+}
+```
+
+Unlike synchronized collections, iterating over a `ConcurrentHashMap` never  
+throws `ConcurrentModificationException`. The iterator reflects the state of  
+the map at some point during or after iteration begins. This "weakly  
+consistent" behavior is a deliberate trade-off for better concurrency.  
+
+### Atomic compound operations  
+
+`ConcurrentHashMap` provides several methods that perform atomic compound  
+operations, eliminating the need for external synchronization.  
+
+```java
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+
+void main() throws InterruptedException {
+
+    var wordCount = new ConcurrentHashMap<String, Integer>();
+    ExecutorService executor = Executors.newFixedThreadPool(4);
+
+    var words = List.of("apple", "banana", "apple", "cherry", 
+        "banana", "apple", "date", "cherry", "apple");
+
+    for (var word : words) {
+        executor.submit(() -> {
+            // Atomic increment - no external synchronization needed
+            wordCount.merge(word, 1, Integer::sum);
+        });
+    }
+
+    executor.shutdown();
+    executor.awaitTermination(10, TimeUnit.SECONDS);
+
+    println("Word counts:");
+    wordCount.forEach((word, count) -> 
+        println("  " + word + ": " + count));
+}
+```
+
+The `merge` method atomically combines the existing value with a new value  
+using the provided function. Other atomic operations include `compute`,  
+`computeIfAbsent`, and `computeIfPresent`. These eliminate race conditions  
+that would occur with separate get-then-put operations.  
+
+### ComputeIfAbsent for lazy initialization  
+
+The `computeIfAbsent` method is particularly useful for implementing  
+thread-safe lazy caches.  
+
+```java
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+
+void main() throws InterruptedException {
+
+    var cache = new ConcurrentHashMap<String, String>();
+    ExecutorService executor = Executors.newFixedThreadPool(10);
+
+    for (int i = 0; i < 20; i++) {
+        int requestNum = i;
+        executor.submit(() -> {
+            // Expensive computation runs only once per key
+            String result = cache.computeIfAbsent("user:123", key -> {
+                println("Computing value for " + key + 
+                    " (request " + requestNum + ")");
+                try { Thread.sleep(100); } catch (InterruptedException e) {}
+                return "UserData{id=123, name='Alice'}";
+            });
+            println("Request " + requestNum + " got: " + result);
+        });
+    }
+
+    executor.shutdown();
+    executor.awaitTermination(10, TimeUnit.SECONDS);
+}
+```
+
+Despite 20 concurrent requests, the expensive computation runs only once.  
+While one thread computes the value, other threads requesting the same key  
+block until the computation completes, then receive the cached result.  
+
+### Bulk operations  
+
+Java 8 added powerful bulk operations that execute in parallel across the map.  
+
+```java
+import java.util.concurrent.ConcurrentHashMap;
+
+void main() {
+
+    var scores = new ConcurrentHashMap<String, Integer>();
+    scores.put("Alice", 85);
+    scores.put("Bob", 92);
+    scores.put("Charlie", 78);
+    scores.put("Diana", 95);
+    scores.put("Eve", 88);
+
+    // forEach with parallelism threshold
+    println("All scores (parallel if > 3 elements):");
+    scores.forEach(1, (name, score) -> 
+        println("  " + name + ": " + score + 
+            " [" + Thread.currentThread().getName() + "]"));
+
+    // search - find first matching entry
+    String topScorer = scores.search(1, (name, score) -> 
+        score > 90 ? name : null);
+    println("First scorer above 90: " + topScorer);
+
+    // reduce - aggregate all values
+    int total = scores.reduce(1, 
+        (name, score) -> score,
+        Integer::sum);
+    println("Total score: " + total);
+
+    // reduceValues - simpler when you only need values
+    int max = scores.reduceValues(1, Integer::max);
+    println("Highest score: " + max);
+}
+```
+
+The first parameter (parallelism threshold) controls when operations run in  
+parallel. A threshold of 1 means always parallelize; Long.MAX_VALUE means  
+always run sequentially. These operations are efficient because they can  
+process different portions of the map concurrently.  
+
+## CopyOnWriteArrayList  
+
+`CopyOnWriteArrayList` is a thread-safe variant of `ArrayList` that creates a  
+fresh copy of the underlying array on every modification. This design makes it  
+ideal for scenarios where reads vastly outnumber writes.  
+
+### Copy-on-write principle  
+
+The copy-on-write strategy works as follows: reads access the current array  
+directly without locking, while writes create a complete copy of the array,  
+modify the copy, and atomically replace the reference to the underlying array.  
+
+```java
+import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+
+void main() throws InterruptedException {
+
+    var list = new CopyOnWriteArrayList<String>();
+    list.addAll(List.of("A", "B", "C"));
+
+    ExecutorService executor = Executors.newFixedThreadPool(4);
+
+    // Writers create new copies
+    executor.submit(() -> {
+        list.add("D");
+        println("Added D");
+    });
+
+    // Readers see consistent snapshots
+    for (int i = 0; i < 3; i++) {
+        int readerNum = i;
+        executor.submit(() -> {
+            println("Reader " + readerNum + " sees: " + list);
+        });
+    }
+
+    executor.shutdown();
+    executor.awaitTermination(10, TimeUnit.SECONDS);
+
+    println("Final list: " + list);
+}
+```
+
+Each read operation sees a consistent snapshot of the list at some point in  
+time. Modifications never interfere with ongoing reads because they work on  
+a separate copy. The atomic reference swap ensures readers always see a  
+complete, consistent state.  
+
+### Safe iteration during modification  
+
+One key advantage is that iterators never throw `ConcurrentModificationException`.  
+
+```java
+import java.util.concurrent.CopyOnWriteArrayList;
+
+void main() {
+
+    var listeners = new CopyOnWriteArrayList<String>();
+    listeners.addAll(List.of("Listener1", "Listener2", "Listener3"));
+
+    // Safe to iterate while modifying
+    for (String listener : listeners) {
+        println("Notifying: " + listener);
+
+        if (listener.equals("Listener2")) {
+            // This modification creates a new array
+            // The iterator continues on the original array
+            listeners.add("Listener4");
+            listeners.remove("Listener1");
+            println("  Modified list during iteration");
+        }
+    }
+
+    println("After iteration: " + listeners);
+}
+```
+
+The iterator operates on the snapshot that existed when iteration began.  
+Any modifications create a new array, but the iterator continues on the  
+original array. This is ideal for event listener patterns where callbacks  
+might register or unregister listeners.  
+
+### Performance characteristics  
+
+Understanding the trade-offs is crucial for choosing this collection.  
+
+```java
+import java.util.concurrent.CopyOnWriteArrayList;
+
+void main() {
+
+    var list = new CopyOnWriteArrayList<Integer>();
+
+    // Write performance: O(n) - copies entire array
+    long writeStart = System.nanoTime();
+    for (int i = 0; i < 1000; i++) {
+        list.add(i);
+    }
+    long writeTime = System.nanoTime() - writeStart;
+
+    // Read performance: O(1) for indexed access, no locking
+    long readStart = System.nanoTime();
+    for (int i = 0; i < 10000; i++) {
+        int ignored = list.get(i % list.size());
+    }
+    long readTime = System.nanoTime() - readStart;
+
+    println("1000 writes: " + writeTime / 1_000_000 + "ms");
+    println("10000 reads: " + readTime / 1_000_000 + "ms");
+    println("Read/Write ratio for efficiency: reads >> writes");
+}
+```
+
+Writes are expensive because they copy the entire array. As the list grows,  
+write operations become increasingly costly. Reads, however, are extremely  
+fast—just an array index access with no synchronization overhead.  
+
+### Use cases and anti-patterns  
+
+`CopyOnWriteArrayList` excels in specific scenarios.  
+
+```java
+import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.function.Consumer;
+
+// GOOD: Event listeners (rarely changed, frequently invoked)
+class EventBus {
+    private final CopyOnWriteArrayList<Consumer<String>> listeners = 
+        new CopyOnWriteArrayList<>();
+
+    void subscribe(Consumer<String> listener) {
+        listeners.add(listener);
+    }
+
+    void unsubscribe(Consumer<String> listener) {
+        listeners.remove(listener);
+    }
+
+    void publish(String event) {
+        // No synchronization needed during iteration
+        for (var listener : listeners) {
+            listener.accept(event);
+        }
+    }
+}
+
+void main() {
+
+    var bus = new EventBus();
+
+    // Listeners rarely change
+    bus.subscribe(e -> println("Handler 1: " + e));
+    bus.subscribe(e -> println("Handler 2: " + e));
+
+    // But events are published frequently
+    for (int i = 0; i < 5; i++) {
+        bus.publish("Event " + i);
+    }
+}
+```
+
+Ideal use cases include event listeners, configuration holders, and caches  
+that are read frequently but updated rarely. Avoid using it for lists that  
+are modified frequently, as each modification copies the entire array.  
+
+## BlockingQueue  
+
+`BlockingQueue` is an interface that extends `Queue` with operations that  
+block when the queue is empty (for takes) or full (for puts). This makes it  
+perfect for producer-consumer patterns, where producers add items and  
+consumers remove them, with automatic coordination between the two.  
+
+### Understanding blocking behavior  
+
+Blocking queues provide several types of operations with different behaviors.  
+
+| Operation | Throws Exception | Returns Special Value | Blocks | Times Out |
+|-----------|------------------|----------------------|--------|-----------|
+| Insert | add(e) | offer(e) | put(e) | offer(e, time, unit) |
+| Remove | remove() | poll() | take() | poll(time, unit) |
+| Examine | element() | peek() | N/A | N/A |
+
+```java
+import java.util.concurrent.ArrayBlockingQueue;
+import java.util.concurrent.BlockingQueue;
+
+void main() throws InterruptedException {
+
+    BlockingQueue<String> queue = new ArrayBlockingQueue<>(3);
+
+    // offer - returns false if queue is full (non-blocking)
+    println("offer A: " + queue.offer("A"));
+    println("offer B: " + queue.offer("B"));
+    println("offer C: " + queue.offer("C"));
+    println("offer D: " + queue.offer("D")); // false, queue full
+
+    // poll - returns null if queue is empty (non-blocking)
+    println("poll: " + queue.poll());
+    println("poll: " + queue.poll());
+    println("poll: " + queue.poll());
+    println("poll: " + queue.poll()); // null, queue empty
+
+    // put/take block until operation can proceed
+    println("Queue operations demonstrated");
+}
+```
+
+The blocking methods `put` and `take` are the most commonly used for  
+producer-consumer patterns. They automatically handle coordination between  
+threads, eliminating the need for explicit wait/notify logic.  
+
+### Producer-consumer pattern  
+
+The classic producer-consumer pattern is simplified with `BlockingQueue`.  
+
+```java
+import java.util.concurrent.ArrayBlockingQueue;
+import java.util.concurrent.BlockingQueue;
+
+void main() throws InterruptedException {
+
+    BlockingQueue<String> queue = new ArrayBlockingQueue<>(5);
+
+    // Producer thread
+    var producer = new Thread(() -> {
+        try {
+            for (int i = 1; i <= 10; i++) {
+                String item = "Item-" + i;
+                queue.put(item); // Blocks if queue is full
+                println("Produced: " + item + 
+                    " (queue size: " + queue.size() + ")");
+                Thread.sleep(100);
+            }
+            queue.put("DONE"); // Poison pill to signal completion
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+        }
+    });
+
+    // Consumer thread
+    var consumer = new Thread(() -> {
+        try {
+            while (true) {
+                String item = queue.take(); // Blocks if queue is empty
+                if ("DONE".equals(item)) break;
+                println("Consumed: " + item);
+                Thread.sleep(200); // Slower consumer
+            }
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+        }
+    });
+
+    producer.start();
+    consumer.start();
+
+    producer.join();
+    consumer.join();
+
+    println("Producer-consumer completed");
+}
+```
+
+The producer and consumer run at different speeds, but the blocking queue  
+automatically coordinates them. When the queue fills up, the producer waits.  
+When it empties, the consumer waits. This provides natural backpressure  
+without explicit synchronization.  
+
+### ArrayBlockingQueue  
+
+`ArrayBlockingQueue` is a bounded queue backed by a fixed-size array.  
+
+```java
+import java.util.concurrent.ArrayBlockingQueue;
+import java.util.concurrent.BlockingQueue;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+
+void main() throws InterruptedException {
+
+    // Fixed capacity - must be specified at creation
+    BlockingQueue<Integer> queue = new ArrayBlockingQueue<>(10);
+
+    ExecutorService executor = Executors.newFixedThreadPool(4);
+
+    // Multiple producers
+    for (int p = 0; p < 2; p++) {
+        int producerId = p;
+        executor.submit(() -> {
+            try {
+                for (int i = 0; i < 20; i++) {
+                    int item = producerId * 100 + i;
+                    queue.put(item);
+                    println("Producer " + producerId + " put: " + item);
+                }
+            } catch (InterruptedException e) {
+                Thread.currentThread().interrupt();
+            }
+        });
+    }
+
+    // Multiple consumers
+    for (int c = 0; c < 2; c++) {
+        int consumerId = c;
+        executor.submit(() -> {
+            try {
+                for (int i = 0; i < 20; i++) {
+                    Integer item = queue.take();
+                    println("Consumer " + consumerId + " got: " + item);
+                }
+            } catch (InterruptedException e) {
+                Thread.currentThread().interrupt();
+            }
+        });
+    }
+
+    executor.shutdown();
+    executor.awaitTermination(30, TimeUnit.SECONDS);
+}
+```
+
+`ArrayBlockingQueue` provides fair ordering when specified in the constructor.  
+Fair mode ensures threads acquire locks in FIFO order but may reduce  
+throughput. The bounded capacity prevents memory exhaustion when producers  
+outpace consumers.  
+
+### LinkedBlockingQueue  
+
+`LinkedBlockingQueue` is an optionally bounded queue backed by linked nodes.  
+
+```java
+import java.util.concurrent.LinkedBlockingQueue;
+import java.util.concurrent.BlockingQueue;
+
+void main() throws InterruptedException {
+
+    // Optionally bounded (unbounded if capacity not specified)
+    BlockingQueue<String> unbounded = new LinkedBlockingQueue<>();
+    BlockingQueue<String> bounded = new LinkedBlockingQueue<>(100);
+
+    // Separate locks for head and tail - better concurrency
+    var producer = new Thread(() -> {
+        try {
+            for (int i = 0; i < 1000; i++) {
+                bounded.put("Item-" + i);
+            }
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+        }
+    });
+
+    var consumer = new Thread(() -> {
+        try {
+            for (int i = 0; i < 1000; i++) {
+                bounded.take();
+            }
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+        }
+    });
+
+    long start = System.currentTimeMillis();
+    producer.start();
+    consumer.start();
+    producer.join();
+    consumer.join();
+    long elapsed = System.currentTimeMillis() - start;
+
+    println("Processed 1000 items in " + elapsed + "ms");
+    println("LinkedBlockingQueue uses separate locks for put/take");
+}
+```
+
+`LinkedBlockingQueue` uses separate locks for puts and takes, providing  
+better throughput than `ArrayBlockingQueue` when producers and consumers  
+operate at similar rates. However, it has higher memory overhead due to  
+node allocation.  
+
+### PriorityBlockingQueue  
+
+`PriorityBlockingQueue` orders elements by priority rather than FIFO.  
+
+```java
+import java.util.concurrent.PriorityBlockingQueue;
+import java.util.concurrent.BlockingQueue;
+
+record Task(String name, int priority) implements Comparable<Task> {
+    @Override
+    public int compareTo(Task other) {
+        return Integer.compare(this.priority, other.priority);
+    }
+}
+
+void main() throws InterruptedException {
+
+    BlockingQueue<Task> queue = new PriorityBlockingQueue<>();
+
+    // Add tasks with different priorities
+    queue.put(new Task("Low priority task", 3));
+    queue.put(new Task("High priority task", 1));
+    queue.put(new Task("Medium priority task", 2));
+    queue.put(new Task("Critical task", 0));
+
+    // Tasks come out in priority order
+    println("Processing tasks by priority:");
+    while (!queue.isEmpty()) {
+        Task task = queue.take();
+        println("  " + task.priority() + ": " + task.name());
+    }
+}
+```
+
+Elements must implement `Comparable` or a `Comparator` must be provided.  
+Note that `PriorityBlockingQueue` is unbounded—it never blocks on `put`.  
+The priority ordering applies only during removal, not insertion.  
+
+### DelayQueue  
+
+`DelayQueue` holds elements that become available only after their delay  
+expires.  
+
+```java
+import java.util.concurrent.DelayQueue;
+import java.util.concurrent.Delayed;
+import java.util.concurrent.TimeUnit;
+
+record DelayedTask(String name, long triggerTime) implements Delayed {
+    
+    @Override
+    public long getDelay(TimeUnit unit) {
+        return unit.convert(triggerTime - System.currentTimeMillis(), 
+            TimeUnit.MILLISECONDS);
+    }
+
+    @Override
+    public int compareTo(Delayed other) {
+        return Long.compare(getDelay(TimeUnit.MILLISECONDS), 
+            other.getDelay(TimeUnit.MILLISECONDS));
+    }
+}
+
+void main() throws InterruptedException {
+
+    var queue = new DelayQueue<DelayedTask>();
+    long now = System.currentTimeMillis();
+
+    // Schedule tasks with different delays
+    queue.put(new DelayedTask("Task A", now + 3000)); // 3 seconds
+    queue.put(new DelayedTask("Task B", now + 1000)); // 1 second
+    queue.put(new DelayedTask("Task C", now + 2000)); // 2 seconds
+
+    println("Waiting for tasks...");
+
+    for (int i = 0; i < 3; i++) {
+        DelayedTask task = queue.take(); // Blocks until delay expires
+        println("Executed: " + task.name() + " at " + 
+            (System.currentTimeMillis() - now) + "ms");
+    }
+}
+```
+
+`DelayQueue` is useful for implementing scheduled tasks, cache expiration,  
+retry logic with exponential backoff, or rate limiting. Elements are ordered  
+by their remaining delay time.  
+
+### SynchronousQueue  
+
+`SynchronousQueue` has no internal capacity—each put must wait for a take.  
+
+```java
+import java.util.concurrent.SynchronousQueue;
+import java.util.concurrent.BlockingQueue;
+
+void main() throws InterruptedException {
+
+    BlockingQueue<String> queue = new SynchronousQueue<>();
+
+    var producer = new Thread(() -> {
+        try {
+            for (int i = 1; i <= 5; i++) {
+                String item = "Item-" + i;
+                println("Producer putting: " + item);
+                queue.put(item); // Blocks until consumer takes
+                println("Producer handed off: " + item);
+            }
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+        }
+    });
+
+    var consumer = new Thread(() -> {
+        try {
+            for (int i = 0; i < 5; i++) {
+                Thread.sleep(500); // Slow consumer
+                String item = queue.take(); // Blocks until producer puts
+                println("Consumer received: " + item);
+            }
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+        }
+    });
+
+    producer.start();
+    consumer.start();
+
+    producer.join();
+    consumer.join();
+}
+```
+
+Each insertion blocks until another thread removes the element, and vice  
+versa. This creates a direct handoff between producer and consumer, useful  
+for implementing rendezvous points or when you want immediate processing  
+without buffering.  
+
+## Comparison of Concurrent Collections  
+
+| Collection | Thread-Safety Mechanism | Read Performance | Write Performance | Best Use Case |
+|------------|------------------------|------------------|-------------------|---------------|
+| ConcurrentHashMap | CAS + bucket-level locks | Excellent | Very Good | General-purpose thread-safe map |
+| CopyOnWriteArrayList | Copy-on-write | Excellent | Poor | Read-heavy lists, event listeners |
+| ArrayBlockingQueue | Single lock | Good | Good | Bounded producer-consumer |
+| LinkedBlockingQueue | Dual locks | Good | Good | High-throughput producer-consumer |
+| PriorityBlockingQueue | Single lock + heap | Good | Good | Priority-based task scheduling |
+| DelayQueue | Single lock | Good | Good | Scheduled tasks, timeouts |
+| SynchronousQueue | Lock-free handoff | N/A | N/A | Direct thread-to-thread transfer |
+
+## Best Practices  
+
+### Choosing the right collection  
+
+Select concurrent collections based on access patterns and requirements.  
+
+```java
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.concurrent.LinkedBlockingQueue;
+import java.util.concurrent.BlockingQueue;
+
+void main() {
+
+    // 1. For key-value data with concurrent access
+    //    Use ConcurrentHashMap
+    var cache = new ConcurrentHashMap<String, Object>();
+    cache.computeIfAbsent("config", k -> loadConfig());
+
+    // 2. For lists rarely modified but frequently iterated
+    //    Use CopyOnWriteArrayList
+    var listeners = new CopyOnWriteArrayList<Runnable>();
+
+    // 3. For producer-consumer patterns
+    //    Use appropriate BlockingQueue implementation
+    BlockingQueue<String> workQueue = new LinkedBlockingQueue<>(1000);
+
+    println("Collections selected based on use case:");
+    println("  ConcurrentHashMap for cache/config");
+    println("  CopyOnWriteArrayList for listeners");
+    println("  LinkedBlockingQueue for work distribution");
+}
+
+Object loadConfig() {
+    return Map.of("setting", "value");
+}
+```
+
+The key factors are: read/write ratio, whether you need ordering or  
+priority, bounded vs unbounded capacity requirements, and whether blocking  
+behavior is desired. Choosing incorrectly can severely impact performance.  
+
+### Avoiding unnecessary synchronization  
+
+Concurrent collections handle synchronization internally—don't add more.  
+
+```java
+import java.util.concurrent.ConcurrentHashMap;
+
+void main() {
+
+    var map = new ConcurrentHashMap<String, Integer>();
+
+    // BAD: External synchronization is unnecessary and harmful
+    // synchronized (map) {
+    //     map.put("key", map.getOrDefault("key", 0) + 1);
+    // }
+
+    // GOOD: Use built-in atomic operations
+    map.merge("key", 1, Integer::sum);
+
+    // BAD: Check-then-act race condition
+    // if (!map.containsKey("key")) {
+    //     map.put("key", computeValue());
+    // }
+
+    // GOOD: Atomic compute
+    map.computeIfAbsent("key", k -> computeValue());
+
+    println("Value: " + map.get("key"));
+}
+
+Integer computeValue() {
+    return 42;
+}
+```
+
+Adding external synchronization defeats the purpose of concurrent  
+collections, reducing performance without adding safety. Use the atomic  
+methods provided by the collection instead of compound check-then-act  
+operations.  
+
+### Monitoring performance trade-offs  
+
+Different workloads require different collections.  
+
+```java
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+import java.util.Collections;
+
+void main() throws InterruptedException {
+
+    int iterations = 10000;
+    int threads = 4;
+
+    // Test ConcurrentHashMap
+    var concurrentMap = new ConcurrentHashMap<Integer, Integer>();
+    long mapTime = measureConcurrentOps(concurrentMap, iterations, threads);
+
+    // Test synchronized map for comparison
+    var syncMap = Collections.synchronizedMap(new HashMap<Integer, Integer>());
+    long syncTime = measureConcurrentOps(syncMap, iterations, threads);
+
+    println("ConcurrentHashMap: " + mapTime + "ms");
+    println("Synchronized Map: " + syncTime + "ms");
+    println("ConcurrentHashMap is typically faster for concurrent access");
+}
+
+long measureConcurrentOps(Map<Integer, Integer> map, int iterations, 
+        int threads) throws InterruptedException {
+    ExecutorService executor = Executors.newFixedThreadPool(threads);
+    long start = System.currentTimeMillis();
+
+    for (int t = 0; t < threads; t++) {
+        executor.submit(() -> {
+            for (int i = 0; i < iterations; i++) {
+                map.put(i % 100, i);
+                map.get(i % 100);
+            }
+        });
+    }
+
+    executor.shutdown();
+    executor.awaitTermination(1, TimeUnit.MINUTES);
+    return System.currentTimeMillis() - start;
+}
+```
+
+Always benchmark with realistic workloads. The best collection depends on  
+your specific read/write ratio, contention level, and data size. Profile  
+in production-like conditions to make informed decisions.  
+
+## Common Pitfalls  
+
+### Misusing CopyOnWriteArrayList for writes  
+
+`CopyOnWriteArrayList` performs poorly with frequent modifications.  
+
+```java
+import java.util.concurrent.CopyOnWriteArrayList;
+
+void main() {
+
+    // BAD: Using CopyOnWriteArrayList for write-heavy workload
+    var cowList = new CopyOnWriteArrayList<Integer>();
+
+    long cowStart = System.currentTimeMillis();
+    for (int i = 0; i < 10000; i++) {
+        cowList.add(i); // Each add copies the entire array!
+    }
+    long cowTime = System.currentTimeMillis() - cowStart;
+
+    // GOOD: Use ConcurrentLinkedQueue or synchronized list for writes
+    var arrayList = new ArrayList<Integer>();
+
+    long alStart = System.currentTimeMillis();
+    for (int i = 0; i < 10000; i++) {
+        synchronized (arrayList) {
+            arrayList.add(i);
+        }
+    }
+    long alTime = System.currentTimeMillis() - alStart;
+
+    println("CopyOnWriteArrayList: " + cowTime + "ms");
+    println("Synchronized ArrayList: " + alTime + "ms");
+    println("Use CopyOnWriteArrayList only for read-heavy workloads");
+}
+```
+
+Each modification copies the entire array, making write performance O(n).  
+For lists with frequent modifications, use `ConcurrentLinkedQueue` or  
+a properly synchronized collection.  
+
+### Assuming compound operations are atomic  
+
+Individual operations are atomic, but sequences of operations are not.  
+
+```java
+import java.util.concurrent.ConcurrentHashMap;
+
+void main() throws InterruptedException {
+
+    var map = new ConcurrentHashMap<String, Integer>();
+    map.put("balance", 1000);
+
+    // BAD: Non-atomic compound operation
+    // var balance = map.get("balance");
+    // if (balance >= 100) {
+    //     map.put("balance", balance - 100); // Race condition!
+    // }
+
+    // GOOD: Use atomic operations
+    var threads = new ArrayList<Thread>();
+    for (int i = 0; i < 20; i++) {
+        var thread = new Thread(() -> {
+            map.compute("balance", (key, balance) -> {
+                if (balance != null && balance >= 100) {
+                    return balance - 100;
+                }
+                return balance;
+            });
+        });
+        threads.add(thread);
+        thread.start();
+    }
+
+    for (var thread : threads) {
+        thread.join();
+    }
+
+    println("Final balance: " + map.get("balance"));
+    println("Use compute() for atomic read-modify-write operations");
+}
+```
+
+The check-then-act pattern is not thread-safe even with concurrent  
+collections. Another thread can modify the value between your check and  
+your action. Always use atomic methods like `compute`, `merge`, or  
+`computeIfAbsent` for compound operations.  
+
+### Ignoring BlockingQueue capacity limits  
+
+Unbounded queues can lead to memory exhaustion.  
+
+```java
+import java.util.concurrent.LinkedBlockingQueue;
+import java.util.concurrent.ArrayBlockingQueue;
+import java.util.concurrent.BlockingQueue;
+
+void main() throws InterruptedException {
+
+    // RISKY: Unbounded queue can grow indefinitely
+    BlockingQueue<String> unbounded = new LinkedBlockingQueue<>();
+    // If producer is faster than consumer, memory exhaustion!
+
+    // BETTER: Bounded queue with capacity limit
+    BlockingQueue<String> bounded = new ArrayBlockingQueue<>(1000);
+
+    // Producer that respects backpressure
+    var producer = new Thread(() -> {
+        try {
+            for (int i = 0; i < 2000; i++) {
+                // put() blocks when queue is full - natural backpressure
+                bounded.put("Item-" + i);
+                if (i % 500 == 0) {
+                    println("Produced " + i + " items, queue size: " + 
+                        bounded.size());
+                }
+            }
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+        }
+    });
+
+    var consumer = new Thread(() -> {
+        try {
+            for (int i = 0; i < 2000; i++) {
+                bounded.take();
+                Thread.sleep(1); // Slow consumer
+            }
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+        }
+    });
+
+    producer.start();
+    consumer.start();
+
+    producer.join();
+    consumer.join();
+
+    println("Bounded queues prevent memory exhaustion through backpressure");
+}
+```
+
+Always consider capacity limits when using blocking queues. Bounded queues  
+provide natural backpressure—when the queue fills up, producers block  
+until space is available, preventing memory exhaustion.  
+
+## Advanced Topics  
+
+### Integration with Executors  
+
+Concurrent collections work seamlessly with thread pools.  
+
+```java
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.LinkedBlockingQueue;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+
+void main() throws InterruptedException {
+
+    var results = new ConcurrentHashMap<Integer, String>();
+    var workQueue = new LinkedBlockingQueue<Integer>(100);
+    ExecutorService executor = Executors.newFixedThreadPool(4);
+
+    // Submit work items
+    for (int i = 0; i < 50; i++) {
+        workQueue.put(i);
+    }
+
+    // Workers process items and store results
+    for (int w = 0; w < 4; w++) {
+        executor.submit(() -> {
+            while (!workQueue.isEmpty()) {
+                Integer item = workQueue.poll();
+                if (item != null) {
+                    results.put(item, "Result-" + item);
+                }
+            }
+        });
+    }
+
+    executor.shutdown();
+    executor.awaitTermination(10, TimeUnit.SECONDS);
+
+    println("Processed " + results.size() + " items");
+    println("Sample: " + results.get(25));
+}
+```
+
+Thread pools distribute work across threads, while concurrent collections  
+provide safe shared state. This combination is the foundation of most  
+concurrent Java applications.  
+
+### Using with parallel streams  
+
+Concurrent collections can safely collect parallel stream results.  
+
+```java
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.stream.IntStream;
+
+void main() {
+
+    var frequencyMap = new ConcurrentHashMap<Integer, Long>();
+
+    // Process in parallel, collect to concurrent map
+    IntStream.range(0, 10000)
+        .parallel()
+        .forEach(i -> {
+            int key = i % 10;
+            frequencyMap.merge(key, 1L, Long::sum);
+        });
+
+    println("Frequency counts:");
+    frequencyMap.forEach((key, count) -> 
+        println("  " + key + ": " + count));
+
+    long total = frequencyMap.values().stream().mapToLong(Long::longValue).sum();
+    println("Total: " + total);
+}
+```
+
+When collecting results from parallel streams into shared data structures,  
+concurrent collections eliminate the need for external synchronization.  
+The `merge` operation safely handles concurrent updates from multiple  
+stream threads.  
+
+### Combining with synchronization primitives  
+
+For complex coordination, combine concurrent collections with other primitives.  
+
+```java
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+
+void main() throws InterruptedException {
+
+    var sharedState = new ConcurrentHashMap<String, Integer>();
+    var startLatch = new CountDownLatch(1);
+    var completionLatch = new CountDownLatch(5);
+
+    ExecutorService executor = Executors.newFixedThreadPool(5);
+
+    for (int i = 0; i < 5; i++) {
+        int workerId = i;
+        executor.submit(() -> {
+            try {
+                startLatch.await(); // Wait for signal to start
+                for (int j = 0; j < 1000; j++) {
+                    sharedState.merge("counter", 1, Integer::sum);
+                }
+                println("Worker " + workerId + " completed");
+            } catch (InterruptedException e) {
+                Thread.currentThread().interrupt();
+            } finally {
+                completionLatch.countDown();
+            }
+        });
+    }
+
+    println("All workers ready, starting...");
+    startLatch.countDown(); // Signal all workers to start
+
+    completionLatch.await(); // Wait for all to complete
+    println("Final counter: " + sharedState.get("counter"));
+
+    executor.shutdown();
+}
+```
+
+`CountDownLatch` ensures all workers start simultaneously and the main  
+thread waits for completion. The concurrent map safely aggregates results.  
+This pattern is useful for benchmarking and coordinated parallel operations.  
+
+## Conclusion  
+
+Concurrent collections are essential building blocks for modern multithreaded  
+Java applications. They provide thread-safe data structures with significantly  
+better performance than synchronized wrappers, using sophisticated internal  
+mechanisms like CAS operations, lock striping, and copy-on-write semantics.  
+
+**ConcurrentHashMap** is the workhorse for shared key-value data, offering  
+excellent concurrency through fine-grained locking and atomic compound  
+operations. **CopyOnWriteArrayList** excels in read-heavy scenarios like  
+event listener management, trading write performance for lock-free reads.  
+**BlockingQueue** implementations simplify producer-consumer patterns with  
+built-in blocking behavior that automatically coordinates threads.  
+
+Key principles for effective use:  
+
+1. **Choose based on access patterns**: Match the collection to your read/write  
+   ratio and concurrency requirements  
+
+2. **Use atomic operations**: Leverage built-in methods like `compute`,  
+   `merge`, and `computeIfAbsent` for compound operations  
+
+3. **Avoid external synchronization**: The collections handle thread safety  
+   internally—adding more locks hurts performance  
+
+4. **Respect capacity limits**: Bounded queues prevent memory exhaustion  
+   through natural backpressure  
+
+5. **Understand iteration semantics**: Weakly consistent iterators may not  
+   reflect the absolute latest state but never throw exceptions  
+
+By understanding the strengths and trade-offs of each concurrent collection,  
+developers can build applications that are both correct and performant under  
+concurrent access, without the complexity of manual synchronization.  
diff --git a/conversions/AutoboxingEx.java b/conversions/AutoboxingEx.java
index ecbe6154..3164f541 100644
--- a/conversions/AutoboxingEx.java
+++ b/conversions/AutoboxingEx.java
@@ -1,21 +1,17 @@
-package com.zetcode;
 
-public class AutoboxingEx {
-    
-    private static int cube(int x) {
-        
-        return x * x * x;
-    }
+int cube(int x) {
 
-    public static void main(String[] args) {
-        
-        Integer i = 10;
-        int j = i;
-        
-        System.out.println(i);
-        System.out.println(j);        
-        
-        Integer a = cube(i);
-        System.out.println(a);    
-    }
+  return x * x * x;
+}
+
+void main() {
+
+  Integer i = 10;
+  int j = i;
+
+  IO.println(i);
+  IO.println(j);
+
+  Integer a = cube(i);
+  IO.println(a);
 }
diff --git a/conversions/ConversionsEx.java b/conversions/ConversionsEx.java
index 39808de2..c1c8308f 100644
--- a/conversions/ConversionsEx.java
+++ b/conversions/ConversionsEx.java
@@ -1,53 +1,45 @@
-package com.zetcode;
-
-import java.util.Objects;
-
-public class ConversionsEx {
-
-    public static void main(String[] args) {
-        
-        // https://stackoverflow.com/questions/1514910/how-to-properly-compare-two-integers-in-java?utm_medium=organic&utm_source=google_rich_qa&utm_campaign=google_rich_qa
-
-        Integer m = 4;
-        Integer n = 5;
-        
-        if (Objects.equals(m, n)) {
-            
-            System.out.println("Variables are equal");
-        } else {
-            System.out.println("Variables are not equal");
-        }
-        
-        if (m.intValue() == n.intValue()) {
-            
-            System.out.println("Variables are equal");
-        } else {
-            System.out.println("Variables are not equal");
-        }
-        
-
-        // you can't convert-and-autobox in one step
-        // you can't implicitly narrow a type
-        // 1L
-        Long num = 1L;
-
-        // Why new Long(10) compiles? Because there is a suitable constructor 
-        // available that excepts integer arguments. 
-        Long num2 = new Long(2);
-
-        Byte b = new Byte((byte) 10);
-        byte b2 = 34;
-
-        Long x = (long) 10;
-
-        int x2 = (int) 23.4;
-        double x3 = 23;
-
-        double x4 = 32f;
-        float x5 = (float) 35.567d;
-
-        byte g = (12) * 3;
-        //byte g2 = 3 * g; 
-    }
 
+void main() {
+
+
+  Integer m = 4;
+  Integer n = 5;
+
+  if (Objects.equals(m, n)) {
+
+    System.out.println("Variables are equal");
+  } else {
+    System.out.println("Variables are not equal");
+  }
+
+  if (m.intValue() == n.intValue()) {
+
+    System.out.println("Variables are equal");
+  } else {
+    System.out.println("Variables are not equal");
+  }
+
+  // you can't convert-and-autobox in one step
+  // you can't implicitly narrow a type
+  // 1L
+  Long num = 1L;
+
+  Long num2 = Long.valueOf(2);
+
+  Byte b = Byte.valueOf((byte) 10);
+  byte b2 = 34;
+
+  Long x = (long) 10;
+
+  int x2 = (int) 23.4;
+  double x3 = 23;
+
+  double x4 = 32f;
+  float x5 = (float) 35.567d;
+
+  byte g = (12) * 3;
+  // byte g2 = 3 * g;
 }
+
+
+// https://stackoverflow.com/questions/1514910/how-to-properly-compare-two-integers-in-java?utm_medium=organic&utm_source=google_rich_qa&utm_campaign=google_rich_qa
diff --git a/floating-point.md b/floating-point.md
new file mode 100644
index 00000000..803b290b
--- /dev/null
+++ b/floating-point.md
@@ -0,0 +1,1343 @@
+# Floating-Point Math in Java  
+
+Floating-point numbers are fundamental to scientific computing, graphics, machine  
+learning, and countless other domains in Java programming. Understanding their  
+representation, limitations, and proper usage is essential for writing robust  
+numerical code. This document explores floating-point arithmetic in Java, covering  
+the IEEE 754 standard, common pitfalls, precision issues, and best practices.  
+
+Java provides two primitive floating-point types: `float` (32-bit) and `double`  
+(64-bit). The `double` type is the default and most commonly used for decimal  
+values. While floating-point numbers offer excellent range and performance, they  
+cannot represent all decimal values exactly, leading to subtle bugs if not handled  
+carefully.  
+
+
+## IEEE 754 Standard  
+
+Java implements the IEEE 754 standard for floating-point arithmetic, which defines  
+how floating-point numbers are stored and calculated. A floating-point number  
+consists of three parts: the sign bit, the exponent, and the mantissa (significand).  
+
+| Type     | Sign Bit | Exponent Bits | Mantissa Bits | Total Bits |  
+|----------|----------|---------------|---------------|------------|  
+| `float`  | 1        | 8             | 23            | 32         |  
+| `double` | 1        | 11            | 52            | 64         |  
+
+The formula for the represented value is: `(-1)^sign × 2^(exponent-bias) × 1.mantissa`  
+
+The limited number of bits means many decimal fractions cannot be represented  
+exactly in binary floating-point. For example, 0.1 in decimal is a repeating  
+fraction in binary, similar to how 1/3 is repeating in decimal.  
+
+
+## Basic float and double  
+
+The most basic usage of floating-point types demonstrates their declaration and  
+simple operations.  
+
+```java
+void main() {
+
+    float floatValue = 3.14f;
+    double doubleValue = 3.14159265358979;
+
+    IO.println("Float value: " + floatValue);
+    IO.println("Double value: " + doubleValue);
+    IO.println("Float size: " + Float.BYTES + " bytes");
+    IO.println("Double size: " + Double.BYTES + " bytes");
+}
+```
+
+The `float` type requires an `f` suffix on literals to distinguish from `double`.  
+Without the suffix, Java assumes the literal is a `double`. The `float` type  
+provides approximately 7 significant decimal digits of precision, while `double`  
+provides approximately 15-16 digits.  
+
+
+## Precision limits  
+
+Floating-point types have inherent precision limits due to their binary  
+representation.  
+
+```java
+void main() {
+
+    IO.println("Float max value: " + Float.MAX_VALUE);
+    IO.println("Float min positive: " + Float.MIN_VALUE);
+    IO.println("Float min normal: " + Float.MIN_NORMAL);
+
+    IO.println("Double max value: " + Double.MAX_VALUE);
+    IO.println("Double min positive: " + Double.MIN_VALUE);
+    IO.println("Double min normal: " + Double.MIN_NORMAL);
+}
+```
+
+The difference between `MIN_VALUE` and `MIN_NORMAL` relates to denormalized  
+numbers. `MIN_VALUE` is the smallest positive value that can be represented,  
+while `MIN_NORMAL` is the smallest positive normalized value. Denormalized  
+numbers provide gradual underflow but with reduced precision.  
+
+
+## The classic 0.1 + 0.2 problem  
+
+The most famous floating-point issue demonstrates that simple decimal fractions  
+cannot be represented exactly.  
+
+```java
+void main() {
+
+    double a = 0.1;
+    double b = 0.2;
+    double sum = a + b;
+
+    IO.println("0.1 + 0.2 = " + sum);
+    IO.println("Expected: 0.3");
+    IO.println("Equal to 0.3? " + (sum == 0.3));
+    IO.println("Actual sum: " + String.format("%.20f", sum));
+}
+```
+
+The result is `0.30000000000000004` rather than `0.3` because neither 0.1 nor  
+0.2 can be represented exactly in binary floating-point. This is not a bug but  
+a fundamental characteristic of binary floating-point representation. The small  
+error accumulates during addition.  
+
+
+## Special values - NaN  
+
+IEEE 754 defines special values including NaN (Not a Number) for undefined  
+mathematical operations.  
+
+```java
+void main() {
+
+    double nanResult = 0.0 / 0.0;
+    double sqrtNegative = Math.sqrt(-1);
+    double logNegative = Math.log(-1);
+
+    IO.println("0.0 / 0.0 = " + nanResult);
+    IO.println("sqrt(-1) = " + sqrtNegative);
+    IO.println("log(-1) = " + logNegative);
+
+    IO.println("Is NaN: " + Double.isNaN(nanResult));
+    IO.println("NaN == NaN: " + (nanResult == nanResult));
+}
+```
+
+NaN has the unusual property of not being equal to itself. This is by design in  
+IEEE 754—`NaN == NaN` always returns `false`. Use `Double.isNaN` or `Float.isNaN`  
+to check for NaN values. NaN propagates through calculations: any operation  
+involving NaN produces NaN.  
+
+
+## Special values - Infinity  
+
+Positive and negative infinity represent overflow results and mathematical  
+infinity.  
+
+```java
+void main() {
+
+    double posInf = 1.0 / 0.0;
+    double negInf = -1.0 / 0.0;
+    double overflow = Double.MAX_VALUE * 2;
+
+    IO.println("1.0 / 0.0 = " + posInf);
+    IO.println("-1.0 / 0.0 = " + negInf);
+    IO.println("MAX_VALUE * 2 = " + overflow);
+
+    IO.println("Is infinite: " + Double.isInfinite(posInf));
+    IO.println("Positive infinity: " + Double.POSITIVE_INFINITY);
+    IO.println("Negative infinity: " + Double.NEGATIVE_INFINITY);
+
+    IO.println("Infinity - Infinity = " + (posInf - posInf));
+    IO.println("1.0 / Infinity = " + (1.0 / posInf));
+}
+```
+
+Unlike integer division by zero which throws an exception, floating-point  
+division by zero produces infinity. Operations with infinity follow mathematical  
+rules: infinity minus infinity produces NaN, and finite values divided by  
+infinity produce zero.  
+
+
+## Signed zero  
+
+IEEE 754 distinguishes between positive zero and negative zero, though they  
+compare as equal.  
+
+```java
+void main() {
+
+    double posZero = 0.0;
+    double negZero = -0.0;
+
+    IO.println("Positive zero: " + posZero);
+    IO.println("Negative zero: " + negZero);
+    IO.println("+0.0 == -0.0: " + (posZero == negZero));
+
+    IO.println("1.0 / +0.0 = " + (1.0 / posZero));
+    IO.println("1.0 / -0.0 = " + (1.0 / negZero));
+
+    IO.println("Compare: " + Double.compare(posZero, negZero));
+}
+```
+
+While `+0.0 == -0.0` returns `true`, dividing by them produces different  
+infinities. `Double.compare` distinguishes between positive and negative zero,  
+returning a non-zero value. This behavior is important in mathematical functions  
+where the sign of zero carries meaning.  
+
+
+## Checking for finite values  
+
+Testing whether a value is finite (not NaN or Infinity) is essential for robust  
+numerical code.  
+
+```java
+void main() {
+
+    double[] values = {
+        1.0, Double.NaN, Double.POSITIVE_INFINITY, 
+        Double.NEGATIVE_INFINITY, 0.0, -0.0
+    };
+
+    for (double v : values) {
+        IO.println(v + " -> isNaN: " + Double.isNaN(v) + 
+                   ", isInfinite: " + Double.isInfinite(v) +
+                   ", isFinite: " + Double.isFinite(v));
+    }
+}
+```
+
+The `Double.isFinite` method returns `true` only if the value is neither NaN nor  
+infinity. This is useful for validating inputs and results in numerical  
+calculations. Always validate floating-point inputs before using them in  
+critical calculations.  
+
+
+## Equality comparison pitfall  
+
+Direct equality comparison with `==` fails for many floating-point calculations.  
+
+```java
+void main() {
+
+    double a = 1.0;
+    double b = 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1;
+
+    IO.println("a = " + a);
+    IO.println("b = " + String.format("%.20f", b));
+    IO.println("a == b: " + (a == b));
+    IO.println("Difference: " + Math.abs(a - b));
+}
+```
+
+Adding 0.1 ten times does not equal exactly 1.0 due to accumulated rounding  
+errors. Each addition compounds the representation error. This demonstrates why  
+direct equality testing is unreliable for floating-point values computed through  
+different paths.  
+
+
+## Epsilon-based comparison  
+
+Using a tolerance (epsilon) value enables practical floating-point comparisons.  
+
+```java
+void main() {
+
+    double a = 1.0;
+    double b = 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1;
+    double epsilon = 1e-10;
+
+    boolean equal = Math.abs(a - b) < epsilon;
+    IO.println("Using epsilon comparison: " + equal);
+
+    double c = 1000000.0;
+    double d = c + 0.0000001;
+    IO.println("Large values differ? " + (Math.abs(c - d) < epsilon));
+}
+```
+
+Epsilon comparison works for values near zero but becomes problematic for large  
+values. A fixed epsilon may be too large for small values and too small for  
+large values. Consider using relative epsilon or `Math.ulp` for more robust  
+comparisons.  
+
+
+## Relative epsilon comparison  
+
+A relative epsilon adapts to the magnitude of the numbers being compared.  
+
+```java
+void main() {
+
+    double a = 1000000.1;
+    double b = 1000000.2;
+
+    double absoluteEpsilon = 1e-10;
+    double relativeEpsilon = 1e-9;
+
+    boolean absoluteEqual = Math.abs(a - b) < absoluteEpsilon;
+    boolean relativeEqual = Math.abs(a - b) < relativeEpsilon * Math.max(Math.abs(a), Math.abs(b));
+
+    IO.println("Absolute comparison: " + absoluteEqual);
+    IO.println("Relative comparison: " + relativeEqual);
+}
+```
+
+Relative epsilon scales with the magnitude of the values. For very large numbers,  
+the absolute difference can be large even when the relative difference is tiny.  
+This approach provides more consistent behavior across different value ranges.  
+
+
+## Using Math.ulp for comparison  
+
+Unit in the Last Place (ULP) represents the smallest difference between two  
+consecutive floating-point values.  
+
+```java
+void main() {
+
+    double small = 1.0;
+    double large = 1_000_000.0;
+
+    IO.println("ULP of 1.0: " + Math.ulp(small));
+    IO.println("ULP of 1,000,000: " + Math.ulp(large));
+
+    double a = 1.0;
+    double b = a + Math.ulp(a);
+    IO.println("1.0 and next representable: differ by " + (b - a));
+
+    int ulpDifference = 3;
+    boolean closeEnough = Math.abs(a - b) <= ulpDifference * Math.ulp(Math.max(a, b));
+    IO.println("Within 3 ULPs: " + closeEnough);
+}
+```
+
+ULP-based comparison is the most precise way to compare floating-point values.  
+Two values within a few ULPs of each other are essentially equal for practical  
+purposes. The ULP size increases with the magnitude of the number, providing  
+automatic scaling.  
+
+
+## Error accumulation  
+
+Repeated operations accumulate errors, potentially leading to significant  
+inaccuracies.  
+
+```java
+void main() {
+
+    double sum = 0.0;
+    int iterations = 1_000_000;
+
+    for (int i = 0; i < iterations; i++) {
+        sum += 0.1;
+    }
+
+    double expected = iterations * 0.1;
+    IO.println("Accumulated sum: " + sum);
+    IO.println("Expected: " + expected);
+    IO.println("Error: " + Math.abs(sum - expected));
+}
+```
+
+Adding 0.1 one million times produces a noticeable error. The error grows with  
+each operation because each addition introduces a small rounding error. This is  
+particularly problematic in simulations and iterative algorithms that perform  
+millions of calculations.  
+
+
+## Kahan summation algorithm  
+
+The Kahan summation algorithm reduces accumulated errors in floating-point sums.  
+
+```java
+void main() {
+
+    int iterations = 1_000_000;
+
+    double naiveSum = 0.0;
+    for (int i = 0; i < iterations; i++) {
+        naiveSum += 0.1;
+    }
+
+    double kahanSum = 0.0;
+    double compensation = 0.0;
+    for (int i = 0; i < iterations; i++) {
+        double y = 0.1 - compensation;
+        double t = kahanSum + y;
+        compensation = (t - kahanSum) - y;
+        kahanSum = t;
+    }
+
+    double expected = iterations * 0.1;
+    IO.println("Naive sum error: " + Math.abs(naiveSum - expected));
+    IO.println("Kahan sum error: " + Math.abs(kahanSum - expected));
+}
+```
+
+Kahan summation tracks the lost low-order bits and compensates in subsequent  
+additions. This algorithm is particularly valuable when summing many small values  
+or when values vary greatly in magnitude. Many numerical libraries use this or  
+similar compensated summation techniques.  
+
+
+## Overflow behavior  
+
+Exceeding the maximum representable value causes overflow to infinity.  
+
+```java
+void main() {
+
+    double big = Double.MAX_VALUE;
+    IO.println("MAX_VALUE: " + big);
+    IO.println("MAX_VALUE * 1.1: " + (big * 1.1));
+    IO.println("MAX_VALUE + MAX_VALUE: " + (big + big));
+
+    float floatBig = Float.MAX_VALUE;
+    IO.println("Float MAX_VALUE * 2: " + (floatBig * 2));
+
+    double result = 1e308 * 1e10;
+    IO.println("1e308 * 1e10 = " + result);
+}
+```
+
+Unlike integer overflow which wraps around, floating-point overflow produces  
+infinity. This is often more detectable but can still cause problems if not  
+handled. Always check for infinite results when working with potentially large  
+values.  
+
+
+## Underflow behavior  
+
+Values smaller than can be represented become zero or denormalized numbers.  
+
+```java
+void main() {
+
+    double tiny = Double.MIN_NORMAL;
+    IO.println("MIN_NORMAL: " + tiny);
+    IO.println("MIN_NORMAL / 2: " + (tiny / 2));
+    IO.println("MIN_NORMAL / 1e20: " + (tiny / 1e20));
+
+    double denormal = Double.MIN_VALUE;
+    IO.println("MIN_VALUE (denormal): " + denormal);
+    IO.println("MIN_VALUE / 2: " + (denormal / 2));
+}
+```
+
+Gradual underflow through denormalized numbers helps maintain numerical  
+properties but with reduced precision. Operations in the denormalized range  
+can be slower on some processors and should be avoided when performance is  
+critical.  
+
+
+## Loss of significance  
+
+Subtracting nearly equal numbers loses significant digits of precision.  
+
+```java
+void main() {
+
+    double a = 1.0000000000000001;
+    double b = 1.0;
+
+    double diff = a - b;
+    IO.println("a = " + a);
+    IO.println("b = " + b);
+    IO.println("a - b = " + diff);
+    IO.println("Expected: 1e-16");
+
+    double large1 = 1234567890.123456;
+    double large2 = 1234567890.123455;
+    IO.println("Large subtraction: " + (large1 - large2));
+}
+```
+
+When subtracting two nearly equal large numbers, most significant bits cancel  
+out, leaving only the least significant bits which may contain mostly rounding  
+errors. This catastrophic cancellation can destroy accuracy in numerical  
+algorithms.  
+
+
+## Associativity failure  
+
+Floating-point addition is not associative due to rounding at each step.  
+
+```java
+void main() {
+
+    double a = 1e16;
+    double b = -1e16;
+    double c = 1.0;
+
+    double result1 = (a + b) + c;
+    double result2 = a + (b + c);
+
+    IO.println("(a + b) + c = " + result1);
+    IO.println("a + (b + c) = " + result2);
+    IO.println("Equal? " + (result1 == result2));
+}
+```
+
+In exact arithmetic, both expressions equal 1.0. However, `b + c` loses the  
+small value `c` because `1e16` is too large to represent the difference of 1.  
+This non-associativity means the order of operations matters for floating-point  
+accuracy.  
+
+
+## Float vs Double precision  
+
+Comparing precision between float and double shows significant differences.  
+
+```java
+void main() {
+
+    float f = 1.0f / 3.0f;
+    double d = 1.0 / 3.0;
+
+    IO.println("Float 1/3: " + String.format("%.20f", f));
+    IO.println("Double 1/3: " + String.format("%.20f", d));
+
+    float fSum = 0.0f;
+    double dSum = 0.0;
+    for (int i = 0; i < 1000; i++) {
+        fSum += 0.001f;
+        dSum += 0.001;
+    }
+
+    IO.println("Float sum: " + fSum);
+    IO.println("Double sum: " + dSum);
+}
+```
+
+Float provides roughly 7 significant decimal digits while double provides about  
+15-16. For most applications, double is preferred due to its greater precision.  
+Float is mainly useful when memory is constrained or when interacting with APIs  
+that require single precision.  
+
+
+## BigDecimal introduction  
+
+`BigDecimal` provides arbitrary-precision decimal arithmetic, essential for  
+financial calculations.  
+
+```java
+import java.math.BigDecimal;
+
+void main() {
+
+    var a = new BigDecimal("0.1");
+    var b = new BigDecimal("0.2");
+    var sum = a.add(b);
+
+    IO.println("BigDecimal 0.1 + 0.2 = " + sum);
+    IO.println("Equals 0.3? " + sum.equals(new BigDecimal("0.3")));
+
+    double doubleSum = 0.1 + 0.2;
+    IO.println("Double 0.1 + 0.2 = " + doubleSum);
+}
+```
+
+BigDecimal represents decimal numbers exactly using a scaled integer approach.  
+Always use the String constructor to avoid inheriting floating-point  
+imprecisions. For financial applications where exact decimal arithmetic is  
+required, BigDecimal is the only correct choice.  
+
+
+## BigDecimal from double pitfall  
+
+Creating BigDecimal from double inherits the double's imprecision.  
+
+```java
+import java.math.BigDecimal;
+
+void main() {
+
+    var fromDouble = new BigDecimal(0.1);
+    var fromString = new BigDecimal("0.1");
+
+    IO.println("From double: " + fromDouble);
+    IO.println("From string: " + fromString);
+    IO.println("Equal? " + fromDouble.equals(fromString));
+
+    var correct = BigDecimal.valueOf(0.1);
+    IO.println("Using valueOf: " + correct);
+}
+```
+
+The double constructor captures the actual value stored in the double, including  
+its imprecision. Always use the String constructor for exact decimal values.  
+`BigDecimal.valueOf` is an alternative that uses the canonical string  
+representation of the double.  
+
+
+## BigDecimal rounding modes  
+
+BigDecimal supports various rounding modes for precise control over calculations.  
+
+```java
+import java.math.BigDecimal;
+import java.math.RoundingMode;
+
+void main() {
+
+    var value = new BigDecimal("2.5");
+
+    IO.println("UP: " + value.setScale(0, RoundingMode.UP));
+    IO.println("DOWN: " + value.setScale(0, RoundingMode.DOWN));
+    IO.println("CEILING: " + value.setScale(0, RoundingMode.CEILING));
+    IO.println("FLOOR: " + value.setScale(0, RoundingMode.FLOOR));
+    IO.println("HALF_UP: " + value.setScale(0, RoundingMode.HALF_UP));
+    IO.println("HALF_DOWN: " + value.setScale(0, RoundingMode.HALF_DOWN));
+    IO.println("HALF_EVEN: " + value.setScale(0, RoundingMode.HALF_EVEN));
+
+    var negative = new BigDecimal("-2.5");
+    IO.println("Negative HALF_UP: " + negative.setScale(0, RoundingMode.HALF_UP));
+}
+```
+
+`HALF_EVEN` (banker's rounding) minimizes cumulative rounding error over many  
+operations by rounding to the nearest even number when equidistant. This is the  
+default in IEEE 754 and is recommended for statistical or financial aggregations.  
+
+
+## BigDecimal division  
+
+Division with BigDecimal requires specifying scale and rounding mode to handle  
+non-terminating decimals.  
+
+```java
+import java.math.BigDecimal;
+import java.math.RoundingMode;
+
+void main() {
+
+    var a = new BigDecimal("10");
+    var b = new BigDecimal("3");
+
+    try {
+        var result = a.divide(b);
+    } catch (ArithmeticException e) {
+        IO.println("Exception without scale: " + e.getMessage());
+    }
+
+    var result = a.divide(b, 10, RoundingMode.HALF_UP);
+    IO.println("10 / 3 with 10 decimal places: " + result);
+
+    var exact = new BigDecimal("10").divide(new BigDecimal("4"));
+    IO.println("Exact division 10/4: " + exact);
+}
+```
+
+Division can produce non-terminating decimals (like 10/3), which cannot be  
+represented exactly. Without specifying scale and rounding mode, BigDecimal  
+throws ArithmeticException. Always specify these for division unless you know  
+the result terminates.  
+
+
+## Financial calculation example  
+
+Proper handling of currency calculations using BigDecimal.  
+
+```java
+import java.math.BigDecimal;
+import java.math.RoundingMode;
+
+void main() {
+
+    var price = new BigDecimal("19.99");
+    var quantity = new BigDecimal("3");
+    var taxRate = new BigDecimal("0.0825");
+
+    var subtotal = price.multiply(quantity);
+    var tax = subtotal.multiply(taxRate).setScale(2, RoundingMode.HALF_UP);
+    var total = subtotal.add(tax);
+
+    IO.println("Price: $" + price);
+    IO.println("Quantity: " + quantity);
+    IO.println("Subtotal: $" + subtotal);
+    IO.println("Tax (8.25%): $" + tax);
+    IO.println("Total: $" + total);
+
+    double dPrice = 19.99;
+    double dTotal = dPrice * 3 * 1.0825;
+    IO.println("Double calculation: $" + dTotal);
+}
+```
+
+Financial applications must use BigDecimal to ensure accuracy. Even small  
+rounding errors can accumulate to significant discrepancies in large  
+transactions or many operations. Most financial regulations require specific  
+rounding behavior that only BigDecimal can guarantee.  
+
+
+## Math.round and rounding  
+
+Java's built-in rounding functions provide convenient but limited options.  
+
+```java
+void main() {
+
+    double value = 2.5;
+    IO.println("Math.round(2.5): " + Math.round(value));
+    IO.println("Math.round(-2.5): " + Math.round(-2.5));
+
+    IO.println("Math.floor(2.7): " + Math.floor(2.7));
+    IO.println("Math.ceil(2.3): " + Math.ceil(2.3));
+
+    double precise = 2.555;
+    IO.println("Math.round(2.555 * 100) / 100.0: " + 
+               Math.round(precise * 100) / 100.0);
+}
+```
+
+`Math.round` uses round-half-up for positive numbers but round-half-down for  
+negative numbers (towards positive infinity). The multiply-round-divide pattern  
+for rounding to decimal places can introduce additional errors. For precise  
+rounding, use BigDecimal.  
+
+
+## DecimalFormat for display  
+
+DecimalFormat controls how floating-point numbers are displayed without changing  
+their value.  
+
+```java
+import java.text.DecimalFormat;
+
+void main() {
+
+    double value = 1234567.89123;
+
+    var df1 = new DecimalFormat("#,###.##");
+    var df2 = new DecimalFormat("0.000");
+    var df3 = new DecimalFormat("$#,###.00");
+    var df4 = new DecimalFormat("0.###E0");
+
+    IO.println("Pattern #,###.##: " + df1.format(value));
+    IO.println("Pattern 0.000: " + df2.format(value));
+    IO.println("Pattern $#,###.00: " + df3.format(value));
+    IO.println("Scientific: " + df4.format(value));
+}
+```
+
+DecimalFormat is for display purposes only—it formats a number into a string  
+for output. It does not perform precise calculations. Use BigDecimal for  
+calculations and DecimalFormat only for final output formatting.  
+
+
+## Mixing int and double  
+
+Type promotion when mixing integer and floating-point types can cause surprises.  
+
+```java
+void main() {
+
+    int a = 7;
+    int b = 3;
+
+    double result1 = a / b;
+    double result2 = (double) a / b;
+    double result3 = a / (double) b;
+    double result4 = (double) (a / b);
+
+    IO.println("a / b (int division): " + result1);
+    IO.println("(double) a / b: " + result2);
+    IO.println("a / (double) b: " + result3);
+    IO.println("(double) (a / b): " + result4);
+}
+```
+
+Integer division occurs before type conversion if both operands are integers.  
+`7 / 3` equals `2` as integer division, then converts to `2.0`. Cast at least  
+one operand to double before division to get floating-point division.  
+
+
+## Float to double conversion  
+
+Converting between float and double can introduce unexpected precision.  
+
+```java
+void main() {
+
+    float f = 0.1f;
+    double d = f;
+
+    IO.println("float 0.1f: " + f);
+    IO.println("Promoted to double: " + d);
+    IO.println("With precision: " + String.format("%.20f", d));
+
+    double exact = 0.1;
+    IO.println("Double 0.1: " + String.format("%.20f", exact));
+    IO.println("Are they equal? " + (d == exact));
+}
+```
+
+When a float is widened to double, the exact bit pattern is preserved and  
+extended with zeros. This reveals the actual value stored in the float, which  
+differs from the double representation of the same decimal. This can cause  
+comparison failures.  
+
+
+## StrictMath vs Math  
+
+StrictMath guarantees identical results across platforms at potential  
+performance cost.  
+
+```java
+void main() {
+
+    double value = 0.5;
+
+    IO.println("Math.sin: " + Math.sin(value));
+    IO.println("StrictMath.sin: " + StrictMath.sin(value));
+
+    IO.println("Math.exp: " + Math.exp(value));
+    IO.println("StrictMath.exp: " + StrictMath.exp(value));
+
+    IO.println("Math.pow(2, 10): " + Math.pow(2, 10));
+    IO.println("StrictMath.pow(2, 10): " + StrictMath.pow(2, 10));
+}
+```
+
+Math methods may use platform-specific optimizations that produce slightly  
+different results on different CPUs or JVMs. StrictMath uses software  
+implementations that guarantee bit-identical results everywhere. Use StrictMath  
+when reproducibility across platforms is required.  
+
+
+## strictfp modifier  
+
+The `strictfp` modifier ensures strict floating-point semantics for a class or  
+method.  
+
+```java
+strictfp class StrictCalculation {
+    static double calculate(double a, double b) {
+        return a * b + a / b;
+    }
+}
+
+void main() {
+
+    double result = StrictCalculation.calculate(1e308, 1e-308);
+    IO.println("Strict result: " + result);
+
+    IO.println("Note: Since Java 17, all floating-point operations");
+    IO.println("are strictfp by default (JEP 306)");
+}
+```
+
+Before Java 17, floating-point operations could use extended precision on some  
+platforms, leading to different results. JEP 306 made strictfp the default,  
+so modern Java code always uses strict IEEE 754 semantics. The modifier is  
+now effectively a no-op but retained for source compatibility.  
+
+
+## Comparing wrapper objects  
+
+Comparing Float and Double objects has additional pitfalls beyond primitive  
+comparison.  
+
+```java
+void main() {
+
+    Double a = 0.1 + 0.2;
+    Double b = 0.3;
+
+    IO.println("a.equals(b): " + a.equals(b));
+    IO.println("a == b: " + (a == b));
+
+    Double c = 1.0;
+    Double d = 1.0;
+    IO.println("1.0 == 1.0 (objects): " + (c == d));
+
+    Double nanA = Double.NaN;
+    Double nanB = Double.NaN;
+    IO.println("NaN.equals(NaN): " + nanA.equals(nanB));
+    IO.println("NaN == NaN (objects): " + (nanA == nanB));
+}
+```
+
+Object `==` compares references, not values. `equals` compares values but still  
+uses exact comparison. Unlike primitive NaN, wrapper NaN objects can be reference  
+equal if cached, and `equals` returns true for two NaN wrappers—contrary to  
+primitive behavior.  
+
+
+## Parsing floating-point strings  
+
+Converting strings to floating-point numbers requires handling parse errors and  
+locale issues.  
+
+```java
+void main() {
+
+    IO.println("Parse '3.14': " + Double.parseDouble("3.14"));
+    IO.println("Parse '-1.5e10': " + Double.parseDouble("-1.5e10"));
+    IO.println("Parse 'NaN': " + Double.parseDouble("NaN"));
+    IO.println("Parse 'Infinity': " + Double.parseDouble("Infinity"));
+
+    try {
+        Double.parseDouble("3,14");
+    } catch (NumberFormatException e) {
+        IO.println("Cannot parse '3,14' (European format)");
+    }
+
+    IO.println("valueOf: " + Double.valueOf("123.456"));
+}
+```
+
+`parseDouble` and `valueOf` use US locale conventions (period as decimal  
+separator). For locale-sensitive parsing, use `NumberFormat`. Scientific  
+notation, NaN, and Infinity strings are all valid inputs. Invalid strings throw  
+NumberFormatException.  
+
+
+## Binary representation  
+
+Examining the actual binary representation of floating-point numbers.  
+
+```java
+void main() {
+
+    double value = 0.1;
+    long bits = Double.doubleToLongBits(value);
+
+    IO.println("Value: " + value);
+    IO.println("Bits (hex): " + Long.toHexString(bits));
+    IO.println("Bits (binary): " + Long.toBinaryString(bits));
+
+    long sign = (bits >> 63) & 1;
+    long exponent = (bits >> 52) & 0x7FF;
+    long mantissa = bits & 0xFFFFFFFFFFFFFL;
+
+    IO.println("Sign: " + sign);
+    IO.println("Exponent: " + exponent + " (biased), " + (exponent - 1023) + " (actual)");
+    IO.println("Mantissa: " + Long.toBinaryString(mantissa));
+
+    double reconstructed = Double.longBitsToDouble(bits);
+    IO.println("Reconstructed: " + reconstructed);
+}
+```
+
+`doubleToLongBits` reveals the actual IEEE 754 representation. The exponent is  
+stored with a bias of 1023 for doubles. Understanding the binary representation  
+helps explain why certain decimal values cannot be represented exactly and how  
+precision decreases with magnitude.  
+
+
+## Next representable values  
+
+Finding adjacent floating-point values reveals the discrete nature of the  
+representation.  
+
+```java
+void main() {
+
+    double value = 1.0;
+    double next = Math.nextUp(value);
+    double prev = Math.nextDown(value);
+
+    IO.println("Value: " + value);
+    IO.println("Next representable: " + next);
+    IO.println("Previous representable: " + prev);
+    IO.println("Gap up: " + (next - value));
+    IO.println("Gap down: " + (value - prev));
+
+    double large = 1e15;
+    IO.println("Gap at 1e15: " + (Math.nextUp(large) - large));
+
+    double small = 1e-10;
+    IO.println("Gap at 1e-10: " + (Math.nextUp(small) - small));
+}
+```
+
+The gap between representable values increases with magnitude. Near 1.0, the gap  
+is about 2.2e-16. Near 1e15, the gap is about 0.125—meaning values cannot be  
+represented with sub-integer precision at that magnitude. This explains why  
+precision decreases for larger numbers.  
+
+
+## Subnormal numbers  
+
+Subnormal (denormalized) numbers allow gradual underflow at the cost of  
+precision.  
+
+```java
+void main() {
+
+    double normal = Double.MIN_NORMAL;
+    double subnormal = normal / 2;
+
+    IO.println("MIN_NORMAL: " + normal);
+    IO.println("Half of MIN_NORMAL: " + subnormal);
+    IO.println("Is subnormal: " + (subnormal < Double.MIN_NORMAL && subnormal > 0));
+
+    double tiny = Double.MIN_VALUE;
+    IO.println("MIN_VALUE (smallest subnormal): " + tiny);
+    IO.println("MIN_VALUE / 2: " + (tiny / 2));
+
+    IO.println("Subnormal range: [" + Double.MIN_VALUE + ", " + Double.MIN_NORMAL + ")");
+}
+```
+
+Subnormal numbers have reduced precision because the leading "1" bit is no  
+longer implicit. They fill the gap between zero and the smallest normal number,  
+preventing abrupt underflow to zero. However, operations with subnormals can be  
+significantly slower on some hardware.  
+
+
+## Fused multiply-add  
+
+FMA performs multiply-add with a single rounding, improving accuracy and  
+performance.  
+
+```java
+void main() {
+
+    double a = 1.0 + 1e-15;
+    double b = 1.0 - 1e-15;
+    double c = -1.0;
+
+    double standard = a * b + c;
+    double fma = Math.fma(a, b, c);
+
+    IO.println("a * b + c (standard): " + standard);
+    IO.println("Math.fma(a, b, c): " + fma);
+    IO.println("Expected: " + (1e-30));
+
+    double x = 0.1;
+    double y = 10.0;
+    double z = -1.0;
+    IO.println("Standard: " + (x * y + z));
+    IO.println("FMA: " + Math.fma(x, y, z));
+}
+```
+
+FMA computes `a * b + c` with only one rounding at the end instead of two  
+(one for multiplication, one for addition). This can provide better accuracy for  
+certain numerical algorithms. Modern CPUs have hardware FMA instructions, making  
+it efficient as well.  
+
+
+## Performance comparison: double vs BigDecimal  
+
+BigDecimal is significantly slower than primitive double for arithmetic.  
+
+```java
+import java.math.BigDecimal;
+import java.math.MathContext;
+
+void main() {
+
+    int iterations = 1_000_000;
+
+    long startDouble = System.nanoTime();
+    double sumDouble = 0.0;
+    for (int i = 0; i < iterations; i++) {
+        sumDouble += 0.1;
+        sumDouble *= 1.001;
+    }
+    long doubleTime = System.nanoTime() - startDouble;
+
+    long startBigDecimal = System.nanoTime();
+    var sumBD = BigDecimal.ZERO;
+    var increment = new BigDecimal("0.1");
+    var multiplier = new BigDecimal("1.001");
+    for (int i = 0; i < iterations; i++) {
+        sumBD = sumBD.add(increment);
+        sumBD = sumBD.multiply(multiplier, MathContext.DECIMAL64);
+    }
+    long bdTime = System.nanoTime() - startBigDecimal;
+
+    IO.println("Double time: " + (doubleTime / 1_000_000) + " ms");
+    IO.println("BigDecimal time: " + (bdTime / 1_000_000) + " ms");
+    IO.println("Ratio: " + (bdTime / doubleTime) + "x slower");
+}
+```
+
+BigDecimal can be 10-100x slower than primitive double operations. For  
+performance-critical numerical computations like graphics or physics, use  
+double. Reserve BigDecimal for scenarios where exact decimal arithmetic is  
+required, such as financial calculations.  
+
+
+## Floating-point in loops  
+
+Using floating-point numbers as loop counters can cause unexpected behavior.  
+
+```java
+void main() {
+
+    int count1 = 0;
+    for (double d = 0.0; d < 1.0; d += 0.1) {
+        count1++;
+    }
+    IO.println("Loop with d += 0.1: " + count1 + " iterations");
+
+    int count2 = 0;
+    for (double d = 0.0; d <= 1.0; d += 0.1) {
+        count2++;
+    }
+    IO.println("Loop with d <= 1.0: " + count2 + " iterations");
+
+    IO.println("Better approach:");
+    int count3 = 0;
+    for (int i = 0; i < 10; i++) {
+        double d = i * 0.1;
+        count3++;
+    }
+    IO.println("Integer loop counter: " + count3 + " iterations");
+}
+```
+
+Accumulated rounding errors in loop counters can cause off-by-one errors or  
+even infinite loops. The last iteration may or may not execute depending on  
+accumulated error. Use integer loop counters and calculate the floating-point  
+value from the integer when needed.  
+
+
+## Floating-point in HashMap keys  
+
+Using Float or Double as HashMap keys is problematic due to comparison issues.  
+
+```java
+void main() {
+
+    var map = new HashMap<Double, String>();
+
+    map.put(0.1 + 0.2, "calculated");
+    map.put(0.3, "literal");
+
+    IO.println("Map size: " + map.size());
+    IO.println("Get 0.3: " + map.get(0.3));
+    IO.println("Get 0.1+0.2: " + map.get(0.1 + 0.2));
+
+    IO.println("Keys: " + map.keySet());
+
+    Map<Double, String> nanMap = new HashMap<>();
+    nanMap.put(Double.NaN, "NaN value");
+    IO.println("Get NaN: " + nanMap.get(Double.NaN));
+}
+```
+
+`0.1 + 0.2` and `0.3` have different hash codes because they are not equal.  
+This results in two separate entries. NaN keys work because Double.equals treats  
+all NaNs as equal, contrary to primitive comparison. Avoid using floating-point  
+values as map keys unless you understand these implications.  
+
+
+## Floating-point in switch  
+
+Floating-point values cannot be used in switch statements, requiring alternatives.  
+
+```java
+void main() {
+
+    double value = 1.5;
+
+    if (Math.abs(value - 1.0) < 0.01) {
+        IO.println("Approximately one");
+    } else if (Math.abs(value - 1.5) < 0.01) {
+        IO.println("Approximately one and a half");
+    } else if (Math.abs(value - 2.0) < 0.01) {
+        IO.println("Approximately two");
+    }
+
+    int scaled = (int) Math.round(value * 2);
+    String result = switch (scaled) {
+        case 2 -> "One";
+        case 3 -> "One and a half";
+        case 4 -> "Two";
+        default -> "Other";
+    };
+    IO.println("Switch result: " + result);
+}
+```
+
+Java prohibits float and double in switch statements because exact equality  
+comparison is unreliable. Use if-else with epsilon comparison, or scale to  
+integers if appropriate. The integer scaling approach works when the floating-  
+point values represent discrete choices.  
+
+
+## Arrays and floating-point  
+
+Working with arrays of floating-point numbers has performance considerations.  
+
+```java
+void main() {
+
+    double[] prices = {19.99, 29.99, 9.99, 49.99, 14.99};
+
+    double sum = 0;
+    for (double price : prices) {
+        sum += price;
+    }
+    IO.println("Sum (loop): " + sum);
+
+    double streamSum = java.util.Arrays.stream(prices).sum();
+    IO.println("Sum (stream): " + streamSum);
+
+    double average = java.util.Arrays.stream(prices).average().orElse(0);
+    IO.println("Average: " + average);
+
+    double max = java.util.Arrays.stream(prices).max().orElse(0);
+    IO.println("Maximum: " + max);
+
+    java.util.Arrays.sort(prices);
+    IO.println("Sorted: " + java.util.Arrays.toString(prices));
+}
+```
+
+Primitive double arrays are more memory-efficient than Double object arrays.  
+Stream operations on double arrays use DoubleStream which avoids boxing  
+overhead. For large numerical computations, primitive arrays significantly  
+outperform collections of wrapper objects.  
+
+
+## Statistical accuracy considerations  
+
+Computing statistical measures requires attention to numerical stability.  
+
+```java
+void main() {
+
+    double[] data = {1e9, 1, 2, 3, 4, 5, 6, 7, 8, 9};
+
+    double sum = 0;
+    for (double d : data) {
+        sum += d;
+    }
+    double mean = sum / data.length;
+
+    double varianceSum = 0;
+    for (double d : data) {
+        varianceSum += (d - mean) * (d - mean);
+    }
+    double variance = varianceSum / data.length;
+
+    IO.println("Mean: " + mean);
+    IO.println("Variance: " + variance);
+
+    double[] normalized = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
+    sum = 0;
+    for (double d : normalized) sum += d;
+    mean = sum / normalized.length;
+    varianceSum = 0;
+    for (double d : normalized) varianceSum += (d - mean) * (d - mean);
+    IO.println("Normalized variance: " + (varianceSum / normalized.length));
+}
+```
+
+When data values vary widely in magnitude, subtracting the mean can cause loss  
+of significance. For more accurate variance calculation, use Welford's online  
+algorithm or other numerically stable methods. Libraries like Apache Commons  
+Math provide robust statistical functions.  
+
+
+## Random floating-point numbers  
+
+Random number generation with floating-point has its own characteristics.  
+
+```java
+import java.util.Random;
+
+void main() {
+
+    var random = new Random(42);
+
+    IO.println("Random doubles [0, 1):");
+    for (int i = 0; i < 5; i++) {
+        IO.println("  " + random.nextDouble());
+    }
+
+    IO.println("Random in range [10, 20):");
+    for (int i = 0; i < 5; i++) {
+        double value = 10 + random.nextDouble() * 10;
+        IO.println("  " + value);
+    }
+
+    IO.println("Gaussian distribution:");
+    for (int i = 0; i < 5; i++) {
+        IO.println("  " + random.nextGaussian());
+    }
+}
+```
+
+`nextDouble` returns values in [0, 1) with uniform distribution. The range is  
+half-open: it includes 0 but excludes 1. Random floating-point values still  
+have the same representation limitations as other floating-point numbers—not  
+all values in the range are equally likely to appear.  
+
+
+## Guidelines for choosing float, double, or BigDecimal  
+
+Selecting the appropriate type depends on the use case requirements.  
+
+```java
+import java.math.BigDecimal;
+import java.math.RoundingMode;
+
+void main() {
+
+    IO.println("=== Use float for: ===");
+    IO.println("- Graphics (GPU APIs often use float)");
+    IO.println("- Large arrays where memory matters");
+    float[] vertices = {1.0f, 2.0f, 3.0f};
+    IO.println("Vertex example: " + vertices[0]);
+
+    IO.println("\n=== Use double for: ===");
+    IO.println("- General scientific computing");
+    IO.println("- Physics simulations");
+    IO.println("- Most decimal calculations");
+    double gravity = 9.80665;
+    IO.println("Gravity: " + gravity + " m/s²");
+
+    IO.println("\n=== Use BigDecimal for: ===");
+    IO.println("- Financial calculations");
+    IO.println("- When exact decimal representation is required");
+    IO.println("- When specific rounding modes matter");
+    var price = new BigDecimal("99.99");
+    var tax = price.multiply(new BigDecimal("0.08")).setScale(2, RoundingMode.HALF_UP);
+    IO.println("Tax on $99.99 at 8%: $" + tax);
+}
+```
+
+Float saves memory but has limited precision—use only when necessary. Double is  
+the default choice for most numerical work, offering good precision and  
+performance. BigDecimal is essential when exact decimal arithmetic matters, such  
+as in financial software, despite its performance cost.  
+
+
+## Summary and Best Practices  
+
+Key guidelines for robust floating-point programming in Java:  
+
+| Situation | Recommendation |  
+|-----------|----------------|  
+| Financial calculations | Always use `BigDecimal` with String constructor |  
+| Equality comparison | Use epsilon or ULP-based comparison |  
+| Loop counters | Use integers, compute float from index |  
+| HashMap keys | Avoid float/double, or normalize values |  
+| Scientific computing | Use double, consider numerical stability |  
+| Graphics/GPU | Use float for memory and API compatibility |  
+| Cross-platform consistency | Use StrictMath or strictfp (pre-Java 17) |  
+| Accumulating sums | Consider Kahan summation or BigDecimal |  
+| Display formatting | Use DecimalFormat, not for calculations |  
+| Parsing user input | Handle NumberFormatException, validate result |  
+
+Understanding floating-point limitations prevents subtle bugs. The IEEE 754  
+representation cannot exactly represent most decimal fractions, leading to  
+precision issues that accumulate through calculations. Choosing the right type  
+and comparison method for each use case ensures both correctness and performance.  
+
+Always validate floating-point inputs for NaN and infinity. Be aware of the  
+magnitude of your values—precision decreases as magnitude increases. When exact  
+decimal arithmetic is required, accept the performance cost of BigDecimal rather  
+than trying to work around floating-point limitations.  
diff --git a/fork-join-pool.md b/fork-join-pool.md
new file mode 100644
index 00000000..e69de29b
diff --git a/fun-streams/collect/README.md b/fun-streams/collect/README.md
new file mode 100644
index 00000000..ac24e7fe
--- /dev/null
+++ b/fun-streams/collect/README.md
@@ -0,0 +1,195 @@
+# Collectors
+
+
+## Creating list of Integers with streams 
+
+```java
+void main() {
+
+    List<Integer> nums1 = IntStream.range(1, 4).boxed().toList();
+    List<Integer> nums2 = IntStream.range(1, 4)
+            .collect(ArrayList::new, List::add, List::addAll);
+    List<Integer> nums3 = Stream.iterate(1, x -> x + 1).limit(3).toList();
+    List<Integer> nums4 = Stream.of(1, 2, 3).toList();
+
+
+    System.out.println(nums1);
+    System.out.println(nums2);
+    System.out.println(nums3);
+    System.out.println(nums4);
+}
+```
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+The `Collector.of` method in Java's `java.util.stream.Collector` class is a factory method used to create a custom `Collector` for use in stream operations. It allows you to define how a stream's elements are collected into a final result by specifying the key components of the collection process.
+
+### Definition
+The `Collector.of` method has the following signatures in the Java Stream API:
+
+1. **Basic Form**:
+   ```java
+   public static <T, A, R> Collector<T, A, R> of(
+       Supplier<A> supplier,
+       BiConsumer<A, T> accumulator,
+       BinaryOperator<A> combiner,
+       Function<A, R> finisher,
+       Collector.Characteristics... characteristics)
+   ```
+   - **`<T>`**: The type of input elements in the stream.
+   - **`<A>`**: The mutable accumulation type (intermediate container).
+   - **`<R>`**: The final result type.
+   - **Parameters**:
+     - `supplier`: A function that creates a new mutable container (e.g., `StringBuilder::new`).
+     - `accumulator`: A function that incorporates a stream element into the mutable container (e.g., `StringBuilder::append`).
+     - `combiner`: A function that merges two containers, used in parallel streams (e.g., `(sb1, sb2) -> sb1.append(sb2)`).
+     - `finisher`: A function that transforms the intermediate container into the final result (e.g., `StringBuilder::toString`).
+     - `characteristics`: Optional `Collector.Characteristics` (e.g., `CONCURRENT`, `UNORDERED`, `IDENTITY_FINISH`) that describe the collector's behavior.
+   - **Returns**: A `Collector` instance that can be used with `Stream.collect()`.
+
+2. **Simplified Form (Identity Finisher)**:
+   ```java
+   public static <T, R> Collector<T, R, R> of(
+       Supplier<R> supplier,
+       BiConsumer<R, T> accumulator,
+       BinaryOperator<R> combiner,
+       Collector.Characteristics... characteristics)
+   ```
+   - This version is used when the intermediate container is the same as the final result type (i.e., no finisher transformation is needed).
+   - The `finisher` is implicitly the identity function (`x -> x`).
+   - **Parameters** and **returns** are similar to the first form, but `<A>` and `<R>` are the same type.
+
+### Purpose
+`Collector.of` is used to create custom collectors when the built-in collectors (e.g., `Collectors.toList()`, `Collectors.joining()`) are insufficient for specific use cases. It provides fine-grained control over the collection process, allowing you to define how elements are accumulated, combined, and finalized.
+
+### Example Usage
+From your previous example:
+```java
+Collector<String, StringBuilder, String> stringCollector =
+    Collector.of(
+        StringBuilder::new,             // Supplier: Creates a new StringBuilder
+        StringBuilder::append,          // Accumulator: Appends each string
+        StringBuilder::append,          // Combiner: Merges two StringBuilders
+        StringBuilder::toString         // Finisher: Converts StringBuilder to String
+    );
+```
+
+### Characteristics
+You can specify `Collector.Characteristics` to optimize the collector:
+- `CONCURRENT`: Indicates the collector can handle concurrent accumulation (e.g., for parallel streams).
+- `UNORDERED`: Indicates the result is not dependent on the order of elements.
+- `IDENTITY_FINISH`: Indicates the finisher is the identity function (no transformation needed).
+
+If no characteristics apply, pass an empty array (`new Collector.Characteristics[]{}`).
+
+### Notes
+- The collector created by `Collector.of` is used with `Stream.collect()` to process stream elements.
+- It is particularly useful for custom aggregations, such as building specialized data structures or performing complex reductions.
+- Ensure the supplier, accumulator, combiner, and finisher are thread-safe if `CONCURRENT` is specified or if used in parallel streams.
+
+Let me know if you need further clarification or additional examples!
+
+## Collector.of
+
+## Concatenating list
+
+```java
+import java.util.List;
+import java.util.stream.Collector;
+
+void main() {
+    List<String> words = List.of("Apple", "Banana", "Cherry");
+
+    Collector<String, StringBuilder, String> delimitedCollector =
+        Collector.of(
+            StringBuilder::new,                    // Supplier
+            (sb, word) -> sb.append(word).append(", "), // Accumulator
+            StringBuilder::append,                 // Combiner
+            sb -> sb.length() > 0 
+                ? sb.substring(0, sb.length() - 2) // Remove trailing ", "
+                : sb.toString()                    // Finisher
+        );
+
+    String result = words.stream().collect(delimitedCollector);
+    System.out.println(result); // Output: Apple, Banana, Cherry
+}
+```
+
+### Counting chars
+
+```java
+void main() {
+    List<String> words = List.of("cat", "dog", "elephant");
+
+    Collector<String, Map<String, Integer>, Map<String, Integer>> charCountCollector =
+        Collector.of(
+            HashMap::new,                          // Supplier
+            (map, word) -> map.put(word, word.length()), // Accumulator
+            (map1, map2) -> {                      // Combiner
+                map1.putAll(map2);
+                return map1;
+            },
+            map -> map                             // Finisher (identity)
+        );
+
+    Map<String, Integer> result = words.stream().collect(charCountCollector);
+    System.out.println(result); // Output: {cat=3, dog=3, elephant=8}
+}
+```
+
+### Uppercasing letters
+
+```java
+void main() {
+
+    List<String> words = List.of("hello", "there", "java");
+
+    Collector<String, ArrayList<String>, List<String>> uppercaseCollector =
+        Collector.of(
+            ArrayList::new,                        // Supplier
+            (list, word) -> list.add(word.toUpperCase()), // Accumulator
+            (list1, list2) -> {                    // Combiner
+                list1.addAll(list2);
+                return list1;
+            },
+            list -> list                           // Finisher (identity)
+        );
+
+    List<String> result = words.stream().collect(uppercaseCollector);
+    System.out.println(result); // Output: [HELLO, WORLD, JAVA]
+}
+```
+
+### Counting chars
+
+```java
+
+void main() {
+    List<String> words = List.of("one", "two", "three");
+
+    Collector<String, int[], Integer> lengthSumCollector =
+        Collector.of(
+            () -> new int[]{0},                    // Supplier
+            (arr, word) -> arr[0] += word.length(), // Accumulator
+            (arr1, arr2) -> {                      // Combiner
+                arr1[0] += arr2[0];
+                return arr1;
+            },
+            arr -> arr[0]                          // Finisher
+        );
+
+    Integer result = words.stream().collect(lengthSumCollector);
+    System.out.println(result); // Output: 11 (3 + 3 + 5)
+}
+```
diff --git a/fun-streams/gatherers.md b/fun-streams/gatherers.md
new file mode 100644
index 00000000..4023900f
--- /dev/null
+++ b/fun-streams/gatherers.md
@@ -0,0 +1,380 @@
+# Gatherers
+
+
+## Type Parameters
+
+The `Gatherer<T, A, R>` interface in Java's Stream API (introduced in JDK 22) has three type parameters:  
+
+1. **`T`** – The type of input elements to the gather operation.  
+2. **`A`** – The type of the gatherer's private state object (often mutable),  
+   used to track previously seen elements or influence later transformations.  
+4. **`R`** – The type of output elements from the gather operation.  
+
+## Core Functions of a Gatherer
+
+A **Gatherer** is defined by four key functions:
+
+1. **Initializer (`initializer()`)** – Creates a new state object (`A`).  
+2. **Integrator (`integrator()`)** – Processes each input element (`T`) and optionally emits output (`R`).  
+3. **Combiner (`combiner()`)** – Merges two state objects (`A`) for parallel execution.  
+4. **Finisher (`finisher()`)** – Performs a final action when the stream ends.  
+
+
+**What Does `?` Mean in `Gatherer<String, ?, String>`?**
+
+- The wildcard `?` in `Gatherer<String, ?, String>` means **the intermediate state type is unspecified**.
+- This allows flexibility in defining the state used during the transformation process.
+- The state could be **mutable or immutable**, depending on the specific gatherer implementation.
+
+```java
+public class GathererExample {
+
+    public static void main(String[] args) {
+        var words = Stream.of("apple", "banana", "cherry", "date", "fig", "grape", "kiwi");
+
+        var gatherer = Gatherer.of(
+            () -> null, // No explicit state needed
+            Gatherer.Integrator.ofGreedy((state, element, downstream) -> {
+                if (element.length() > 4) { // Example filtering logic
+                    downstream.accept(element.toUpperCase());
+                }
+            })
+        );
+
+        var result = words.gather(gatherer).toList();
+        System.out.println(result);
+    }
+}
+```
+
+
+## Limit operation
+
+```java
+
+// Limit Gatherer
+<T> Gatherer<T, ?, T> limit(long limit) {
+    return Gatherer.ofSequential(
+            () -> new Object() {
+                long counter = 0L;
+            },
+            (counter, element, downstream) -> {
+                if (counter.counter >= limit) {
+                    return false;
+                } else {
+                    counter.counter++;
+                    return downstream.push(element);
+                }
+            });
+}
+
+void main() {
+
+    var stream = Stream.of(1, 2, 3, 4, 5);
+    var result = stream.gather(limit(3L)).toList();
+    System.out.println("result = " + result);
+}
+```
+
+## Gatherers.windowFixed
+
+```java
+void main() {
+
+    String text = """
+            Name      | price  | stock |
+            Product A |      3 | 2312  |
+            Product B |     12 | 120   |
+            Procuct C |     21 | 3450  |
+            Product D |     11 | 12300 |
+            """;
+
+    int res = Pattern.compile("\\d+")
+            .matcher(text)
+            .results()
+            .map(m -> Integer.parseInt(m.group()))
+            .gather(Gatherers.windowFixed(2))
+            .mapToInt(list -> list.get(0) * list.get(1))
+            .sum();
+
+    System.out.println(res);
+}
+```
+
+## Gatherers.windowFixed && Gatherers.fold
+
+```java
+void main() {
+
+    String text = """
+            Name      | price  | stock |
+            Product A |      3 | 2312  |
+            Product B |     12 | 120   |
+            Procuct C |     21 | 3450  |
+            Product D |     11 | 12300 |
+            """;
+
+    var pattern = Pattern.compile("\\d+");
+
+    var matcher = pattern.matcher(text);
+
+    int res = matcher.results().map(matchRes -> Integer.valueOf(matchRes.group()))
+            .gather(Gatherers.windowFixed(2))
+            .gather(Gatherers.fold(() -> 0, (product, list) -> product + (list.getFirst() * list.getLast())))
+            .findFirst().orElse(0);
+
+    System.out.println(res);
+}
+```
+
+
+## Distinct ignore case
+
+
+```java
+// Distinct Ignore Case Gatherer
+Gatherer<String, ?, String> distinctIgnoreCase() {
+
+    return Gatherer.ofSequential(
+            () -> new HashSet<String>(),
+            (set, element, downstream) -> {
+                if (set.add(element.toLowerCase())) {
+                    return downstream.push(element);
+                }
+                return true;
+            });
+}
+
+void main() {
+    var stream = Stream.of("one", "One", "ONE", "Two", "two", "tWo");
+    var result = stream.gather(distinctIgnoreCase()).toList();
+    System.out.println("result = " + result);
+}
+```
+
+
+
+
+
+## Running sum
+
+```java
+import java.util.List;
+import java.util.stream.Stream;
+
+
+void main() {
+    // Example 1: Gatherer to calculate running sum
+    List<Integer> runningSums = Stream.of(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
+            .gather(runningSumGatherer())
+            .toList();
+    System.out.println("Running Sums: " + runningSums);
+}
+
+Gatherer<Integer, int[], Integer> runningSumGatherer() {
+    return Gatherer.ofSequential(
+            () -> new int[] { 0 },
+            (state, element, downstream) -> {
+                state[0] += element;
+                downstream.push(state[0]);
+                return true;
+            },
+            Gatherer.defaultFinisher()
+    // (state, downstream) -> {}
+    );
+}
+```
+
+## Counting negs/pos
+
+```java
+import java.util.List;
+import java.util.stream.Gatherers;
+
+class Count {
+
+    private int positive;
+    private int negative;
+
+    public Count() {
+
+    }
+
+    public Count(int pos, int neg) {
+        this.positive = pos;
+        this.negative = neg;
+    }
+}
+
+void main() {
+
+    var numbers = List.of(1, -2, 3, -4, 5, -3, 4, -9, 8);
+
+    // Count positive and negative elements
+    var count = numbers.stream()
+            .gather(Gatherers.scan(Count::new, (c, elem) -> {
+                c.positive += elem > 0 ? 1 : 0;
+                c.negative += elem < 0 ? 1 : 0;
+                return c;
+            })).reduce((c1, c2) -> new Count(c1.positive + c2.positive, c1.negative + c2.negative)).get();
+
+    System.out.println("Positive Count: " + count.positive);
+    System.out.println("Negative Count: " + count.negative);
+}
+```
+
+## Creating a custom filter operation
+
+```java
+import java.util.stream.Gatherer;
+
+void main() {
+    List<Integer> evens = Stream.of(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
+            .gather(evenGatherer())
+            .toList();
+    System.out.println("Even Numbers: " + evens);
+}
+
+Gatherer<Integer, Void, Integer> evenGatherer() {
+    return Gatherer.ofSequential(
+            // () -> null,
+            Gatherer.defaultInitializer(),
+            integrator(),
+            // (_, element, downstream) -> {
+            //     if (element % 2 == 0)
+            //         downstream.push(element);
+            //     return true;
+            // },
+            Gatherer.defaultFinisher());
+}
+
+Gatherer.Integrator<Void, Integer, Integer> integrator() {
+    return Gatherer.Integrator.ofGreedy((_, element, downstream) -> {
+        if (element % 2 == 0) {
+            downstream.push(element);
+        }
+        return true; // Continue processing
+    });
+}
+```
+
+
+
+## Deduplicate consecutive elements
+
+```java
+import java.util.stream.Gatherer;
+import java.util.stream.Stream;
+
+class State {
+    String previous;
+}
+
+void main() {
+
+    Gatherer<String, State, String> deduplicate = Gatherer.ofSequential(
+            State::new, // Initial state (no previous element)
+            (state, element, downstream) -> {
+                if (state.previous == null || !state.previous.equals(element)) {
+                    downstream.push(element); // Push if different from previous
+                }
+                state.previous = element; // Update state to current element
+                return true; // Continue processing
+            },
+            Gatherer.defaultFinisher());
+
+    Stream<String> words = Stream.of("a", "a", "b", "b", "c", "a");
+    var result = words.gather(deduplicate).toList();
+    System.out.println(result); // Output: [a, b, c, a]
+}
+```
+
+## Running averages & parsing CSV
+
+```java
+public void stockPriceAnalysis() {
+    System.out.println("=== Stock Price Moving Average Analysis ===");
+
+    List<Double> stockPrices = List.of(
+            100.5, 102.3, 98.7, 105.2, 107.8, 103.4, 99.1, 101.6, 104.3, 108.9);
+
+    // Calculate 3-day moving average and track running total
+    var analysis = stockPrices.stream()
+            .gather(Gatherers.windowSliding(3))
+            .gather(Gatherers.scan(() -> new MovingAverageResult(0.0, 0.0),
+                    (acc, window) -> {
+                        double avg = window.stream().mapToDouble(Double::doubleValue).average().orElse(0.0);
+                        double runningTotal = acc.runningTotal() + avg;
+                        return new MovingAverageResult(avg, runningTotal);
+                    }))
+            .toList();
+
+    analysis.forEach(result -> System.out.printf("Moving Avg: %.2f, Cumulative: %.2f%n",
+            result.movingAverage(), result.runningTotal()));
+}
+
+record MovingAverageResult(double movingAverage, double runningTotal) {
+}
+
+void dataCleaningPipeline() {
+    System.out.println("\n=== Data Cleaning and Transformation Pipeline ===");
+
+    String csvData = """
+            ID,Name,Score,Category
+            1,Alice Johnson,85.5,A
+            2,,92.3,B
+            3,Bob Smith,-1,C
+            4,Carol Davis,78.9,A
+            5,David Wilson,105.2,B
+            6,,,-
+            7,Eve Brown,88.1,C
+            8,Frank Miller,67.4,A
+            """;
+
+    var lines = csvData.lines().skip(1); // Skip header
+
+    // Clean data: remove invalid entries, normalize scores, and group by category
+    var cleanedData = lines.map(line -> line.split(",")).filter(fields -> fields.length == 4)
+            .map(fields -> new StudentRecord(fields[0].trim(), fields[1].trim(), parseScore(fields[2].trim()),
+                    fields[3].trim()))
+            .filter(record -> !record.name().isEmpty() && record.score() >= 0 && record.score() <= 100
+                    && !record.category().equals("-"))
+            .gather(Gatherers.fold(() -> new HashMap<String, CategoryStats>(), (stats, record) -> {
+                stats.compute(record.category(), (key, existing) -> {
+                    if (existing == null) {
+                        return new CategoryStats(1, record.score(), record.score(), record.score());
+                    }
+                    return new CategoryStats(existing.count() + 1, existing.sum() + record.score(),
+                            Math.min(existing.min(), record.score()), Math.max(existing.max(), record.score()));
+                });
+                return stats;
+            })).findFirst().orElse(new HashMap<>());
+
+    cleanedData.entrySet().stream().sorted(Map.Entry.comparingByKey()).forEach(entry -> {
+        var category = entry.getKey();
+        var stats = entry.getValue();
+        double average = stats.sum() / stats.count();
+        System.out.printf("Category %s: Count=%d, Avg=%.1f, Min=%.1f, Max=%.1f%n", category, stats.count(), average,
+                stats.min(), stats.max());
+    });
+}
+
+record StudentRecord(String id, String name, double score, String category) {
+}
+
+record CategoryStats(int count, double sum, double min, double max) {
+}
+
+private static double parseScore(String scoreStr) {
+    try {
+        return Double.parseDouble(scoreStr);
+    } catch (NumberFormatException e) {
+        return -1; // Invalid score marker
+    }
+}
+
+void main() {
+    dataCleaningPipeline();
+    stockPriceAnalysis();
+}
+```
diff --git a/fun-streams/map.md b/fun-streams/map.md
new file mode 100644
index 00000000..c3956ec2
--- /dev/null
+++ b/fun-streams/map.md
@@ -0,0 +1,168 @@
+# The map & flatMap methods 
+
+## map & array
+
+```java
+import java.util.Arrays;
+import java.util.stream.IntStream;
+
+void main() {
+    var nums = IntStream.of(1, 2, 3, 4, 5, 6, 7, 8);
+    var squares = nums.map(e -> e * e).toArray();
+
+    System.out.println(Arrays.toString(squares));
+}
+```
+
+## map & random 
+
+```java
+import java.util.Random;
+import java.util.stream.Stream;
+
+void main() {
+
+    Stream.generate(new Random()::nextDouble)
+        .map(e -> (e * 100))
+        .mapToInt(Double::intValue)
+        .limit(5)
+        .forEach(System.out::println);
+}
+```
+
+## map & strings
+
+```java
+import java.util.stream.Stream;
+
+void main() {
+
+    var words = Stream.of("cardinal", "pen", "coin", "globe");
+    // words.map(e -> capitalize(e)).forEach(System.out::println);
+    words.map(this::capitalize).forEach(System.out::println);
+}
+
+String capitalize(String word) {
+
+    word = word.substring(0, 1).toUpperCase() + word.substring(1).toLowerCase();
+    return word;
+}
+```
+
+## map & CSV
+
+```java
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.stream.Collectors;
+
+
+void main() throws IOException {
+
+    var lines = Files.readAllLines(Path.of("numbers.csv"));
+    var vals = lines.stream().map(line -> Arrays.asList(line.split(",")))
+        .flatMap(Collection::stream)
+        .map(String::trim) 
+        .mapToInt(Integer::valueOf)
+        .boxed().collect(Collectors.toList());
+
+    System.out.println(vals);
+}
+```
+
+## map with record
+
+```java
+import java.util.Comparator;
+import java.util.List;
+import java.util.stream.Collectors;
+
+record User(String name, String occupation) {}
+
+void main() {
+
+    var users = List.of(new User("Peter", "programmer"),
+            new User("Jane", "accountant"), new User("Robert", "teacher"),
+            new User("Milan", "programmer"), new User("Jane", "designer"));
+
+    var userNames = users.stream().map(user -> user.name()).sorted()
+            .collect(Collectors.toList());
+    System.out.println(userNames);
+
+    var occupations = users.stream().map(user -> user.occupation())
+            .sorted(Comparator.reverseOrder()).distinct().collect(Collectors.toList());
+
+    System.out.println(occupations);
+}
+```
+
+## flatMap
+
+The `flatMap()` operation has the effect of applying a one-to-many transformation to the  
+elements of the stream, and then flattening the resulting elements into a new stream.  
+
+```java
+
+import java.util.List;
+import java.util.stream.Stream;
+
+
+record User(String name, String occupation, List<Address> addresses) {}
+record Address(String street, String city, String state) {}
+
+void main() {
+
+    // Use flatMap to transform User stream to a stream of Addresses
+    Stream<Address> allAddresses = getUsers().flatMap(user -> user.addresses().stream());
+
+    // You can further process the stream of addresses
+    allAddresses.forEach(address -> System.out.println(address));
+
+    System.out.println("---------------------------");
+
+    getUsers().map(user -> user.occupation()).forEach(System.out::println);
+}
+
+
+Stream<User> getUsers() {
+    User u1 = new User("John Doe", "gardener", List.of(
+        new Address("123 Main St", "Anytown", "CA"),
+        new Address("456 Elm St", "Springfield", "NY")
+    ));
+    User u2 = new User("Roger Roe", "driver", List.of(
+        new Address("15 Brown St", "Anytown", "CA"),
+        new Address("34 Sesame St", "Sunnyvale", "CA")
+    ));
+
+    return Stream.of(u1, u2);
+}
+```
+
+## Flattening
+
+```java
+import java.util.Collection;
+import java.util.List;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
+
+void main() {
+    
+    var vals1 = List.of(1, 2, 3);
+    var vals2 = List.of(4, 5, 6);
+    var vals3 = List.of(7, 8, 9);
+
+    var vals = Stream.of(vals1, vals2, vals3)
+            .collect(Collectors.toList());
+
+    System.out.println("Before flattening : " + vals);
+
+    var flattened = Stream.of(vals1, vals2, vals3).flatMap(Collection::stream)
+            .collect(Collectors.toList());
+
+    System.out.println("After flattening : " + flattened);
+}
+```
diff --git a/fun-streams/map/FlatMapEx.java b/fun-streams/map/FlatMapEx.java
deleted file mode 100644
index f96216fa..00000000
--- a/fun-streams/map/FlatMapEx.java
+++ /dev/null
@@ -1,26 +0,0 @@
-package com.zetcode;
-
-import java.util.Collection;
-import java.util.List;
-import java.util.stream.Collectors;
-import java.util.stream.Stream;
-
-public class FlatMapEx {
-
-    public static void main(String[] args) {
-
-        var vals1 = List.of(1, 2, 3);
-        var vals2 = List.of(4, 5, 6);
-        var vals3 = List.of(7, 8, 9);
-
-        var vals = Stream.of(vals1, vals2, vals3)
-                .collect(Collectors.toList());
-
-        System.out.println("Before flattening : " + vals);
-
-        var flattened = Stream.of(vals1, vals2, vals3).flatMap(Collection::stream)
-                .collect(Collectors.toList());
-
-        System.out.println("After flattening : " + flattened);
-   }
-}
diff --git a/fun-streams/map/JavaStreamMapEx.java b/fun-streams/map/JavaStreamMapEx.java
deleted file mode 100644
index 578b742c..00000000
--- a/fun-streams/map/JavaStreamMapEx.java
+++ /dev/null
@@ -1,16 +0,0 @@
-package com.zetcode;
-
-import java.util.Arrays;
-import java.util.stream.IntStream;
-
-public class JavaStreamMapEx {
-
-    public static void main(String[] args) {
-
-        var nums = IntStream.of(1, 2, 3, 4, 5, 6, 7, 8);
-
-        var squares = nums.map(e -> e * e).toArray();
-
-        System.out.println(Arrays.toString(squares));
-    }
-}
diff --git a/fun-streams/map/JavaStreamMapEx2.java b/fun-streams/map/JavaStreamMapEx2.java
deleted file mode 100644
index 7963d9c4..00000000
--- a/fun-streams/map/JavaStreamMapEx2.java
+++ /dev/null
@@ -1,16 +0,0 @@
-package com.zetcode;
-
-import java.util.Random;
-import java.util.stream.Stream;
-
-public class JavaStreamMapEx2 {
-
-    public static void main(String[] args) {
-
-        Stream.generate(new Random()::nextDouble)
-                .map(e -> (e * 100))
-                .mapToInt(Double::intValue)
-                .limit(5)
-                .forEach(System.out::println);
-    }
-}
diff --git a/fun-streams/map/JavaStreamMapEx3.java b/fun-streams/map/JavaStreamMapEx3.java
deleted file mode 100644
index 5ab4725c..00000000
--- a/fun-streams/map/JavaStreamMapEx3.java
+++ /dev/null
@@ -1,18 +0,0 @@
-package com.zetcode;
-
-import java.util.stream.Stream;
-
-public class JavaStreamMapEx3 {
-
-    public static void main(String[] args) {
-
-        var words = Stream.of("cardinal", "pen", "coin", "globe");
-        words.map(JavaStreamMapEx3::capitalize).forEach(System.out::println);
-    }
-
-    private static String capitalize(String word) {
-
-        word = word.substring(0, 1).toUpperCase() + word.substring(1).toLowerCase();
-        return word;
-    }
-}
diff --git a/fun-streams/map/JavaStreamMapEx4.java b/fun-streams/map/JavaStreamMapEx4.java
deleted file mode 100644
index 7a6adaa5..00000000
--- a/fun-streams/map/JavaStreamMapEx4.java
+++ /dev/null
@@ -1,22 +0,0 @@
-package com.zetcode;
-
-import java.io.IOException;
-import java.nio.file.Files;
-import java.nio.file.Path;
-import java.util.Arrays;
-import java.util.Collection;
-import java.util.stream.Collectors;
-
-public class JavaStreamMapEx4 {
-
-    public static void main(String[] args) throws IOException {
-
-        var lines = Files.readAllLines(Path.of("src/resources/numbers.csv"));
-
-        var vals = lines.stream().map(line-> Arrays.asList(line.split(",")))
-                .flatMap(Collection::stream).mapToInt(Integer::valueOf)
-                .boxed().collect(Collectors.toList());
-
-        System.out.println(vals);
-    }
-}
diff --git a/fun-streams/map/JavaStreamMapEx5.java b/fun-streams/map/JavaStreamMapEx5.java
deleted file mode 100644
index c0b02047..00000000
--- a/fun-streams/map/JavaStreamMapEx5.java
+++ /dev/null
@@ -1,24 +0,0 @@
-package com.zetcode;
-
-import java.util.Comparator;
-import java.util.List;
-import java.util.stream.Collectors;
-
-public class JavaStreamMapEx5 {
-
-    public static void main(String[] args) {
-
-        var users = List.of(new User("Peter", "programmer"),
-                new User("Jane", "accountant"), new User("Robert", "teacher"),
-                new User("Milan", "programmer"), new User("Jane", "designer"));
-
-        var userNames = users.stream().map(user -> user.getName()).sorted()
-                .collect(Collectors.toList());
-        System.out.println(userNames);
-
-        var occupations = users.stream().map(user -> user.getOccupation())
-                .sorted(Comparator.reverseOrder()).distinct().collect(Collectors.toList());
-
-        System.out.println(occupations);
-    }
-}
diff --git a/fun-streams/map/User.java b/fun-streams/map/User.java
deleted file mode 100644
index 6447318b..00000000
--- a/fun-streams/map/User.java
+++ /dev/null
@@ -1,28 +0,0 @@
-package com.zetcode;
-
-public class User {
-
-    private String name;
-    private String occupation;
-
-    public User(String name, String occupation) {
-        this.name = name;
-        this.occupation = occupation;
-    }
-
-    public String getName() {
-        return name;
-    }
-
-    public void setName(String name) {
-        this.name = name;
-    }
-
-    public String getOccupation() {
-        return occupation;
-    }
-
-    public void setOccupation(String occupation) {
-        this.occupation = occupation;
-    }
-}
diff --git a/fun-streams/reduce.md b/fun-streams/reduce.md
new file mode 100644
index 00000000..c8abbc2e
--- /dev/null
+++ b/fun-streams/reduce.md
@@ -0,0 +1,129 @@
+# The reduce operation
+
+## builtins
+
+The `sum` and `count` are built-int reduction operations
+
+```java
+import java.util.Arrays;
+
+void main() {
+
+    int vals[] = {2, 4, 6, 8, 10, 12, 14, 16};
+
+    int sum = Arrays.stream(vals).sum();
+    System.out.printf("The sum of values: %d%n", sum);
+
+    long n = Arrays.stream(vals).count();
+    System.out.printf("The number of values: %d%n", n);
+}
+```
+
+## reduce custom sum
+
+```java
+import java.util.List;
+import java.util.Optional;
+
+void main() {
+
+    List<Integer> nums = List.of(1, 2, 3, 4, 5);
+    Optional<Integer> res = nums.stream().reduce((a, b) -> a + b);
+    res.ifPresent(System.out::println);    
+
+    Optional<Integer> res3 = nums.stream().reduce(Integer::sum);
+    res3.ifPresent(System.out::println);  
+}
+```
+
+## couting chars
+
+```java
+import java.util.List;
+
+void main(String[] args) {
+
+    List<String> words = List.of("coin", "pet", "tennis", "sky");
+
+    int n = words.stream().map(String::length).reduce(0, (l1, l2) -> l1 + l2);
+    System.out.printf("The count of characters in the list: %d%n", n);
+}
+```
+
+## reduce & Optional
+
+```java
+import java.util.stream.IntStream;
+
+void main(String[] args) {
+    IntStream.range(1, 10).reduce((x, y) -> x + y).ifPresent(s -> System.out.println(s));
+    IntStream.range(1, 10).reduce(Integer::sum).ifPresent(s -> System.out.println(s));
+    IntStream.range(1, 10).reduce(MyUtils::add2Ints).ifPresent(s -> System.out.println(s));
+}
+
+
+class MyUtils {
+    public static int add2Ints(int num1, int num2) {
+        return num1 + num2;
+    }
+}
+```
+
+## max price
+
+```java
+import java.util.List;
+import java.util.Optional;
+
+
+void main(String[] args) {
+
+    List<Car> persons = List.of(Car.of("Skoda", 18544),
+            Car.of("Volvo", 22344),
+            Car.of("Fiat", 23650),
+            Car.of("Renault", 19700));
+
+    Optional<Car> car = persons.stream().reduce((c1, c2)
+            -> c1.price() > c2.price() ? c1 : c2);
+
+    car.ifPresent(System.out::println);
+}
+
+record Car(String name, int price) {
+
+    public static Car of(String name, int price) {
+        return new Car(name, price);
+    }
+}
+```
+
+## max age
+
+```java
+import java.time.LocalDate;
+import java.time.chrono.IsoChronology;
+import java.util.ArrayList;
+import java.util.List;
+
+void main() {
+        
+    List<User> users = new ArrayList<>();
+    users.add(new User("Frank", LocalDate.of(1979, 11, 23)));
+    users.add(new User("Peter", LocalDate.of(1985, 1, 18)));
+    users.add(new User("Lucy", LocalDate.of(2002, 5, 14)));
+    users.add(new User("Albert", LocalDate.of(1996, 8, 30)));
+    users.add(new User("Frank", LocalDate.of(1967, 10, 6)));
+    
+    int maxAge = users.stream().map(User::getAge)
+            .reduce(0, (a1, a2) -> a1 > a2 ? a1 : a2);
+    
+    System.out.printf("The oldest user's age: %s%n", maxAge);
+}
+
+record User(String name, LocalDate dob) {
+    public int getAge() {
+        return dob.until(IsoChronology.INSTANCE.dateNow())
+            .getYears();
+    }
+}
+```
diff --git a/fun-streams/reduce/Car.java b/fun-streams/reduce/Car.java
deleted file mode 100644
index 7d9bb7f4..00000000
--- a/fun-streams/reduce/Car.java
+++ /dev/null
@@ -1,26 +0,0 @@
-package com.zetcode;
-
-public class Car {
-
-    private final String name;
-    private final int price;
-
-    public Car(String name, int price) {
-
-        this.name = name;
-        this.price = price;
-    }
-
-    public int getPrice() {
-        return price;
-    }
-
-    @Override
-    public String toString() {
-        StringBuilder builder = new StringBuilder();
-        builder.append("Car{name=").append(name).append(", price=")
-                .append(price).append("}");
-
-        return builder.toString();
-    }
-}
diff --git a/fun-streams/reduce/JavaStreamReduceBuiltin.java b/fun-streams/reduce/JavaStreamReduceBuiltin.java
deleted file mode 100644
index f2c6cc0b..00000000
--- a/fun-streams/reduce/JavaStreamReduceBuiltin.java
+++ /dev/null
@@ -1,17 +0,0 @@
-package com.zetcode;
-
-import java.util.Arrays;
-
-public class JavaStreamReduceBuiltin {
-
-    public static void main(String[] args) {
-
-        int vals[] = {2, 4, 6, 8, 10, 12, 14, 16};
-
-        int sum = Arrays.stream(vals).sum();
-        System.out.printf("The sum of values: %d%n", sum);
-
-        long n = Arrays.stream(vals).count();
-        System.out.printf("The number of values: %d%n", n);
-    }
-}
diff --git a/fun-streams/reduce/JavaStreamReduceMaxAge.java b/fun-streams/reduce/JavaStreamReduceMaxAge.java
deleted file mode 100644
index 654142de..00000000
--- a/fun-streams/reduce/JavaStreamReduceMaxAge.java
+++ /dev/null
@@ -1,23 +0,0 @@
-package com.zetcode;
-
-import java.time.LocalDate;
-import java.util.ArrayList;
-import java.util.List;
-
-public class JavaStreamReduceMaxAge {
-    
-    public static void main(String[] args) {
-        
-        List<MyUser> users = new ArrayList<>();
-        users.add(new MyUser("Frank", LocalDate.of(1979, 11, 23)));
-        users.add(new MyUser("Peter", LocalDate.of(1985, 1, 18)));
-        users.add(new MyUser("Lucy", LocalDate.of(2002, 5, 14)));
-        users.add(new MyUser("Albert", LocalDate.of(1996, 8, 30)));
-        users.add(new MyUser("Frank", LocalDate.of(1967, 10, 6)));
-        
-        int maxAge = users.stream().mapToInt(MyUser::getAge)
-                .reduce(0, (a1, a2) -> a1 > a2 ? a1 : a2);
-        
-        System.out.printf("The oldest user's age: %s%n", maxAge);
-    }
-}
diff --git a/fun-streams/reduce/JavaStreamReduceNofCharacters.java b/fun-streams/reduce/JavaStreamReduceNofCharacters.java
deleted file mode 100644
index 670fce0d..00000000
--- a/fun-streams/reduce/JavaStreamReduceNofCharacters.java
+++ /dev/null
@@ -1,20 +0,0 @@
-package com.zetcode;
-
-import java.util.ArrayList;
-import java.util.List;
-
-public class JavaStreamReduceNofCharacters {
-    
-    public static void main(String[] args) {
-        
-        List<String> words = new ArrayList<>();
-        words.add("coin");
-        words.add("pet");
-        words.add("tennis");
-        words.add("sky");
-        
-        int n = words.stream().mapToInt(String::length).reduce(0, (l1, l2) -> l1 + l2);
-        
-        System.out.printf("The count of characters in the list: %d%n", n);
-    }
-}
diff --git a/fun-streams/reduce/JavaStreamReduceOptional.java b/fun-streams/reduce/JavaStreamReduceOptional.java
deleted file mode 100644
index e3dbe836..00000000
--- a/fun-streams/reduce/JavaStreamReduceOptional.java
+++ /dev/null
@@ -1,22 +0,0 @@
-package com.zetcode;
-
-import java.util.Arrays;
-import java.util.List;
-import java.util.Optional;
-
-public class JavaStreamReduceOptional {
-
-    public static void main(String[] args) {
-
-        List<Car> persons = Arrays.asList(new Car("Skoda", 18544),
-                new Car("Volvo", 22344),
-                new Car("Fiat", 23650),
-                new Car("Renault", 19700));
-
-        Optional<Car> car = persons.stream().reduce((c1, c2)
-                -> c1.getPrice() > c2.getPrice() ? c1 : c2);
-
-        car.ifPresent(System.out::println);
-    }
-
-}
diff --git a/fun-streams/reduce/JavaStreamReduceOptional2.java b/fun-streams/reduce/JavaStreamReduceOptional2.java
deleted file mode 100644
index cfcef950..00000000
--- a/fun-streams/reduce/JavaStreamReduceOptional2.java
+++ /dev/null
@@ -1,14 +0,0 @@
-package com.zetcode;
-
-import java.util.stream.IntStream;
-
-public class JavaStreamReduceOptional2 {
-
-    public static void main(String[] args) {
-
-        IntStream.range(1, 10).reduce((x, y) -> x + y).ifPresent(s -> System.out.println(s));
-        IntStream.range(1, 10).reduce(Integer::sum).ifPresent(s -> System.out.println(s));
-        IntStream.range(1, 10).reduce(MyUtils::add2Ints).ifPresent(s -> System.out.println(s));
-    }
-}
-
diff --git a/fun-streams/reduce/MyUser.java b/fun-streams/reduce/MyUser.java
deleted file mode 100644
index 8c49ba11..00000000
--- a/fun-streams/reduce/MyUser.java
+++ /dev/null
@@ -1,46 +0,0 @@
-package com.zetcode;
-
-import java.time.LocalDate;
-import java.time.chrono.IsoChronology;
-
-public class MyUser {
-
-    private String name;
-    private LocalDate dateOfBirth;
-
-    public MyUser(String name, LocalDate dateOfBirth) {
-        this.name = name;
-        this.dateOfBirth = dateOfBirth;
-    }
-
-    public String getName() {
-        return name;
-    }
-
-    public void setName(String name) {
-        this.name = name;
-    }
-
-    public LocalDate getDateOfBirth() {
-        return dateOfBirth;
-    }
-
-    public void setDateOfBirth(LocalDate dateOfBirth) {
-        this.dateOfBirth = dateOfBirth;
-    }
-
-    public int getAge() {
-        return dateOfBirth.until(IsoChronology.INSTANCE.dateNow())
-                .getYears();
-    }
-
-    @Override
-    public String toString() {
-
-        StringBuilder builder = new StringBuilder();
-        builder.append("User{name=").append(name).append(", dateOfBirth=")
-                .append(dateOfBirth).append("}");
-
-        return builder.toString();
-    }
-}
diff --git a/fun-streams/reduce/MyUtils.java b/fun-streams/reduce/MyUtils.java
deleted file mode 100644
index c7e7d011..00000000
--- a/fun-streams/reduce/MyUtils.java
+++ /dev/null
@@ -1,8 +0,0 @@
-package com.zetcode;
-
-public class MyUtils {
-
-    public static int add2Ints(int num1, int num2) {
-        return num1 + num2;
-    }
-}
diff --git a/functional/FunctionCompose.java b/functional/FunctionCompose.java
deleted file mode 100644
index 34ea73c9..00000000
--- a/functional/FunctionCompose.java
+++ /dev/null
@@ -1,19 +0,0 @@
-package com.zetcode;
-
-import java.util.function.Function;
-
-public class FunctionCompose {
-
-    public static void main(String[] args) {
-
-        Function<String, String> upperFun = (val) -> val.toUpperCase();
-
-        Function<String, String> reverseFun = (val) -> {
-
-            return new StringBuilder(val).reverse().toString();
-        };
-
-        var res = upperFun.compose(reverseFun).apply("falcon");
-        System.out.println(res);
-    }
-}
diff --git a/functional/FunctionEx.java b/functional/FunctionEx.java
deleted file mode 100644
index 9d507534..00000000
--- a/functional/FunctionEx.java
+++ /dev/null
@@ -1,28 +0,0 @@
-package com.zetcode;
-
-import java.util.List;
-import java.util.function.Function;
-
-// Represents a function that accepts one argument and produces a result.
-// <T> the type of the input to the function
-// <R> the type of the result of the function
-
-public class FunctionEx {
-
-    public static void main(String[] args) {
-
-        var vals = List.of(1, 2, 3, 4, 5);
-
-        Function<List<Integer>, Integer> sumList = FunctionEx::doSumList;
-
-        var mysum = sumList.apply(vals);
-        System.out.println(mysum);
-    }
-
-    private static Integer doSumList(List<Integer> vals) {
-
-        return vals.stream()
-                .mapToInt(Integer::intValue)
-                .sum();
-    }
-}
diff --git a/functional/FunctionEx2.java b/functional/FunctionEx2.java
deleted file mode 100644
index 4db1567a..00000000
--- a/functional/FunctionEx2.java
+++ /dev/null
@@ -1,15 +0,0 @@
-package com.zetcode;
-
-import java.util.function.Function;
-
-public class FunctionEx2 {
-
-    public static void main(String[] args) {
-
-        // String::toUpperCase
-        Function<String, String> upperFun = s -> s.toUpperCase();
-
-        var res = upperFun.apply("falcon");
-        System.out.println(res);
-    }
-}
diff --git a/functional/function.md b/functional/function.md
new file mode 100644
index 00000000..f619f928
--- /dev/null
+++ b/functional/function.md
@@ -0,0 +1,192 @@
+# The Function inteface
+
+```java
+package com.zetcode;
+
+import java.util.List;
+import java.util.function.Function;
+
+// Represents a function that accepts one argument and produces a result.
+// <T> the type of the input to the function
+// <R> the type of the result of the function
+
+public class FunctionEx {
+
+    public static void main(String[] args) {
+
+        var vals = List.of(1, 2, 3, 4, 5);
+
+        Function<List<Integer>, Integer> sumList = FunctionEx::doSumList;
+
+        var mysum = sumList.apply(vals);
+        System.out.println(mysum);
+    }
+
+    private static Integer doSumList(List<Integer> vals) {
+
+        return vals.stream()
+                .mapToInt(Integer::intValue)
+                .sum();
+    }
+}
+```
+
+## Calculating age
+
+```java
+import java.util.function.Function;
+import java.util.function.Consumer;
+import java.time.LocalDate;
+import java.time.Period;
+import java.util.List;
+
+Function<LocalDate, Integer> findAge = dob -> Period.between(dob,
+        LocalDate.now()).getYears();
+Consumer<User> action = u -> System.out.println(STR."\{u.name} is \{findAge.apply(u.dob)} years old");
+
+void main() {
+
+    List<User> users = List.of(
+            User.of("John Doe", "gardener", LocalDate.of(1956, 11, 12)),
+            User.of("Roger Roe", "driver", LocalDate.of(1976, 11, 12)),
+            User.of("John Doe", "teacher", LocalDate.of(1967, 1, 7)),
+            User.of("John Doe", "gardener", LocalDate.of(1998, 5, 22)));
+
+    users.stream().forEach(action);
+}
+
+record User(String name, String occupation, LocalDate dob) {
+    static User of(String name, String occupation, LocalDate dob) {
+        return new User(name, occupation, dob);
+    }
+}
+```
+
+## Categorizing age
+
+```java
+import java.util.function.Function;
+import java.util.function.Consumer;
+import java.util.List;
+
+Function<Integer, String> ageCategory = age -> {
+    return switch (age) {
+        case Integer n when n < 18 && n > 0 -> "minor";
+        case Integer n when n >= 18 && n < 64 -> "adult";
+        case Integer n when n > 64 -> "senior";
+        default -> "n/a";
+    };
+};
+
+Consumer<String> action = msg -> System.out.println(msg);
+
+void main() {
+
+    List<Integer> ages = List.of(11, 18, 17, 19, 21, 55, 86, 99, 43, 65, 63);
+    ages.stream().map(age -> ageCategory.apply(age)).forEach(action);
+}
+```
+
+## Filter 
+
+`Predicate<Integer> isEven = n -> n % 2 == 0;`
+
+```java
+import java.util.function.Function;
+import java.util.List;
+
+Function<Integer, Boolean> isEven = n -> n % 2 == 0; 
+
+void main() {
+
+    var vals = List.of(1, 2, 3, 4, 5, 6, 7, 8, 9);
+    vals.stream().filter(isEven::apply).forEach(System.out::println);
+}
+```
+
+## Composition
+
+
+```java
+import java.util.function.Function;
+
+void main() {
+
+    Function<String, String> upperFun = val -> val.toUpperCase();
+    Function<String, String> reverseFun = val -> {
+        return new StringBuilder(val).reverse().toString();
+    };
+
+    var res = upperFun.compose(reverseFun).apply("falcon");
+    System.out.println(res);
+}
+```
+
+## compose vs andThen
+
+The order in which the functions are applied may matter.  
+
+```java
+import java.util.function.Function;
+
+void main() {
+
+    Function<Double, Double> half = a -> a / 2;
+    Function<Double, Double> square = a -> a * a;
+    
+    Function<Double, Double> squareAndThenHalf = square.andThen(half);
+    Double res1 = squareAndThenHalf.apply(3d);  // First squares, then halves
+    
+    System.out.println(res1);
+
+    Function<Double, Double> squareComposeHalf = square.compose(half);
+    Double res2 = squareComposeHalf.apply(3d);  // First halves, then squares
+    System.out.println(res2);
+}
+```
+
+Three functions
+
+```java
+import java.util.function.Function;
+
+Function<Integer, Integer> fn1 = n -> n + 1;
+Function<Integer, Integer> fn2 = n -> n * 2;
+Function<Integer, Integer> fn3 = n -> n * n;
+
+Function<Integer, Integer> cfn1 = fn1.andThen(fn2).andThen(fn3);
+Function<Integer, Integer> cfn2 = fn1.compose(fn2).compose(fn3);
+
+void main() {
+
+    Integer res = cfn1.apply(10);
+    System.out.println(res);
+
+    Integer res2 = cfn2.apply(10);
+    System.out.println(res2);
+}
+```
+
+## Filter & sum
+
+```java
+import java.util.function.Function;
+import java.util.List;
+
+// Function<List<Integer>, Integer> sumEvens = vals -> vals.stream()
+//         .filter(n -> n % 2 == 0)
+//         .mapToInt(Integer::intValue)
+//         .sum();
+
+Function<List<Integer>, Integer> sumEvens = vals -> vals.stream()
+        .filter(n -> n % 2 == 0)
+        .reduce(0, Integer::sum);
+
+void main() {
+
+    List<Integer> vals = List.of(1, 2, 14, 22, 11, 24, 5, 21, 12, 22);
+
+    Integer res = sumEvens.apply(vals);
+    System.out.println(res);
+}
+```
diff --git a/functional/functional_iterface.md b/functional/functional_iterface.md
new file mode 100644
index 00000000..0477b76f
--- /dev/null
+++ b/functional/functional_iterface.md
@@ -0,0 +1,57 @@
+# @FunctionalInterface
+
+## How to throw exception in lambda
+
+Create a custom `Consumer` that throws an exception.  
+
+```java
+import java.io.IOException;
+import java.nio.file.FileStore;
+import java.nio.file.FileSystem;
+import java.nio.file.FileSystems;
+import java.util.function.Consumer;
+
+@FunctionalInterface
+public interface ThrowingConsumer<T> extends Consumer<T> {
+
+    @Override
+    default void accept(final T elem) {
+        try {
+            acceptThrows(elem);
+        } catch (final Exception e) {
+            // Implement your own exception handling logic here..
+            // For example:
+//            System.out.println("handling an exception...");
+            // Or ...
+            throw new RuntimeException(e);
+        }
+    }
+
+    void acceptThrows(T elem) throws Exception;
+
+}
+
+void main(String[] args) throws IOException {
+
+    FileSystem fileSystem = FileSystems.getDefault();
+
+    System.out.printf("%30s | %10s | %23s | %20s \n", "", "Type", "Total space", "Free space");
+    System.out.println("-------------------------------------------------"
+            + "----------------------------------------------------------");
+
+    Iterable<FileStore> fileStores = fileSystem.getFileStores();
+
+//    for (var fileStore : fileStores) {
+//        System.out.printf("%30s | %10s | %20s GB | %20s GB\n", fileStore, fileStore.type(),
+//                (fileStore.getTotalSpace() / 1073741824f),
+//                (fileStore.getUsableSpace() / 1073741824f));
+//    }
+
+    fileStores.forEach((ThrowingConsumer<FileStore>) fileStore -> {
+
+            System.out.printf("%30s | %10s | %20s GB | %20s GB\n", fileStore, fileStore.type(),
+                    (fileStore.getTotalSpace() / 1073741824f),
+                    (fileStore.getUsableSpace() / 1073741824f));
+        });
+}
+```
diff --git a/garbage-collection.md b/garbage-collection.md
new file mode 100644
index 00000000..7f9c036e
--- /dev/null
+++ b/garbage-collection.md
@@ -0,0 +1,1214 @@
+# Garbage Collection in Java  
+
+Garbage Collection (GC) is an automatic memory management mechanism in Java that  
+identifies and reclaims memory occupied by objects that are no longer in use. This  
+frees developers from manual memory management, reducing memory leaks and dangling  
+pointer bugs that plague languages like C and C++. Understanding GC algorithms is  
+essential for building high-performance Java applications.  
+
+The Java Virtual Machine (JVM) has evolved significantly since its inception,  
+introducing increasingly sophisticated garbage collectors to meet the demands of  
+modern applications. From the original Serial collector to today's ultra-low-latency  
+collectors like ZGC and Shenandoah, each generation has brought improvements in  
+throughput, pause times, and scalability.  
+
+This document explores the major garbage collection algorithms available in modern  
+Java: G1 (the default), ZGC, Shenandoah, and Epsilon. Each collector is designed  
+for specific use cases, and choosing the right one can dramatically impact  
+application performance.  
+
+
+## Overview of Garbage Collection  
+
+Garbage collection automates the process of reclaiming memory from objects that  
+are no longer reachable by the application. The JVM divides the heap into regions  
+and uses various strategies to identify and collect garbage efficiently.  
+
+
+### Heap Structure  
+
+The JVM heap is traditionally divided into generations based on object lifetimes:  
+
+| Region       | Description                                                     |
+|--------------|-----------------------------------------------------------------|
+| Young Gen    | Newly allocated objects; most objects die here (short-lived)   |
+| Eden Space   | Initial allocation area within Young Generation                |
+| Survivor     | Objects that survived one or more Young GC cycles              |
+| Old Gen      | Long-lived objects promoted from Young Generation              |
+| Metaspace    | Class metadata and method information (not in heap)            |
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                               JVM Heap                                      │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  ┌─────────────────────────────────┐  ┌─────────────────────────────────┐  │
+│  │        Young Generation         │  │         Old Generation          │  │
+│  │  ┌───────────────────────────┐  │  │                                 │  │
+│  │  │        Eden Space         │  │  │   Long-lived objects that       │  │
+│  │  │   (New allocations)       │  │  │   survived multiple GC cycles   │  │
+│  │  └───────────────────────────┘  │  │                                 │  │
+│  │  ┌────────────┐ ┌────────────┐  │  │                                 │  │
+│  │  │ Survivor 0 │ │ Survivor 1 │  │  │                                 │  │
+│  │  │   (From)   │ │   (To)     │  │  │                                 │  │
+│  │  └────────────┘ └────────────┘  │  │                                 │  │
+│  └─────────────────────────────────┘  └─────────────────────────────────┘  │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+Modern collectors like ZGC and Shenandoah may use different heap layouts,  
+organizing memory into uniformly-sized regions rather than generations.  
+
+
+### Object Lifecycle  
+
+Objects go through a predictable lifecycle from allocation to collection:  
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                          Object Lifecycle                                   │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│   ┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────────────┐  │
+│   │  Object  │     │  Object  │     │  Object  │     │    Object is     │  │
+│   │ Created  │────►│  In Use  │────►│ Becomes  │────►│    Collected     │  │
+│   │ in Eden  │     │ (Reach-  │     │ Unreach- │     │  (Memory freed)  │  │
+│   │          │     │   able)  │     │   able   │     │                  │  │
+│   └──────────┘     └──────────┘     └──────────┘     └──────────────────┘  │
+│        │                                                                    │
+│        │ If survives GC                                                     │
+│        ▼                                                                    │
+│   ┌──────────┐     ┌──────────┐                                            │
+│   │ Promoted │     │ Promoted │                                            │
+│   │    to    │────►│    to    │                                            │
+│   │ Survivor │     │ Old Gen  │                                            │
+│   └──────────┘     └──────────┘                                            │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+
+### GC Phases  
+
+Most garbage collectors perform these fundamental phases:  
+
+| Phase        | Description                                                    |
+|--------------|----------------------------------------------------------------|
+| Marking      | Identify all reachable (live) objects starting from GC roots  |
+| Sweeping     | Identify unreachable objects as garbage                        |
+| Compacting   | Move live objects together to eliminate fragmentation          |
+| Copying      | Copy live objects to a new region (alternative to compacting)  |
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           GC Phases Overview                                │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  1. MARKING PHASE                                                           │
+│     ┌─────────────────────────────────────────────────────────────────┐    │
+│     │  GC Roots ──► Live Object ──► Live Object ──► Live Object       │    │
+│     │      │                             │                             │    │
+│     │      ▼                             ▼                             │    │
+│     │  Live Object                   Live Object     [Dead] [Dead]    │    │
+│     └─────────────────────────────────────────────────────────────────┘    │
+│                                                                             │
+│  2. SWEEPING PHASE                                                          │
+│     ┌─────────────────────────────────────────────────────────────────┐    │
+│     │  [Live] [    Free    ] [Live] [Live] [     Free      ] [Live]   │    │
+│     │         Dead objects reclaimed, memory fragmented               │    │
+│     └─────────────────────────────────────────────────────────────────┘    │
+│                                                                             │
+│  3. COMPACTING PHASE                                                        │
+│     ┌─────────────────────────────────────────────────────────────────┐    │
+│     │  [Live][Live][Live][Live][          Free Space          ]       │    │
+│     │         Objects moved together, eliminating fragmentation       │    │
+│     └─────────────────────────────────────────────────────────────────┘    │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+
+### Stop-the-World Pauses  
+
+A **stop-the-world (STW)** pause occurs when the GC must pause all application  
+threads to safely perform certain operations. Reducing these pauses is a primary  
+goal of modern collectors.  
+
+| Pause Type     | Description                                               |
+|----------------|-----------------------------------------------------------|
+| Minor GC       | Collection of Young Generation; typically short           |
+| Major GC       | Collection of Old Generation; often longer                |
+| Full GC        | Collection of entire heap; longest pause                  |
+| Concurrent GC  | GC work done while application runs (no pause)            |
+
+Modern collectors like ZGC and Shenandoah perform most work concurrently,  
+achieving sub-millisecond pause times regardless of heap size.  
+
+
+### Concurrent vs Parallel Collection  
+
+Understanding the difference between concurrent and parallel collection is crucial:  
+
+| Term        | Description                                                    |
+|-------------|----------------------------------------------------------------|
+| Parallel    | Multiple GC threads work together during STW pause             |
+| Concurrent  | GC threads work while application threads continue running     |
+| Incremental | GC work is divided into smaller chunks across multiple pauses  |
+
+
+## G1 Garbage Collector  
+
+The Garbage First (G1) collector is the default garbage collector in Java 9+.  
+It is designed to provide high throughput with predictable pause times, making  
+it suitable for most applications. G1 balances the needs of large heaps with  
+the requirement for reasonable latency.  
+
+
+### Region-Based Heap Management  
+
+G1 divides the heap into equally-sized regions (typically 1-32 MB each) rather  
+than contiguous generations. Each region can be Eden, Survivor, Old, or Humongous  
+(for large objects).  
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         G1 Region-Based Heap                                │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐          │
+│  │  E  │ │  E  │ │  S  │ │  O  │ │  O  │ │  O  │ │  E  │ │  H  │          │
+│  └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘          │
+│  ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐          │
+│  │  O  │ │  E  │ │  O  │ │  F  │ │  F  │ │  O  │ │  S  │ │  H  │          │
+│  └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘          │
+│  ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐          │
+│  │  O  │ │  F  │ │  O  │ │  O  │ │  E  │ │  O  │ │  F  │ │  O  │          │
+│  └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘          │
+│                                                                             │
+│  Legend: E = Eden, S = Survivor, O = Old, H = Humongous, F = Free          │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+
+### How G1 Works  
+
+G1 operates in several phases to manage memory efficiently:  
+
+| Phase                    | Description                                         |
+|--------------------------|-----------------------------------------------------|
+| Young GC                 | Collects Eden and Survivor regions                  |
+| Concurrent Marking       | Marks live objects while application runs           |
+| Mixed GC                 | Collects Young regions plus selected Old regions    |
+| Full GC                  | Fallback collection of entire heap (avoided if ok)  |
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           G1 GC Cycle                                       │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│   ┌─────────────┐     ┌─────────────────────┐     ┌─────────────────────┐  │
+│   │  Young GC   │────►│ Concurrent Marking  │────►│      Mixed GC       │  │
+│   │   (STW)     │     │   (Concurrent)      │     │       (STW)         │  │
+│   └─────────────┘     └─────────────────────┘     └─────────────────────┘  │
+│         │                                                   │               │
+│         │                                                   │               │
+│         └───────────────────────────────────────────────────┘               │
+│                           (Cycle repeats)                                   │
+│                                                                             │
+│   Concurrent Marking Phases:                                                │
+│   1. Initial Mark (STW) - Mark objects directly reachable from GC roots    │
+│   2. Root Region Scan   - Scan survivor regions for references to old gen  │
+│   3. Concurrent Mark    - Mark live objects throughout the heap            │
+│   4. Remark (STW)       - Complete marking of remaining live objects       │
+│   5. Cleanup (STW/Conc) - Identify completely empty regions to reclaim     │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+
+### G1 Advantages  
+
+G1 provides several key benefits:  
+
+- **Predictable pause times**: Configurable pause time targets  
+- **Region-based collection**: Only collects regions with most garbage first  
+- **Compaction**: Reduces fragmentation during evacuation  
+- **Scalability**: Handles heaps from gigabytes to terabytes  
+- **Adaptive**: Automatically adjusts to meet pause time goals  
+
+
+### G1 JVM Tuning Flags  
+
+Common JVM flags for configuring G1:  
+
+```bash
+# Enable G1 (default in Java 9+)
+-XX:+UseG1GC
+
+# Set maximum pause time target (milliseconds)
+-XX:MaxGCPauseMillis=200
+
+# Set heap region size (1-32 MB, must be power of 2)
+-XX:G1HeapRegionSize=16m
+
+# Set percentage of heap for Old Generation threshold
+-XX:InitiatingHeapOccupancyPercent=45
+
+# Number of parallel GC threads
+-XX:ParallelGCThreads=8
+
+# Number of concurrent marking threads
+-XX:ConcGCThreads=4
+
+# Reserve memory for promotion failures
+-XX:G1ReservePercent=10
+
+# Enable string deduplication
+-XX:+UseStringDeduplication
+```
+
+Example complete configuration for a web server:  
+
+```bash
+java -Xms4g -Xmx4g \
+     -XX:+UseG1GC \
+     -XX:MaxGCPauseMillis=100 \
+     -XX:G1HeapRegionSize=8m \
+     -XX:InitiatingHeapOccupancyPercent=35 \
+     -XX:+UseStringDeduplication \
+     -jar application.jar
+```
+
+
+### Monitoring G1 with simple output  
+
+You can observe G1 behavior by enabling GC logging:  
+
+```java
+void main() {
+
+    // Allocate objects to trigger GC
+    var list = new ArrayList<byte[]>();
+    
+    for (int i = 0; i < 100; i++) {
+        // Allocate 1 MB blocks
+        list.add(new byte[1024 * 1024]);
+        
+        if (i % 10 == 0) {
+            // Release some references to create garbage
+            list.subList(0, Math.min(5, list.size())).clear();
+        }
+    }
+    
+    // Force garbage collection
+    System.gc();
+    
+    var runtime = Runtime.getRuntime();
+    long usedMemory = runtime.totalMemory() - runtime.freeMemory();
+    long maxMemory = runtime.maxMemory();
+    
+    IO.println("Used memory: " + usedMemory / (1024 * 1024) + " MB");
+    IO.println("Max memory: " + maxMemory / (1024 * 1024) + " MB");
+}
+```
+
+Run with GC logging enabled:  
+
+```bash
+java --enable-preview --source 25 \
+     -XX:+UseG1GC \
+     -Xlog:gc*:file=gc.log:time,uptime:filecount=5,filesize=10m \
+     GCDemo.java
+```
+
+This produces detailed logs showing Young GC, concurrent marking phases, and  
+mixed GC events with timing information.  
+
+
+## ZGC (Z Garbage Collector)  
+
+ZGC is an ultra-low-latency garbage collector designed to keep pause times under  
+1 millisecond regardless of heap size. It can handle heaps ranging from megabytes  
+to multi-terabytes while maintaining consistent sub-millisecond pauses.  
+
+
+### ZGC Design Goals  
+
+ZGC was designed with specific goals in mind:  
+
+| Goal                    | Description                                         |
+|-------------------------|-----------------------------------------------------|
+| Ultra-low latency       | Pause times < 1 ms regardless of heap size          |
+| Scalability             | Support heaps from 8 MB to 16 TB                    |
+| Concurrent              | Almost all work done concurrently with application  |
+| No tuning required      | Minimal configuration needed                        |
+
+
+### Colored Pointers  
+
+ZGC uses **colored pointers** to store metadata directly in object references.  
+This innovative approach allows ZGC to determine object state without accessing  
+the object itself.  
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                        ZGC Colored Pointer (64-bit)                         │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  Bit Layout (Linux/x64):                                                    │
+│  ┌────────┬────────┬────────┬────────┬──────────────────────────────────┐  │
+│  │ Unused │ Final- │ Remap  │ Mark 1 │         Object Address           │  │
+│  │(16 bit)│ izable │        │ Mark 0 │           (42 bits)              │  │
+│  │        │(1 bit) │(1 bit) │(2 bits)│                                  │  │
+│  └────────┴────────┴────────┴────────┴──────────────────────────────────┘  │
+│                                                                             │
+│  Metadata bits (4 bits total):                                              │
+│  - Finalizable: Object has a finalizer                                      │
+│  - Remapped:    Object has been relocated                                   │
+│  - Marked:      Object is reachable (two mark bits for alternating cycles) │
+│                                                                             │
+│  The 42-bit address supports up to 4 TB of heap address space              │
+│  (16 TB with pointer compression disabled)                                 │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+
+### Load Barriers  
+
+ZGC uses **load barriers** instead of write barriers. When an object reference  
+is loaded from the heap, the barrier checks if any action is needed (such as  
+updating a relocated pointer).  
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                          ZGC Load Barrier                                   │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│   Application Code:        Load Barrier Check:                              │
+│   ┌───────────────┐        ┌─────────────────────────────────────────┐     │
+│   │ Object ref =  │        │ if (pointer needs remapping) {         │     │
+│   │   obj.field   │ ──────►│     update pointer to new location     │     │
+│   └───────────────┘        │ }                                       │     │
+│                            │ return corrected pointer                │     │
+│                            └─────────────────────────────────────────┘     │
+│                                                                             │
+│   Benefits:                                                                 │
+│   - Application always sees up-to-date references                          │
+│   - Relocation can happen concurrently                                      │
+│   - No stop-the-world pause needed for compaction                          │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+
+### ZGC Phases  
+
+ZGC operates in several concurrent phases with minimal STW pauses:  
+
+| Phase                  | Type        | Description                           |
+|------------------------|-------------|---------------------------------------|
+| Pause Mark Start       | STW (<1ms)  | Start marking, scan thread stacks     |
+| Concurrent Mark        | Concurrent  | Traverse object graph, mark live objs |
+| Pause Mark End         | STW (<1ms)  | Complete marking                       |
+| Concurrent Process     | Concurrent  | Process weak references               |
+| Concurrent Reset       | Concurrent  | Reset metadata for next cycle         |
+| Concurrent Relocate    | Concurrent  | Move objects, update references       |
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           ZGC Cycle                                         │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  STW (< 1ms)  │         Concurrent Work (Application Running)        │ STW │
+│  ┌─────────┐  │  ┌─────────────────────────────────────────────────┐ │┌───┐│
+│  │  Mark   │──┼─►│  Concurrent Marking ──► Concurrent Relocation  │─┼┤End││
+│  │  Start  │  │  │                                                 │ │└───┘│
+│  └─────────┘  │  └─────────────────────────────────────────────────┘ │     │
+│               │                                                       │     │
+│  Application  │  Application runs with load barriers                 │ App │
+│   paused      │  checking/updating references as needed              │ run │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+
+### ZGC Advantages  
+
+ZGC provides exceptional benefits for latency-sensitive applications:  
+
+- **Sub-millisecond pauses**: Typically < 0.5 ms, regardless of heap size  
+- **Scalable**: Supports heaps from 8 MB to 16 TB  
+- **Concurrent compaction**: No fragmentation without long pauses  
+- **NUMA-aware**: Optimized for multi-socket systems  
+- **Self-tuning**: Minimal configuration required  
+
+
+### ZGC JVM Tuning Flags  
+
+Common JVM flags for configuring ZGC:  
+
+```bash
+# Enable ZGC
+-XX:+UseZGC
+
+# Enable generational ZGC (Java 21+, default in Java 23+)
+-XX:+UseZGC -XX:+ZGenerational
+
+# Set maximum heap size (ZGC works best with larger heaps)
+-Xmx16g
+
+# Set concurrent GC threads (default is 25% of CPU cores)
+-XX:ConcGCThreads=4
+
+# Soft max heap size (ZGC tries to stay below this)
+-XX:SoftMaxHeapSize=8g
+
+# Uncommit unused memory (returns memory to OS)
+-XX:+ZUncommit
+-XX:ZUncommitDelay=300
+
+# Enable large pages for better performance
+-XX:+UseLargePages
+```
+
+Example configuration for a low-latency trading application:  
+
+```bash
+java -Xms32g -Xmx32g \
+     -XX:+UseZGC \
+     -XX:+ZGenerational \
+     -XX:SoftMaxHeapSize=28g \
+     -XX:+UseLargePages \
+     -XX:+AlwaysPreTouch \
+     -jar trading-app.jar
+```
+
+
+### Generational ZGC  
+
+Java 21 introduced Generational ZGC which separates young and old generations  
+while maintaining the sub-millisecond pause time guarantee:  
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                       Generational ZGC (Java 21+)                           │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  Benefits of Generational ZGC:                                              │
+│  - Faster collection of short-lived objects                                 │
+│  - Reduced memory overhead                                                  │
+│  - Better throughput for allocation-heavy workloads                         │
+│  - Maintains sub-millisecond pause times                                    │
+│                                                                             │
+│  ┌─────────────────────────┐  ┌─────────────────────────────────────────┐  │
+│  │    Young Generation     │  │           Old Generation                │  │
+│  │  (Collected frequently) │  │       (Collected less often)            │  │
+│  │                         │  │                                         │  │
+│  │  Short-lived objects    │  │  Long-lived objects promoted            │  │
+│  │  Most garbage here      │  │  from young generation                  │  │
+│  └─────────────────────────┘  └─────────────────────────────────────────┘  │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+
+## Shenandoah GC  
+
+Shenandoah is a low-pause-time garbage collector that performs concurrent  
+compaction. It was developed by Red Hat and is included in OpenJDK. Like ZGC,  
+Shenandoah aims for pause times independent of heap size.  
+
+
+### Shenandoah Design  
+
+Shenandoah's key innovation is **concurrent compaction**—the ability to compact  
+the heap while the application continues running. This is achieved through:  
+
+| Feature             | Description                                              |
+|---------------------|----------------------------------------------------------|
+| Brooks Pointers     | Forwarding pointers in object headers                    |
+| Read Barriers       | Check if object has been relocated                       |
+| Write Barriers      | Ensure concurrent updates are safe                       |
+| Self-healing        | References automatically update during access            |
+
+
+### Brooks Pointers  
+
+Each object in Shenandoah contains a **forwarding pointer** that points to  
+itself initially and is updated to point to the new location during relocation:  
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                        Brooks Forwarding Pointer                            │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  Before Relocation:                                                         │
+│  ┌─────────────────────────────────┐                                       │
+│  │  ┌─────────────────────────┐   │                                        │
+│  │  │ Forwarding Ptr ──────┐  │   │ Points to itself                       │
+│  │  ├─────────────────────│─┘  │   │                                        │
+│  │  │ Object Header       │   │   │                                        │
+│  │  ├─────────────────────────┤   │                                        │
+│  │  │ Object Data             │   │                                        │
+│  │  └─────────────────────────┘   │                                        │
+│  └─────────────────────────────────┘                                       │
+│                                                                             │
+│  After Relocation:                                                          │
+│  ┌──────────────────────────┐     ┌─────────────────────────┐              │
+│  │ Old Location             │     │ New Location            │              │
+│  │  ┌────────────────────┐  │     │  ┌────────────────────┐ │              │
+│  │  │ Fwd Ptr ──────────────────────►│ Fwd Ptr ──────┐    │ │              │
+│  │  ├────────────────────┤  │     │  ├───────────│──┘    │ │              │
+│  │  │ (Stale data)       │  │     │  │ Object Header     │ │              │
+│  │  └────────────────────┘  │     │  ├────────────────────┤ │              │
+│  └──────────────────────────┘     │  │ Object Data        │ │              │
+│                                   │  └────────────────────┘ │              │
+│                                   └─────────────────────────┘              │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+
+### Shenandoah GC Phases  
+
+Shenandoah operates in several phases:  
+
+| Phase                  | Type        | Description                           |
+|------------------------|-------------|---------------------------------------|
+| Init Mark              | STW (<1ms)  | Scan GC roots, prepare for marking    |
+| Concurrent Marking     | Concurrent  | Traverse object graph                 |
+| Final Mark             | STW (<1ms)  | Complete marking, prepare for evac    |
+| Concurrent Cleanup     | Concurrent  | Reclaim regions with no live objects  |
+| Concurrent Evacuation  | Concurrent  | Copy live objects to new regions      |
+| Init Update Refs       | STW (<1ms)  | Prepare for reference updating        |
+| Concurrent Update Refs | Concurrent  | Update all references to new locations|
+| Final Update Refs      | STW (<1ms)  | Complete reference updating           |
+| Concurrent Cleanup     | Concurrent  | Reclaim evacuated regions             |
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                        Shenandoah GC Cycle                                  │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  ┌─────┐ Concurrent  ┌─────┐ Concurrent  ┌─────┐ Concurrent  ┌─────┐       │
+│  │Init │   Marking   │Final│ Evacuation  │Init │ Update Refs │Final│       │
+│  │Mark │────────────►│Mark │────────────►│UR   │────────────►│ UR  │       │
+│  │(STW)│             │(STW)│             │(STW)│             │(STW)│       │
+│  └─────┘             └─────┘             └─────┘             └─────┘       │
+│   <1ms                <1ms                <1ms                <1ms         │
+│                                                                             │
+│  Concurrent phases run alongside application threads                        │
+│  STW pauses are very brief - typically under 1 millisecond                 │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+
+### Shenandoah Advantages  
+
+Shenandoah provides significant benefits:  
+
+- **Consistent low pauses**: Sub-millisecond pauses regardless of heap size  
+- **Concurrent compaction**: Eliminates fragmentation without STW pauses  
+- **Wide availability**: Available in most OpenJDK distributions  
+- **Proven in production**: Used in many enterprise applications  
+- **Memory efficient**: Reasonable memory overhead  
+
+
+### Shenandoah JVM Tuning Flags  
+
+Common JVM flags for configuring Shenandoah:  
+
+```bash
+# Enable Shenandoah GC
+-XX:+UseShenandoahGC
+
+# Set heuristics mode (adaptive, static, compact, aggressive)
+-XX:ShenandoahGCHeuristics=adaptive
+
+# Percentage of heap to allocate before triggering GC
+-XX:ShenandoahAllocationThreshold=10
+
+# Free threshold to trigger concurrent GC
+-XX:ShenandoahFreeThreshold=10
+
+# Number of parallel GC threads
+-XX:ParallelGCThreads=8
+
+# Number of concurrent GC threads
+-XX:ConcGCThreads=4
+
+# Enable uncommit for returning memory to OS
+-XX:ShenandoahUncommitDelay=1000
+-XX:ShenandoahGuaranteedGCInterval=30000
+```
+
+Example configuration for a microservices application:  
+
+```bash
+java -Xms2g -Xmx2g \
+     -XX:+UseShenandoahGC \
+     -XX:ShenandoahGCHeuristics=compact \
+     -XX:+AlwaysPreTouch \
+     -jar microservice.jar
+```
+
+
+### Shenandoah Heuristics  
+
+Shenandoah supports different heuristics modes for different workloads:  
+
+| Heuristic   | Description                                                  |
+|-------------|--------------------------------------------------------------|
+| adaptive    | Default; balances throughput and pause times                 |
+| static      | Triggers GC at fixed heap occupancy thresholds               |
+| compact     | Aggressive compaction for fragmentation-prone workloads      |
+| aggressive  | Continuous GC for testing and debugging                      |
+| passive     | Never initiates GC cycles (for testing only)                 |
+
+
+## Epsilon GC  
+
+Epsilon is a **no-op garbage collector** that handles memory allocation but  
+never reclaims any garbage. It is designed for specific use cases where GC  
+overhead must be eliminated or measured.  
+
+
+### Epsilon Design  
+
+Epsilon is intentionally minimal:  
+
+| Feature              | Description                                           |
+|----------------------|-------------------------------------------------------|
+| Memory allocation    | Handles object allocation as normal                   |
+| No garbage collection| Never performs any collection                         |
+| OutOfMemoryError     | Application crashes when heap is exhausted            |
+| Zero GC overhead     | No GC threads, barriers, or pauses                    |
+
+
+### Epsilon Use Cases  
+
+Epsilon is useful for specific scenarios:  
+
+| Use Case                    | Description                                      |
+|-----------------------------|--------------------------------------------------|
+| Performance testing         | Measure application without GC interference      |
+| Memory pressure testing     | Find how much memory application truly needs     |
+| Short-lived applications    | Jobs that complete before filling heap           |
+| Latency-sensitive testing   | Establish baseline latency without GC pauses     |
+| GC algorithm comparison     | Compare overhead of different collectors         |
+| Memory leak detection       | Application quickly fails if leaking memory      |
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                        Epsilon GC Behavior                                  │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│   Heap Usage Over Time:                                                     │
+│                                                                             │
+│   Memory │                                         ┌─── OutOfMemoryError   │
+│     ▲    │                                    ┌────┘                        │
+│     │    │                              ┌─────┘                             │
+│     │    │                        ┌─────┘                                   │
+│   Max────┼────────────────────────┼─────────────────────────────────────   │
+│     │    │                  ┌─────┘                                         │
+│     │    │            ┌─────┘                                               │
+│     │    │      ┌─────┘                                                     │
+│     │    │ ┌────┘                                                           │
+│     │    │─┘                                                                │
+│     │    └──────────────────────────────────────────────────────────► Time │
+│          Start                                              Crash          │
+│                                                                             │
+│   With Epsilon: Memory only increases, never reclaimed                      │
+│   Application must complete before heap exhaustion                          │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+
+### Epsilon JVM Tuning Flags  
+
+JVM flags for Epsilon:  
+
+```bash
+# Enable Epsilon GC (must explicitly unlock experimental features in older JDKs)
+-XX:+UseEpsilonGC
+
+# For older Java versions (before Epsilon became stable)
+-XX:+UnlockExperimentalVMOptions -XX:+UseEpsilonGC
+
+# Set heap size appropriately for your workload
+-Xms4g -Xmx4g
+
+# Optional: Exit on OutOfMemoryError for clean shutdown
+-XX:+ExitOnOutOfMemoryError
+
+# Optional: Heap dump on OOM for analysis
+-XX:+HeapDumpOnOutOfMemoryError
+-XX:HeapDumpPath=/path/to/dumps
+```
+
+Example configuration for performance baseline testing:  
+
+```bash
+java -Xms8g -Xmx8g \
+     -XX:+UseEpsilonGC \
+     -XX:+ExitOnOutOfMemoryError \
+     -jar benchmark-app.jar
+```
+
+
+### Epsilon demonstration  
+
+This example shows how Epsilon handles memory:  
+
+```java
+void main() {
+
+    var runtime = Runtime.getRuntime();
+    var list = new ArrayList<byte[]>();
+    
+    IO.println("Starting Epsilon GC demonstration");
+    IO.println("Max heap: " + runtime.maxMemory() / (1024 * 1024) + " MB");
+    
+    try {
+        for (int i = 0; i < 1000; i++) {
+            // Allocate 1 MB blocks
+            list.add(new byte[1024 * 1024]);
+            
+            if (i % 50 == 0) {
+                long used = runtime.totalMemory() - runtime.freeMemory();
+                IO.println("Allocated " + (i + 1) + " MB, " +
+                          "Used: " + used / (1024 * 1024) + " MB");
+            }
+        }
+    } catch (OutOfMemoryError e) {
+        IO.println("OutOfMemoryError: Heap exhausted as expected with Epsilon");
+    }
+}
+```
+
+Run with Epsilon enabled:  
+
+```bash
+java --enable-preview --source 25 \
+     -Xms256m -Xmx256m \
+     -XX:+UseEpsilonGC \
+     EpsilonDemo.java
+```
+
+The application will crash with `OutOfMemoryError` when the heap is exhausted,  
+demonstrating that Epsilon never reclaims memory.  
+
+
+## Comparison of GC Algorithms  
+
+This section compares the four garbage collectors across various dimensions:  
+
+
+### Feature Comparison  
+
+| Feature              | G1 GC          | ZGC            | Shenandoah     | Epsilon        |
+|----------------------|----------------|----------------|----------------|----------------|
+| Default (Java 9+)    | Yes            | No             | No             | No             |
+| Typical pause times  | 10-200 ms      | < 1 ms         | < 10 ms        | None           |
+| Max pause times      | 500+ ms        | < 1 ms         | < 10 ms        | None           |
+| Heap size support    | GB to TB       | MB to 16 TB    | MB to TB       | Any            |
+| Throughput           | High           | High           | High           | Maximum        |
+| Memory overhead      | Low-Medium     | Medium         | Medium         | None           |
+| Concurrent compact   | Partial        | Yes            | Yes            | N/A            |
+| Generational         | Yes            | Yes (Java 21+) | No             | N/A            |
+| JDK availability     | All            | OpenJDK 11+    | OpenJDK 12+    | OpenJDK 11+    |
+
+
+### Pause Time Comparison  
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                    Typical Pause Time Comparison                            │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  Pause Time (ms)                                                            │
+│                                                                             │
+│     500 ─┤                                                                  │
+│          │  ░░░░░ G1 Full GC (worst case)                                  │
+│          │  ░░░░░                                                          │
+│     200 ─┤  ░░░░░                                                          │
+│          │  ░░░░░                                                          │
+│          │  ░░░░░                                                          │
+│     100 ─┤  ░░░░░ G1 Mixed GC                                              │
+│          │  ░░░░░                                                          │
+│          │  ░░░░░                                                          │
+│      50 ─┤  ░░░░░                                                          │
+│          │  ░░░░░                                                          │
+│          │  ░░░░░   ▓▓▓ G1 Young GC                                        │
+│      10 ─┤  ░░░░░   ▓▓▓                   ▒▒▒ Shenandoah                   │
+│          │  ░░░░░   ▓▓▓                   ▒▒▒                              │
+│       1 ─┤  ░░░░░   ▓▓▓   ███ ZGC         ▒▒▒                              │
+│          │  ░░░░░   ▓▓▓   ███             ▒▒▒                              │
+│       0 ─┼──────────────────────────────────────────► Epsilon (no pauses) │
+│          │    G1        ZGC      Shenandoah    Epsilon                     │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+
+### Use Case Recommendations  
+
+| Application Type           | Recommended GC | Reason                          |
+|----------------------------|----------------|---------------------------------|
+| General purpose            | G1             | Good balance, well-tested       |
+| Web services (typical)     | G1             | Predictable performance         |
+| Low-latency trading        | ZGC            | Sub-ms pauses critical          |
+| Real-time systems          | ZGC/Shenandoah | Consistent low latency          |
+| Large heap (> 32 GB)       | ZGC            | Scales well with heap size      |
+| Microservices              | G1/Shenandoah  | Good startup, reasonable pause  |
+| Batch processing           | G1             | High throughput, pauses okay    |
+| Performance testing        | Epsilon        | Zero GC interference            |
+| Short-lived processes      | Epsilon        | No GC needed                    |
+
+
+### Memory Overhead Comparison  
+
+| Collector   | Overhead Source                                              |
+|-------------|--------------------------------------------------------------|
+| G1          | Remembered sets, region metadata (~5-10% overhead)           |
+| ZGC         | Colored pointers, multi-mapping (~10-15% overhead)           |
+| Shenandoah  | Brooks pointers, barriers (~10-15% overhead)                 |
+| Epsilon     | None (but never frees memory)                                |
+
+
+## Choosing the Right GC  
+
+Selecting the appropriate garbage collector depends on your application's  
+requirements. Use this decision framework to guide your choice.  
+
+
+### Decision Framework  
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                      GC Selection Decision Tree                             │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│                    What are your primary requirements?                      │
+│                                                                             │
+│                              ┌────────────┐                                 │
+│                              │   Start    │                                 │
+│                              └─────┬──────┘                                 │
+│                                    │                                        │
+│                    ┌───────────────┼───────────────┐                        │
+│                    ▼               ▼               ▼                        │
+│             ┌────────────┐  ┌────────────┐  ┌────────────┐                  │
+│             │ Ultra-low  │  │  General   │  │Performance │                  │
+│             │  latency   │  │  purpose   │  │  testing   │                  │
+│             │  (< 1 ms)  │  │            │  │            │                  │
+│             └─────┬──────┘  └─────┬──────┘  └─────┬──────┘                  │
+│                   │               │               │                         │
+│             ┌─────┴─────┐        │               │                         │
+│             ▼           ▼        ▼               ▼                         │
+│        ┌────────┐ ┌────────┐ ┌────────┐    ┌────────────┐                  │
+│        │  ZGC   │ │Shenan- │ │   G1   │    │  Epsilon   │                  │
+│        │        │ │ doah   │ │ (def)  │    │            │                  │
+│        └────────┘ └────────┘ └────────┘    └────────────┘                  │
+│                                                                             │
+│  Further considerations:                                                    │
+│  - ZGC: Best for heaps > 4GB, Java 17+                                     │
+│  - Shenandoah: Good alternative to ZGC, widely available                   │
+│  - G1: Best general choice, extensive tuning options                       │
+│  - Epsilon: Only for testing or short-lived processes                      │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+
+### Latency Requirements  
+
+| Latency Requirement        | Recommended GC    | Configuration                  |
+|----------------------------|-------------------|--------------------------------|
+| Any pause acceptable       | G1                | Default settings               |
+| < 200 ms 99th percentile   | G1                | Tuned MaxGCPauseMillis         |
+| < 50 ms 99th percentile    | G1/Shenandoah     | Careful tuning                 |
+| < 10 ms 99th percentile    | ZGC/Shenandoah    | Default is usually fine        |
+| < 1 ms 99th percentile     | ZGC               | Default settings               |
+
+
+### Throughput vs Latency Trade-offs  
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                    Throughput vs Latency Trade-off                          │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  Throughput ▲                                                               │
+│     (high)  │                                                               │
+│             │  ┌─────────┐                                                  │
+│             │  │ Epsilon │ (no GC overhead, but OOM risk)                   │
+│             │  └─────────┘                                                  │
+│             │         ┌─────────┐                                           │
+│             │         │   G1    │ (high throughput, moderate pauses)        │
+│             │         └─────────┘                                           │
+│             │              ┌────────────┐                                   │
+│             │              │ Shenandoah │ (good throughput, low pauses)     │
+│             │              └────────────┘                                   │
+│             │                   ┌─────────┐                                 │
+│             │                   │   ZGC   │ (good throughput, < 1ms pause) │
+│             │                   └─────────┘                                 │
+│      (low)  │                                                               │
+│             └──────────────────────────────────────────────────────────────►│
+│                   Low                                              High     │
+│                                 Latency (pause times)                       │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+
+### Heap Size Considerations  
+
+| Heap Size        | Recommended GC     | Notes                              |
+|------------------|--------------------|------------------------------------|
+| < 256 MB         | G1 or Serial       | G1 overhead may be significant     |
+| 256 MB - 4 GB    | G1                 | Default, well-tuned                |
+| 4 GB - 32 GB     | G1 or ZGC          | Both work well                     |
+| 32 GB - 256 GB   | ZGC or Shenandoah  | Low-latency collectors preferred   |
+| > 256 GB         | ZGC                | Designed for very large heaps      |
+
+
+## Best Practices  
+
+Following these best practices helps ensure optimal GC performance and  
+application stability.  
+
+
+### Monitoring GC Performance  
+
+Use these tools to monitor GC behavior:  
+
+| Tool                   | Description                                         |
+|------------------------|-----------------------------------------------------|
+| JDK Flight Recorder    | Low-overhead profiling built into JVM               |
+| VisualVM               | GUI for monitoring GC, heap, threads                |
+| GC Logs                | Detailed GC event information                       |
+| jstat                  | Command-line GC statistics                          |
+| jcmd                   | Diagnostic commands for running JVM                 |
+
+
+### Enable GC Logging  
+
+Always enable GC logging in production:  
+
+```bash
+# Modern unified logging (Java 9+)
+-Xlog:gc*:file=gc.log:time,uptime,level,tags:filecount=10,filesize=100m
+
+# More detailed logging
+-Xlog:gc+heap=debug:file=gc.log:time,uptime:filecount=5,filesize=50m
+
+# Log to both file and console
+-Xlog:gc*:file=gc.log:time -Xlog:gc:stdout:time
+```
+
+
+### GC Log Analysis  
+
+Key metrics to monitor in GC logs:  
+
+| Metric                    | Healthy Range         | Warning Signs            |
+|---------------------------|-----------------------|--------------------------|
+| GC pause time             | < target              | Exceeds MaxGCPauseMillis |
+| GC frequency              | Stable                | Increasing over time     |
+| Heap after GC             | < 70% of max          | Consistently > 80%       |
+| Allocation rate           | Stable                | Sudden spikes            |
+| Promotion rate            | Low relative to alloc | High promotion rate      |
+| Full GC frequency         | Rare or never         | Frequent Full GCs        |
+
+
+### JVM Tuning Guidelines  
+
+General tuning recommendations:  
+
+```bash
+# Start with reasonable heap sizing
+-Xms4g -Xmx4g  # Equal min/max avoids resize pauses
+
+# Pre-touch memory for consistent performance
+-XX:+AlwaysPreTouch
+
+# Use large pages if available (improves TLB efficiency)
+-XX:+UseLargePages
+
+# Set appropriate thread counts
+-XX:ParallelGCThreads=8   # Usually = CPU cores
+-XX:ConcGCThreads=2       # Usually = ParallelGCThreads/4
+
+# Enable string deduplication for string-heavy apps
+-XX:+UseStringDeduplication  # G1 only
+```
+
+
+### Common Pitfalls to Avoid  
+
+| Pitfall                      | Problem                      | Solution                    |
+|------------------------------|------------------------------|------------------------------|
+| Over-tuning                  | Breaks self-tuning           | Start with defaults          |
+| Ignoring memory leaks        | GC cannot fix leaks          | Profile and fix app code     |
+| Undersized heap              | Excessive GC overhead        | Increase heap size           |
+| Oversized heap               | Long GC pauses (G1)          | Right-size or use ZGC        |
+| Explicit System.gc()         | Triggers unexpected Full GC  | Remove or disable            |
+| Finalizers                   | Delays object reclamation    | Use try-with-resources       |
+| Ignoring GC logs             | Problems go unnoticed        | Monitor in production        |
+
+
+### Memory Leak Detection  
+
+When GC cannot keep up, suspect a memory leak:  
+
+```java
+void main() {
+
+    // Common memory leak patterns to avoid:
+    
+    // 1. Static collections that grow unboundedly
+    // BAD: static List<Object> cache = new ArrayList<>();
+    
+    // 2. Listeners not removed
+    // BAD: eventSource.addListener(listener); // never removed
+    
+    // 3. Unclosed resources
+    // BAD: InputStream is = new FileInputStream(file); // never closed
+    
+    // GOOD: Use try-with-resources
+    // try (var is = new FileInputStream(file)) { ... }
+    
+    // 4. Custom caches without eviction
+    // BAD: Map<Key, Value> cache = new HashMap<>(); // grows forever
+    
+    // GOOD: Use bounded cache with eviction
+    // Map<Key, Value> cache = Collections.synchronizedMap(
+    //     new LinkedHashMap<>(100, 0.75f, true) {
+    //         protected boolean removeEldestEntry(Map.Entry e) {
+    //             return size() > 100;
+    //         }
+    //     }
+    // );
+    
+    IO.println("Memory leak patterns demonstrated (commented code)");
+}
+```
+
+
+### Profiling with JFR  
+
+Use Java Flight Recorder for detailed GC analysis:  
+
+```bash
+# Start recording with GC events
+java -XX:StartFlightRecording=duration=60s,filename=recording.jfr \
+     -jar application.jar
+
+# Or attach to running process
+jcmd <pid> JFR.start duration=60s filename=recording.jfr
+
+# Analyze with JDK Mission Control or programmatically
+```
+
+
+### Application-Level Optimizations  
+
+Reduce GC pressure through application design:  
+
+| Optimization                 | Description                                     |
+|------------------------------|------------------------------------------------|
+| Object pooling               | Reuse objects for frequently allocated types    |
+| Primitive arrays             | Use primitives instead of boxed types           |
+| StringBuilder                | Avoid string concatenation in loops             |
+| Lazy initialization          | Don't create objects until needed               |
+| Escape analysis              | Let JVM optimize short-lived local objects      |
+| Off-heap storage             | Use ByteBuffer for large data sets              |
+
+
+### Example: Reducing Allocation  
+
+This example demonstrates reducing object allocation:  
+
+```java
+void main() {
+
+    int iterations = 1_000_000;
+    
+    // Measure high-allocation approach
+    long start1 = System.nanoTime();
+    long sum1 = 0;
+    for (int i = 0; i < iterations; i++) {
+        // Creates new String each iteration
+        String s = "Value: " + i;
+        sum1 += s.length();
+    }
+    long time1 = System.nanoTime() - start1;
+    
+    // Measure low-allocation approach
+    long start2 = System.nanoTime();
+    long sum2 = 0;
+    var sb = new StringBuilder();
+    for (int i = 0; i < iterations; i++) {
+        sb.setLength(0);  // Reuse StringBuilder
+        sb.append("Value: ").append(i);
+        sum2 += sb.length();
+    }
+    long time2 = System.nanoTime() - start2;
+    
+    IO.println("High allocation: " + time1 / 1_000_000 + " ms");
+    IO.println("Low allocation:  " + time2 / 1_000_000 + " ms");
+    IO.println("Speedup: " + String.format("%.2fx", (double) time1 / time2));
+}
+```
+
+By reusing the StringBuilder, we eliminate millions of intermediate String  
+allocations, reducing GC pressure and improving performance.  
+
+
+## Conclusion  
+
+Garbage collection is fundamental to Java's memory management, and understanding  
+the available collectors is essential for building high-performance applications.  
+Modern Java provides a spectrum of collectors suited to different requirements:  
+
+**G1 GC** remains the default and best choice for most applications. It provides  
+a good balance between throughput and latency, with extensive tuning options for  
+specific workloads. Its predictable pause times and automatic optimization make  
+it suitable for everything from web services to batch processing.  
+
+**ZGC** represents the cutting edge of low-latency garbage collection. With  
+sub-millisecond pause times regardless of heap size, it is ideal for applications  
+where consistent response times are critical, such as financial trading systems,  
+real-time analytics, and large-scale data processing.  
+
+**Shenandoah** offers similar low-latency benefits to ZGC with a different  
+implementation approach. Its concurrent compaction and wide availability make  
+it a strong choice for applications requiring consistent performance without  
+the uncertainty of GC pauses.  
+
+**Epsilon** serves a unique niche for testing and benchmarking. By eliminating  
+GC entirely, it helps developers understand application behavior without GC  
+interference and is useful for short-lived processes that complete before  
+exhausting memory.  
+
+### Key Takeaways  
+
+| Principle                         | Description                               |
+|-----------------------------------|-------------------------------------------|
+| Start with defaults               | Modern collectors are well-tuned          |
+| Monitor before tuning             | Understand actual behavior first          |
+| Match GC to requirements          | Choose based on latency/throughput needs  |
+| Enable GC logging                 | Essential for production debugging        |
+| Fix application issues first      | GC cannot solve memory leaks              |
+| Test thoroughly                   | GC behavior varies with workload          |
+
+The evolution from early collectors to today's G1, ZGC, and Shenandoah  
+demonstrates the JVM's continued advancement in handling the demands of  
+modern applications. By understanding these collectors and following best  
+practices, developers can build Java applications that are both performant  
+and reliable.  
diff --git a/generics/ConsumerForEachEx.java b/generics/ConsumerForEachEx.java
index bd8bf167..ced150bc 100644
--- a/generics/ConsumerForEachEx.java
+++ b/generics/ConsumerForEachEx.java
@@ -1,27 +1,24 @@
-package com.zetcode;
 
-import java.util.List;
-import java.util.function.Consumer;
+void main() {
 
-public class ConsumerForEachEx {
+  var data = List.of(1, 2, 3, 4, 5, 6, 7);
 
-    public static void main(String[] args) {
+  // Consumer<Integer> consumer = (Integer x) -> IO::println(x);
+  Consumer<Integer> consumer = IO::println;
+  forEach(data, consumer);
 
-        var data = List.of(1, 2, 3, 4, 5, 6, 7);
+  IO.println("--------------------------");
+  forEach(data, IO::println);
 
-//      Consumer<Integer> consumer = (Integer x) ->  System.out.println(x);
-        Consumer<Integer> consumer = System.out::println;
-        forEach(data, consumer);
-
-        System.out.println("--------------------------");
-
-        forEach(data, System.out::println);
-    }
+  IO.println("--------------------------");
+  
+  var words = List.of("sky", "mark", "better", "rock");
+  forEach(words, IO::println);
+}
 
-    static <T> void forEach(List<T> data, Consumer<T> consumer) {
+<T> void forEach(List<T> data, Consumer<T> consumer) {
 
-        for (T t : data) {
-            consumer.accept(t);
-        }
-    }
+  for (T t : data) {
+    consumer.accept(t);
+  }
 }
diff --git a/generics/GenericArray2ListEx.java b/generics/GenericArray2ListEx.java
index 3e73da85..636458f3 100644
--- a/generics/GenericArray2ListEx.java
+++ b/generics/GenericArray2ListEx.java
@@ -1,29 +1,17 @@
-package com.zetcode;
 
-import java.util.Arrays;
-import java.util.List;
-import java.util.function.Function;
-import java.util.stream.Collectors;
+void main() {
 
-public class GenericArray2ListEx {
+  Integer[] vals = { 2, 4, 6, 8, 10, 12 };
+  Float[] vals2 = { 2.4f, 4.2f, 6.1f, 8.4f, 10.2f, 12.1f };
 
-    public static void main(String[] args) {
+  var myList = mapArrayToList(vals, e -> e * e);
+  System.out.println(myList);
 
-        Integer[] vals = {2, 4, 6, 8, 10, 12};
-        Float[] vals2 = {2.4f, 4.2f, 6.1f, 8.4f, 10.2f, 12.1f};
-
-        var myList = mapArrayToList(vals, e -> e * e);
-        System.out.println(myList);
-
-        var myList2 = mapArrayToList(vals2, e -> e * e);
-        System.out.println(myList2);
-    }
-
-    private static <T, R> List<R> mapArrayToList(T[] a, Function<T, R> mapFun) {
+  var myList2 = mapArrayToList(vals2, e -> e * e);
+  System.out.println(myList2);
+}
 
-        return Arrays.stream(a)
-                .map(mapFun)
-                .collect(Collectors.toList());
-    }
+<T, R> List<R> mapArrayToList(T[] a, Function<T, R> mapFun) {
 
+  return Arrays.stream(a).map(mapFun).collect(Collectors.toList());
 }
diff --git a/generics/GenericBoundedEx.java b/generics/GenericBoundedEx.java
index 415f1b3f..276ea146 100644
--- a/generics/GenericBoundedEx.java
+++ b/generics/GenericBoundedEx.java
@@ -1,77 +1,73 @@
-package com.zetcode;
 
 interface Item {
 
-    String info();
+  String info();
 }
 
 interface Plant {
 
-    String getColor();
+  String getColor();
 }
 
 class Bike implements Item {
 
-    @Override
-    public String info() {
+  @Override
+  public String info() {
 
-        return "This is a bike";
-    }
+    return "This is a bike";
+  }
 }
 
 class Chair implements Item {
 
-    @Override
-    public String info() {
+  @Override
+  public String info() {
 
-        return "This is a chair";
-    }
+    return "This is a chair";
+  }
 }
 
 class Flower implements Item, Plant {
 
-    private String color;
+  private String color;
 
-    public Flower(String color) {
-        this.color = color;
-    }
+  public Flower(String color) {
+    this.color = color;
+  }
 
-    public void setColor(String color) {
-        this.color = color;
-    }
+  public void setColor(String color) {
+    this.color = color;
+  }
 
-    @Override
-    public String getColor() {
-        return this.color;
-    }
+  @Override
+  public String getColor() {
+    return this.color;
+  }
 
-    @Override
-    public String info() {
+  @Override
+  public String info() {
 
-        return String.format("This is %s flower", this.color);
-    }
+    return String.format("This is %s flower", this.color);
+  }
 }
 
 // Generic bounded example
 
-public class GenericBoundedEx {
+void main() {
 
-    public static void main(String[] args) {
+  Chair chair = new Chair();
+  doInform2(chair);
 
-        Chair chair = new Chair();
-        doInform2(chair);
-        
-        Flower flower = new Flower("red");
-        doInform(flower);
-    }
+  Flower flower = new Flower("red");
+  doInform(flower);
+}
 
-    public static <T extends Item & Plant> void doInform(T item) {
+<T extends Item & Plant> void doInform(T item) {
 
-        System.out.println(item.info());
-    }
+  System.out.println(item.info());
+}
 
-    public static <T extends Item> void doInform2(T item) {
+<T extends Item> void doInform2(T item) {
 
-        System.out.println(item.info());
-    }
+  System.out.println(item.info());
 }
diff --git a/generics/GenericConcatListEx.java b/generics/GenericConcatListEx.java
index d0b927f4..c0c1f26e 100644
--- a/generics/GenericConcatListEx.java
+++ b/generics/GenericConcatListEx.java
@@ -1,37 +1,32 @@
-package com.zetcode;
 
-import java.util.ArrayList;
-import java.util.List;
+void main() {
 
-public class GenericConcatListEx {
+  var vals1 = List.of(1, 2, 3);
+  var vals2 = List.of(4, 5, 6);
+  var vals3 = List.of(7, 8, 9);
 
-    public static void main(String[] args) {
+  var vals = concatenate(vals1, vals2, vals3);
 
-        var vals1 = List.of(1, 2, 3);
-        var vals2 = List.of(4, 5, 6);
-        var vals3 = List.of(7, 8, 9);
+  IO.println(vals);
 
-        var vals = concatenate(vals1, vals2, vals3);
+  var words1 = List.of("pen", "paper", "ink");
+  var words2 = List.of("sky", "cloud", "wind");
+  var words3 = List.of("tree", "forest", "wood");
 
-        System.out.println(vals);
+  var words = concatenate(words1, words2, words3);
 
-        var words1 = List.of("pen", "paper", "ink");
-        var words2 = List.of("sky", "cloud", "wind");
-        var words3 = List.of("tree", "forest", "wood");
-
-        var words = concatenate(words1, words2, words3);
-
-        System.out.println(words);
-    }
+  IO.println(words);
+}
 
-    @SafeVarargs
-    private static <T> List<T> concatenate(List<T>... lists) {
-        return new ArrayList<>() {{
+@SafeVarargs
+final <T> List<T> concatenate(List<T>... lists) {
+  return new ArrayList<>() {
+    {
 
-            for (List<T> mylist : lists) {
+      for (List<T> mylist : lists) {
 
-                addAll(mylist);
-            }
-        }};
+        addAll(mylist);
+      }
     }
+  };
 }
diff --git a/generics/GenericMethodEx.java b/generics/GenericMethodEx.java
index cc8a7e19..63c66755 100644
--- a/generics/GenericMethodEx.java
+++ b/generics/GenericMethodEx.java
@@ -1,108 +1,100 @@
-package com.zetcode;
+class Car {
 
-import java.util.HashSet;
-import java.util.Objects;
-import java.util.Set;
+  private String name;
+  private int price;
 
-// Generic method
+  public Car(String name, int price) {
+    this.name = name;
+    this.price = price;
+  }
 
-class Car {
+  public String getName() {
+    return name;
+  }
 
-    private String name;
-    private int price;
+  public void setName(String name) {
+    this.name = name;
+  }
 
-    public Car(String name, int price) {
-        this.name = name;
-        this.price = price;
-    }
+  public int getPrice() {
+    return price;
+  }
 
-    public String getName() {
-        return name;
-    }
+  public void setPrice(int price) {
+    this.price = price;
+  }
 
-    public void setName(String name) {
-        this.name = name;
-    }
+  @Override
+  public String toString() {
+    return "Car{" + "name=" + name + ", price=" + price + '}';
+  }
 
-    public int getPrice() {
-        return price;
-    }
+  @Override
+  public int hashCode() {
+    int hash = 5;
+    hash = 79 * hash + Objects.hashCode(this.name);
+    hash = 79 * hash + this.price;
+    return hash;
+  }
 
-    public void setPrice(int price) {
-        this.price = price;
+  @Override
+  public boolean equals(Object obj) {
+    if (this == obj) {
+      return true;
     }
-
-    @Override
-    public String toString() {
-        return "Car{" + "name=" + name + ", price=" + price + '}';
+    if (obj == null) {
+      return false;
     }
-
-    @Override
-    public int hashCode() {
-        int hash = 5;
-        hash = 79 * hash + Objects.hashCode(this.name);
-        hash = 79 * hash + this.price;
-        return hash;
+    if (getClass() != obj.getClass()) {
+      return false;
     }
-
-    @Override
-    public boolean equals(Object obj) {
-        if (this == obj) {
-            return true;
-        }
-        if (obj == null) {
-            return false;
-        }
-        if (getClass() != obj.getClass()) {
-            return false;
-        }
-        final Car other = (Car) obj;
-        if (this.price != other.price) {
-            return false;
-        }
-        return Objects.equals(this.name, other.name);
+    final Car other = (Car) obj;
+    if (this.price != other.price) {
+      return false;
     }
+    return Objects.equals(this.name, other.name);
+  }
+
 }
 
-public class GenericMethodEx {
-
-    public static void main(String[] args) {
-        
-        Set<String> words = new HashSet<>();
-        words.add("blue");
-        words.add("pen");
-        words.add("dog");
-        words.add("narrow");
-        
-        Set<String> words2 = new HashSet<>();
-        words.add("blue");
-        words.add("pencil");
-        words.add("forest");
-        words.add("narrow");
-        
-        Set<String> res = union(words, words2);
-        System.out.println(res);
-        
-        Set<Car> cars = new HashSet<>();
-        cars.add(new Car("Volvo", 23144));
-        cars.add(new Car("Mazda", 20500));
-        cars.add(new Car("Mercedes", 50000));
-        
-        Set<Car> cars2 = new HashSet<>();
-        cars.add(new Car("Volvo", 23144));
-        cars.add(new Car("Mazda", 20500));
-        cars.add(new Car("Skoda", 9800));
-        
-        Set<Car> res2 = union(cars, cars2);
-        res2.forEach(System.out::println);
-        
-    }
-    
-    public static <E> Set<E> union(Set<E> s1, Set<E> s2) {
-        
-        Set<E> result = new HashSet<>(s1);
-        result.addAll(s2);
-        
-        return result;
-    }
+// Generic method
+
+void main() {
+
+  Set<String> words = new HashSet<>();
+  words.add("blue");
+  words.add("pen");
+  words.add("dog");
+  words.add("narrow");
+
+  Set<String> words2 = new HashSet<>();
+  words.add("blue");
+  words.add("pencil");
+  words.add("forest");
+  words.add("narrow");
+
+  Set<String> res = union(words, words2);
+  IO.println(res);
+
+  Set<Car> cars = new HashSet<>();
+  cars.add(new Car("Volvo", 23144));
+  cars.add(new Car("Mazda", 20500));
+  cars.add(new Car("Mercedes", 50000));
+
+  Set<Car> cars2 = new HashSet<>();
+  cars.add(new Car("Volvo", 23144));
+  cars.add(new Car("Mazda", 20500));
+  cars.add(new Car("Skoda", 9800));
+
+  Set<Car> res2 = union(cars, cars2);
+  res2.forEach(IO::println);
+
+}
+
+<E> Set<E> union(Set<E> s1, Set<E> s2) {
+
+  Set<E> result = new HashSet<>(s1);
+  result.addAll(s2);
+
+  return result;
 }
diff --git a/generics/GenericRandomValEx.java b/generics/GenericRandomValEx.java
index 37e0d0aa..a5ff2577 100644
--- a/generics/GenericRandomValEx.java
+++ b/generics/GenericRandomValEx.java
@@ -1,26 +1,19 @@
-package com.zetcode;
 
-import java.util.List;
-import java.util.Random;
+void main() {
 
-public class GenericRandomValEx {
+  var words = List.of("rock", "sky", "blue", "ocean", "falcon");
+  var vals = List.of(2, 3, 4, 5, 6, 7, 8);
 
-    public static void main(String[] args) {
+  var e1 = getRandomElement(words);
+  IO.println(e1);
 
-        var words = List.of("rock", "sky", "blue", "ocean", "falcon");
-        var vals = List.of(2, 3, 4, 5, 6, 7, 8);
-
-        var e1 = getRandomElement(words);
-        System.out.println(e1);
-
-        var e2 = getRandomElement(vals);
-        System.out.println(e2);
-    }
+  var e2 = getRandomElement(vals);
+  IO.println(e2);
+}
 
-    private static <T> T getRandomElement(List<T> list) {
+<T> T getRandomElement(List<T> list) {
 
-        var random = new Random();
-        int idx = random.nextInt(list.size());
-        return list.get(idx);
-    }
+  var random = new Random();
+  int idx = random.nextInt(list.size());
+  return list.get(idx);
 }
diff --git a/generics/GenericWildcardEx.java b/generics/GenericWildcardEx.java
index eab36ad3..6729c4b6 100644
--- a/generics/GenericWildcardEx.java
+++ b/generics/GenericWildcardEx.java
@@ -1,50 +1,41 @@
-package com.zetcode;
-
-import java.util.ArrayList;
-import java.util.List;
-
 abstract class Shape {
 
-    abstract void draw();
+  abstract void draw();
 }
 
 class Rectangle extends Shape {
 
-    @Override
-    void draw() {
-        System.out.println("Drawing rectangle");
-    }
+  @Override
+  void draw() {
+    IO.println("Drawing rectangle");
+  }
 }
 
 class Circle extends Shape {
 
-    @Override
-    void draw() {
-        System.out.println("Drawing circle");
-    }
+  @Override
+  void draw() {
+    IO.println("Drawing circle");
+  }
 }
 
 // Generic wildcard example
+void main() {
 
-public class GenericWildcardEx {
+  List<Rectangle> shapes1 = new ArrayList<>();
+  shapes1.add(new Rectangle());
 
-    public static void main(String[] args) {
-        
-        List<Rectangle> list1 = new ArrayList<>();
-        list1.add(new Rectangle());
+  List<Circle> shapes2 = new ArrayList<>();
+  shapes2.add(new Circle());
+  shapes2.add(new Circle());
 
-        List<Circle> list2 = new ArrayList<>();
-        list2.add(new Circle());
-        list2.add(new Circle());
+  drawShapes(shapes1);
+  drawShapes(shapes2);
+}
 
-        drawShapes(list1);
-        drawShapes(list2);
-    }
+void drawShapes(List<? extends Shape> lists) {
 
-    private static void drawShapes(List<? extends Shape> lists) {
-        
-        for (Shape s : lists) {
-            s.draw();
-        }
-    }
+  for (Shape s : lists) {
+    s.draw();
+  }
 }
diff --git a/generics/README.md b/generics/README.md
new file mode 100644
index 00000000..58907fd4
--- /dev/null
+++ b/generics/README.md
@@ -0,0 +1,15 @@
+# Covariance & Contravariance table
+
+| Feature | Covariance (Upper Bound) | Contravariance (Lower Bound) |
+| :--- | :--- | :--- |
+| **Common Name** | "Extends Wildcard" | "Super Wildcard" |
+| **Syntax** | `? extends T` | `? super T` |
+| **Example** | `List<? extends Number>` | `List<? super Integer>` |
+| **What It Means** | A list of *some unknown type* that is `T` or a **subtype** of `T`. | A list of *some unknown type* that is `T` or a **supertype** of `T`. |
+| **Type of Bound** | **Upper Bound** (`T` is the *highest* class in the hierarchy you can guarantee). | **Lower Bound** (`T` is the *lowest* class in the hierarchy you can guarantee). |
+| **Valid List Types** | `List<Number>`, `List<Integer>`, `List<Double>` | `List<Integer>`, `List<Number>`, `List<Object>` |
+| **Can you READ? (Get)** | **Yes.** You are guaranteed to get an object that is at least of type `T`. | **No** (safely). You can only be sure you're getting an `Object`, as you don't know how high up the superclass chain the list's type goes. |
+| **Can you WRITE? (Add)** | **No** (except `null`). You don't know the *specific* subtype. A `List<? extends Number>` could be a `List<Integer>`, so you can't add a `Double`. | **Yes.** You can safely add any object of type `T` (or its subtypes). A `List<Integer>`, `List<Number>`, or `List<Object>` can all safely accept an `Integer`. |
+| **PECS Mnemonic** | **P**roducer **E**xtends | **C**onsumer **S**uper |
+| **Primary Use Case** | When you are **reading** items *from* a generic structure (it *produces* items for you). | When you are **writing** items *to* a generic structure (it *consumes* items from you). |
+
diff --git a/generics/covariance-contravariance.md b/generics/covariance-contravariance.md
new file mode 100644
index 00000000..12324494
--- /dev/null
+++ b/generics/covariance-contravariance.md
@@ -0,0 +1,1091 @@
+# Covariance & Contravariance
+
+Covariance and contravariance are fundamental concepts in Java's type system  
+that describe how subtyping relationships between types relate to subtyping  
+relationships between more complex types constructed from them. Understanding  
+these concepts is essential for working effectively with Java generics,  
+especially when using wildcards.  
+
+**Covariance** refers to the ability to use a more derived type than originally  
+specified. In Java generics, this is achieved using upper-bounded wildcards  
+(`? extends T`). When a generic type is covariant, it preserves the ordering of  
+types: if `Dog` is a subtype of `Animal`, then `List<? extends Dog>` is a  
+"subtype" of `List<? extends Animal>`. Covariant types are producers - you can  
+read from them but generally cannot write to them (except null).  
+
+**Contravariance** refers to the ability to use a more generic (less derived)  
+type than originally specified. In Java generics, this is achieved using  
+lower-bounded wildcards (`? super T`). When a generic type is contravariant, it  
+reverses the ordering of types: if `Dog` is a subtype of `Animal`, then  
+`List<? super Dog>` is a "subtype" of `List<? super Animal>` in the opposite  
+direction. Contravariant types are consumers - you can write to them but can  
+only safely read Objects from them.  
+
+**Invariance** is the default behavior in Java generics. `List<Dog>` is not  
+considered a subtype of `List<Animal>`, even though `Dog` is a subtype of  
+`Animal`. This prevents type safety violations. Without wildcards, generic  
+types are invariant.  
+
+The **PECS principle** (Producer Extends, Consumer Super) is a helpful mnemonic:  
+use `? extends T` when you only read from a structure (it produces T instances),  
+and use `? super T` when you only write to a structure (it consumes T  
+instances). This principle guides the correct use of bounded wildcards to  
+achieve maximum flexibility while maintaining type safety.  
+
+
+## Covariance & Contravariance table
+
+| Feature | Covariance (Upper Bound) | Contravariance (Lower Bound) |
+| :--- | :--- | :--- |
+| **Common Name** | "Extends Wildcard" | "Super Wildcard" |
+| **Syntax** | `? extends T` | `? super T` |
+| **Example** | `List<? extends Number>` | `List<? super Integer>` |
+| **What It Means** | A list of *some unknown type* that is `T` or a **subtype** of `T`. | A list of *some unknown type* that is `T` or a **supertype** of `T`. |
+| **Type of Bound** | **Upper Bound** (`T` is the *highest* class in the hierarchy you can guarantee). | **Lower Bound** (`T` is the *lowest* class in the hierarchy you can guarantee). |
+| **Valid List Types** | `List<Number>`, `List<Integer>`, `List<Double>` | `List<Integer>`, `List<Number>`, `List<Object>` |
+| **Can you READ? (Get)** | **Yes.** You are guaranteed to get an object that is at least of type `T`. | **No** (safely). You can only be sure you're getting an `Object`, as you don't know how high up the superclass chain the list's type goes. |
+| **Can you WRITE? (Add)** | **No** (except `null`). You don't know the *specific* subtype. A `List<? extends Number>` could be a `List<Integer>`, so you can't add a `Double`. | **Yes.** You can safely add any object of type `T` (or its subtypes). A `List<Integer>`, `List<Number>`, or `List<Object>` can all safely accept an `Integer`. |
+| **PECS Mnemonic** | **P**roducer **E**xtends | **C**onsumer **S**uper |
+| **Primary Use Case** | When you are **reading** items *from* a generic structure (it *produces* items for you). | When you are **writing** items *to* a generic structure (it *consumes* items from you). |
+
+
+
+## Wildcards with upper bounds
+
+This example shows using wildcard types with upper bounds to accept lists of  
+subclasses.  
+
+```java
+abstract class Shape {
+
+  abstract void draw();
+}
+
+class Rectangle extends Shape {
+
+  @Override
+  void draw() {
+    IO.println("Drawing rectangle");
+  }
+}
+
+class Circle extends Shape {
+
+  @Override
+  void draw() {
+    IO.println("Drawing circle");
+  }
+}
+
+// Generic wildcard example
+void main() {
+
+  List<Rectangle> shapes1 = new ArrayList<>();
+  shapes1.add(new Rectangle());
+
+  List<Circle> shapes2 = new ArrayList<>();
+  shapes2.add(new Circle());
+  shapes2.add(new Circle());
+
+  drawShapes(shapes1);
+  drawShapes(shapes2);
+}
+
+void drawShapes(List<? extends Shape> lists) {
+
+  for (Shape s : lists) {
+    s.draw();
+  }
+}
+```
+
+The `drawShapes` method uses a bounded wildcard `? extends Shape` to accept  
+lists of any type that extends `Shape`. This demonstrates covariance - the  
+method can accept `List<Rectangle>`, `List<Circle>`, or `List<Shape>`. The  
+wildcard makes the method more flexible than `List<Shape>` alone, which would  
+not accept lists of subtypes. This is useful for read-only operations where  
+you need to process elements polymorphically without adding new elements.  
+
+
+## Reading with covariance
+
+This example demonstrates reading values from a covariant collection using  
+`? extends Number`.  
+
+```java
+void main() {
+
+  List<Integer> integers = List.of(1, 2, 3, 4, 5);
+  List<Double> doubles = List.of(1.1, 2.2, 3.3);
+
+  printNumbers(integers);
+  printNumbers(doubles);
+}
+
+void printNumbers(List<? extends Number> numbers) {
+
+  for (Number n : numbers) {
+    IO.println(n);
+  }
+}
+```
+
+The `printNumbers` method accepts any list containing Number or its subtypes.  
+We can safely read from the list because we know every element is at least a  
+Number. This demonstrates the producer aspect of covariance - the list produces  
+Number instances that we can read and use polymorphically.  
+
+
+## Sum calculation with covariance
+
+This example shows how covariance enables processing different numeric types  
+with a single method.  
+
+```java
+void main() {
+
+  List<Integer> scores = List.of(85, 92, 78, 95, 88);
+  List<Double> prices = List.of(19.99, 45.50, 12.75);
+
+  IO.println("Total scores: " + sum(scores));
+  IO.println("Total prices: " + sum(prices));
+}
+
+double sum(List<? extends Number> numbers) {
+
+  double total = 0;
+  for (Number n : numbers) {
+    total += n.doubleValue();
+  }
+  return total;
+}
+```
+
+The sum method works with any list of numbers by reading values and converting  
+them to double. This shows how covariance allows writing flexible utility  
+methods that operate on collections of different numeric types. The wildcard  
+enables code reuse across Integer, Double, Float, and other Number subtypes.  
+
+
+## Finding maximum with covariance
+
+This example uses covariance with Comparable to find the maximum element in  
+collections of different types.  
+
+```java
+void main() {
+
+  List<Integer> numbers = List.of(5, 2, 9, 1, 7);
+  List<String> words = List.of("apple", "zebra", "banana");
+
+  IO.println("Max number: " + findMax(numbers));
+  IO.println("Max word: " + findMax(words));
+}
+
+<T extends Comparable<T>> T findMax(List<? extends T> list) {
+
+  T max = list.getFirst();
+  for (T element : list) {
+    if (element.compareTo(max) > 0) {
+      max = element;
+    }
+  }
+  return max;
+}
+```
+
+The generic method uses both a type parameter bound and a covariant wildcard.  
+The bound ensures T is Comparable, while the wildcard allows accepting lists  
+of T or its subtypes. This combination provides type safety while maintaining  
+flexibility for reading and comparing elements.  
+
+
+## Writing with contravariance
+
+This example demonstrates writing values to a contravariant collection using  
+`? super Integer`.  
+
+```java
+void main() {
+
+  List<Integer> integers = new ArrayList<>();
+  List<Number> numbers = new ArrayList<>();
+  List<Object> objects = new ArrayList<>();
+
+  addIntegers(integers);
+  addIntegers(numbers);
+  addIntegers(objects);
+
+  IO.println("Integers: " + integers);
+  IO.println("Numbers: " + numbers);
+  IO.println("Objects: " + objects);
+}
+
+void addIntegers(List<? super Integer> list) {
+
+  list.add(1);
+  list.add(2);
+  list.add(3);
+}
+```
+
+The `addIntegers` method accepts any list that can hold Integer or its  
+supertypes. We can safely write Integer values because any supertype  
+(Number, Object) can hold an Integer. This demonstrates the consumer aspect  
+of contravariance - the list consumes Integer instances that we provide.  
+
+
+## Comparator with contravariance
+
+This example shows using contravariant wildcards with Comparator to sort  
+different types.  
+
+```java
+import java.util.Comparator;
+
+void main() {
+
+  List<Integer> numbers = new ArrayList<>(List.of(5, 2, 9, 1));
+  Comparator<Object> objectComparator = (a, b) ->
+      a.toString().compareTo(b.toString());
+
+  sortList(numbers, objectComparator);
+  IO.println("Sorted: " + numbers);
+}
+
+<T> void sortList(List<T> list, Comparator<? super T> comparator) {
+
+  list.sort(comparator);
+}
+```
+
+The sortList method accepts a Comparator for T or any supertype of T. This  
+allows using a more general comparator (like one for Object) to sort more  
+specific types (like Integer). Contravariance here enables flexible comparison  
+strategies while maintaining type safety.  
+
+
+## PECS principle demonstration
+
+This example demonstrates the PECS principle by copying elements from a  
+producer to a consumer.  
+
+```java
+void main() {
+
+  List<Integer> source = List.of(1, 2, 3, 4, 5);
+  List<Number> destination = new ArrayList<>();
+
+  copy(source, destination);
+  IO.println("Destination: " + destination);
+}
+
+<T> void copy(List<? extends T> src, List<? super T> dest) {
+
+  for (T item : src) {
+    dest.add(item);
+  }
+}
+```
+
+The copy method demonstrates PECS: the source uses `? extends T` (producer)  
+because we read from it, and the destination uses `? super T` (consumer)  
+because we write to it. This allows copying from List<Integer> to List<Number>,  
+which wouldn't be possible without wildcards due to invariance.  
+
+
+## Array covariance
+
+This example shows that arrays in Java are covariant, unlike generic  
+collections.  
+
+```java
+void main() {
+
+  Integer[] integers = {1, 2, 3};
+  Number[] numbers = integers;
+
+  IO.println("First number: " + numbers[0]);
+
+  try {
+    numbers[0] = 3.14;
+  } catch (ArrayStoreException e) {
+    IO.println("Cannot store Double in Integer array: " + e.getMessage());
+  }
+}
+```
+
+Arrays are covariant, meaning Integer[] is a subtype of Number[]. However,  
+this leads to runtime errors when trying to store incompatible types. The JVM  
+performs runtime checks to prevent storing the wrong type, throwing  
+ArrayStoreException. Generics avoid this with compile-time checking.  
+
+
+## Generic collections are invariant
+
+This example demonstrates that generic collections are invariant by default,  
+requiring wildcards for flexibility.  
+
+```java
+void main() {
+
+  List<Integer> integers = List.of(1, 2, 3);
+
+  // This would not compile without wildcards:
+  // processNumbers(integers);  // Error!
+
+  processNumbersWithWildcard(integers);
+}
+
+void processNumbersWithWildcard(List<? extends Number> numbers) {
+
+  for (Number n : numbers) {
+    IO.println(n.doubleValue());
+  }
+}
+```
+
+Unlike arrays, List<Integer> is not a subtype of List<Number> due to  
+invariance. This prevents unsafe operations at compile time. Using wildcards  
+(`? extends Number`) explicitly enables covariance when needed for read  
+operations, providing type safety without runtime checks.  
+
+
+## Bounded wildcards in return types
+
+This example shows using bounded wildcards in method return types to provide  
+flexibility to callers.  
+
+```java
+void main() {
+
+  List<? extends Number> evenNumbers = getEvenNumbers();
+  List<? extends Number> primeNumbers = getPrimeNumbers();
+
+  IO.println("Even numbers: " + evenNumbers);
+  IO.println("Prime numbers: " + primeNumbers);
+}
+
+List<? extends Number> getEvenNumbers() {
+
+  return List.of(2, 4, 6, 8, 10);
+}
+
+List<? extends Number> getPrimeNumbers() {
+
+  return List.of(2, 3, 5, 7, 11);
+}
+```
+
+Methods can return bounded wildcards to allow flexibility in implementation  
+while constraining the type for clients. The caller knows they'll get some  
+kind of Number list and can read from it safely. This pattern is useful when  
+the exact type returned might vary or be implementation-specific.  
+
+
+## Multiple type parameters with wildcards
+
+This example demonstrates using wildcards with multiple type parameters in a  
+generic class.  
+
+```java
+record Pair<K, V>(K key, V value) {}
+
+void main() {
+
+  Pair<Integer, String> pair1 = new Pair<>(1, "one");
+  Pair<Integer, Double> pair2 = new Pair<>(2, 2.0);
+
+  printPair(pair1);
+  printPair(pair2);
+}
+
+void printPair(Pair<? extends Number, ?> pair) {
+
+  IO.println("Key: " + pair.key() + ", Value: " + pair.value());
+}
+```
+
+The printPair method uses wildcards on multiple type parameters independently.  
+The key is bounded to Number subtypes while the value is unbounded (any type).  
+This shows how wildcards can be applied selectively to different type  
+parameters based on what operations you need to perform.  
+
+
+## Contravariance with collections addAll
+
+This example shows how contravariant wildcards enable flexible collection  
+operations like addAll.  
+
+```java
+void main() {
+
+  List<Integer> integers = new ArrayList<>(List.of(1, 2, 3));
+  List<Number> moreNumbers = List.of(4.5, 5L, 6);
+
+  addAll(integers, List.of(4, 5, 6));
+  IO.println("Integers: " + integers);
+}
+
+<T> void addAll(List<? super T> dest, List<? extends T> src) {
+
+  for (T item : src) {
+    dest.add(item);
+  }
+}
+```
+
+This mimics the signature of Collection.addAll, using both covariance and  
+contravariance. The source is covariant (producer) and destination is  
+contravariant (consumer), following PECS. This allows adding from a more  
+specific list to a more general list while maintaining type safety.  
+
+
+## Unbounded wildcards
+
+This example demonstrates using unbounded wildcards when you don't need to  
+know the specific type.  
+
+```java
+void main() {
+
+  List<Integer> integers = List.of(1, 2, 3);
+  List<String> strings = List.of("a", "b", "c");
+  List<Double> doubles = List.of(1.1, 2.2);
+
+  IO.println("Size: " + getSize(integers));
+  IO.println("Size: " + getSize(strings));
+  IO.println("Size: " + getSize(doubles));
+}
+
+int getSize(List<?> list) {
+
+  return list.size();
+}
+```
+
+The unbounded wildcard `?` means "list of unknown type". This is useful when  
+you only need operations that don't depend on the element type, like getting  
+size or checking emptiness. It's more flexible than Object and represents  
+true ignorance of the type parameter.  
+
+
+## Wildcard capture
+
+This example shows the wildcard capture helper method pattern for working  
+with wildcards.  
+
+```java
+void main() {
+
+  List<Integer> integers = new ArrayList<>();
+  integers.add(1);
+  integers.add(2);
+  integers.add(3);
+
+  reverse(integers);
+  
+  IO.println("Reversed: " + integers);
+}
+
+void reverse(List<?> list) {
+
+  reverseHelper(list);
+}
+
+<T> void reverseHelper(List<T> list) {
+
+  int size = list.size();
+  for (int i = 0; i < size / 2; i++) {
+    T temp = list.get(i);
+    list.set(i, list.get(size - 1 - i));
+    list.set(size - 1 - i, temp);
+  }
+}
+```
+
+The wildcard capture pattern uses a helper method with a type parameter to  
+"capture" the unknown type from a wildcard. This allows operations that  
+require knowing the type is consistent (like swapping elements) while still  
+accepting any list type. The helper captures the wildcard into a concrete type.  
+
+
+## Generic method with bounded wildcards
+
+This example shows using bounded wildcards as method parameters in a generic  
+method.  
+
+```java
+void main() {
+
+  List<Integer> integers = List.of(10, 20, 30);
+  List<Double> doubles = List.of(1.5, 2.5, 3.5);
+
+  IO.println("Contains 20: " + contains(integers, 20));
+  IO.println("Contains 2.5: " + contains(doubles, 2.5));
+}
+
+<T> boolean contains(List<? extends T> list, T element) {
+
+  for (T item : list) {
+    if (item.equals(element)) {
+      return true;
+    }
+  }
+  return false;
+}
+```
+
+The contains method combines a type parameter with a covariant wildcard. The  
+type parameter T is inferred from the element being searched, and the list  
+can be of T or any subtype. This provides flexibility while ensuring the  
+search element is compatible with the list contents.  
+
+
+## Contravariance with functional interfaces
+
+This example demonstrates contravariance with Consumer functional interface.  
+
+```java
+import java.util.function.Consumer;
+
+void main() {
+
+  Consumer<Object> objectConsumer = obj -> IO.println("Object: " + obj);
+  Consumer<Number> numberConsumer = num -> IO.println("Number: " + num);
+
+  processList(List.of(1, 2, 3), objectConsumer);
+  processList(List.of(1, 2, 3), numberConsumer);
+}
+
+<T> void processList(List<T> list, Consumer<? super T> consumer) {
+
+  for (T item : list) {
+    consumer.accept(item);
+  }
+}
+```
+
+The processList method accepts a Consumer for T or any supertype. This allows  
+using more general consumers (like Consumer<Object>) with more specific types  
+(like Integer). Contravariance in functional interfaces enables flexible  
+callback mechanisms while maintaining type safety.  
+
+
+## Covariance with Stream operations
+
+This example shows how covariance works naturally with Stream API operations.  
+
+```java
+import java.util.stream.Stream;
+
+void main() {
+
+  List<Integer> integers = List.of(1, 2, 3, 4, 5);
+
+  double average = calculateAverage(integers);
+  IO.println("Average: " + average);
+}
+
+double calculateAverage(List<? extends Number> numbers) {
+
+  return numbers.stream()
+      .mapToDouble(Number::doubleValue)
+      .average()
+      .orElse(0.0);
+}
+```
+
+The calculateAverage method uses covariance to accept any list of numbers and  
+processes them using streams. The covariant wildcard allows the method to work  
+with Integer, Double, Long, etc. This demonstrates how wildcards integrate  
+seamlessly with modern Java APIs like streams.  
+
+
+## Multiple bounds with extends
+
+This example demonstrates using multiple bounds in a generic method to  
+constrain type parameters.  
+
+```java
+interface Printable {
+  String toPrintFormat();
+}
+
+record Document(String title, int pages) implements Comparable<Document>,
+    Printable {
+
+  @Override
+  public int compareTo(Document other) {
+    return Integer.compare(this.pages, other.pages);
+  }
+
+  @Override
+  public String toPrintFormat() {
+    return title + " (" + pages + " pages)";
+  }
+}
+
+void main() {
+
+  List<Document> docs = List.of(
+      new Document("Manual", 50),
+      new Document("Guide", 30)
+  );
+
+  processItems(docs);
+}
+
+<T extends Comparable<T> & Printable> void processItems(List<T> items) {
+
+  var sorted = items.stream().sorted().toList();
+  for (T item : sorted) {
+    IO.println(item.toPrintFormat());
+  }
+}
+```
+
+The processItems method requires T to implement both Comparable and Printable  
+using the `&` syntax for multiple bounds. This ensures compile-time safety for  
+operations requiring both interfaces. Multiple bounds enable writing methods  
+that depend on multiple capabilities of the type parameter.  
+
+
+## Nested wildcards
+
+This example shows using wildcards within wildcards for nested generic  
+structures.  
+
+```java
+void main() {
+
+  List<List<Integer>> intLists = List.of(
+      List.of(1, 2, 3),
+      List.of(4, 5, 6)
+  );
+
+  List<List<Double>> doubleLists = List.of(
+      List.of(1.1, 2.2),
+      List.of(3.3, 4.4)
+  );
+
+  printNested(intLists);
+  printNested(doubleLists);
+}
+
+void printNested(List<? extends List<? extends Number>> lists) {
+
+  for (List<? extends Number> list : lists) {
+    for (Number num : list) {
+      IO.print(num + " ");
+    }
+    IO.println();
+  }
+}
+```
+
+Nested wildcards allow working with complex nested generic structures. The  
+outer wildcard allows lists of different List types, while the inner wildcard  
+allows lists containing different Number types. This pattern is useful for  
+processing hierarchical or nested data structures flexibly.  
+
+
+## Generic builder pattern with wildcards
+
+This example demonstrates using wildcards in a builder pattern for flexible  
+object construction.  
+
+```java
+class Builder<T> {
+
+  private List<T> items = new ArrayList<>();
+
+  Builder<T> addAll(List<? extends T> newItems) {
+    items.addAll(newItems);
+    return this;
+  }
+
+  List<T> build() {
+    return new ArrayList<>(items);
+  }
+}
+
+void main() {
+
+  List<Integer> integers = List.of(1, 2, 3);
+  List<Number> numbers = new Builder<Number>()
+      .addAll(integers)
+      .addAll(List.of(4.5, 5.5))
+      .build();
+
+  IO.println("Built list: " + numbers);
+}
+```
+
+The builder's addAll method uses covariance to accept lists of T or subtypes,  
+enabling flexible construction. This allows adding Integer lists to a  
+Number builder, or Double lists, making the builder more versatile. Wildcards  
+in builders enable fluent APIs that work with type hierarchies.  
+
+
+## Type inference with wildcards
+
+This example shows how Java's type inference works with bounded wildcards in  
+method calls.  
+
+```java
+void main() {
+
+  var result1 = merge(List.of(1, 2, 3), List.of(4, 5));
+  var result2 = merge(List.of("a", "b"), List.of("c", "d"));
+
+  IO.println("Merged integers: " + result1);
+  IO.println("Merged strings: " + result2);
+}
+
+<T> List<T> merge(List<? extends T> list1, List<? extends T> list2) {
+
+  List<T> result = new ArrayList<>();
+  result.addAll(list1);
+  result.addAll(list2);
+  return result;
+}
+```
+
+The merge method uses covariant wildcards on both parameters, and the compiler  
+infers T from the common supertype. This allows merging lists of the same type  
+or compatible types. Type inference with wildcards reduces verbosity while  
+maintaining type safety.  
+
+
+## Contravariance with Predicate
+
+This example demonstrates using contravariant wildcards with Predicate  
+functional interface.  
+
+```java
+import java.util.function.Predicate;
+
+void main() {
+
+  Predicate<Object> notNull = obj -> obj != null;
+  List<String> strings = List.of("hello", "world");
+
+  var filtered = filter(strings, notNull);
+  IO.println("Filtered: " + filtered);
+}
+
+<T> List<T> filter(List<T> list, Predicate<? super T> predicate) {
+
+  return list.stream()
+      .filter(predicate)
+      .toList();
+}
+```
+
+The filter method accepts a Predicate for T or any supertype, following  
+contravariance for consumers. This allows using more general predicates  
+(like checking for null on Object) with more specific types (like String).  
+Contravariant functional interfaces enable code reuse across type hierarchies.  
+
+
+## Covariance with Optional
+
+This example shows using covariant wildcards with Optional to handle different  
+numeric types.  
+
+```java
+import java.util.Optional;
+
+void main() {
+
+  Optional<Integer> intOpt = Optional.of(42);
+  Optional<Double> doubleOpt = Optional.of(3.14);
+
+  IO.println("Integer value: " + getValue(intOpt));
+  IO.println("Double value: " + getValue(doubleOpt));
+}
+
+double getValue(Optional<? extends Number> optional) {
+
+  return optional
+      .map(Number::doubleValue)
+      .orElse(0.0);
+}
+```
+
+The getValue method uses covariance to accept Optional of any Number subtype.  
+This demonstrates how wildcards work with wrapper types like Optional,  
+allowing flexible handling of different numeric types. Covariance with  
+Optional enables generic utility methods for wrapped values.  
+
+
+## Combining covariance and contravariance
+
+This example shows using both covariance and contravariance in a single  
+method for maximum flexibility.  
+
+```java
+import java.util.function.Function;
+
+void main() {
+
+  List<Integer> integers = List.of(1, 2, 3);
+  Function<Number, String> formatter = n -> "Value: " + n;
+
+  var result = transform(integers, formatter);
+  IO.println("Transformed: " + result);
+}
+
+<T, R> List<R> transform(
+    List<? extends T> source,
+    Function<? super T, ? extends R> mapper) {
+
+  List<R> result = new ArrayList<>();
+  for (T item : source) {
+    result.add(mapper.apply(item));
+  }
+  return result;
+}
+```
+
+The transform method demonstrates PECS on both parameters: source is covariant  
+(producer), and mapper's input is contravariant (consumer) while its output is  
+covariant (producer). This combination provides maximum flexibility, allowing  
+the most general possible types for both input and transformation.  
+
+
+## Wildcards with Set operations
+
+This example demonstrates using wildcards for set operations like union and  
+intersection.  
+
+```java
+void main() {
+
+  Set<Integer> set1 = Set.of(1, 2, 3, 4);
+  Set<Integer> set2 = Set.of(3, 4, 5, 6);
+
+  var unionSet = union(set1, set2);
+  var intersectionSet = intersection(set1, set2);
+
+  IO.println("Union: " + unionSet);
+  IO.println("Intersection: " + intersectionSet);
+}
+
+<T> Set<T> union(Set<? extends T> set1, Set<? extends T> set2) {
+
+  Set<T> result = new HashSet<>(set1);
+  result.addAll(set2);
+  return result;
+}
+
+<T> Set<T> intersection(Set<? extends T> set1, Set<? extends T> set2) {
+
+  Set<T> result = new HashSet<>(set1);
+  result.retainAll(set2);
+  return result;
+}
+```
+
+Set operations use covariant wildcards to accept sets of T or subtypes. This  
+allows combining sets of the same type or compatible types. The wildcards  
+enable mathematical set operations while maintaining type safety and  
+flexibility in the input types.  
+
+
+## Wildcards with Map
+
+This example shows using wildcards with Map for flexible key-value operations.  
+
+```java
+void main() {
+
+  Map<String, Integer> scores = Map.of("Alice", 95, "Bob", 87);
+  Map<String, Double> prices = Map.of("Apple", 1.99, "Banana", 0.59);
+
+  printMap(scores);
+  printMap(prices);
+}
+
+<K, V> void printMap(Map<? extends K, ? extends V> map) {
+
+  map.forEach((key, value) ->
+      IO.println(key + ": " + value)
+  );
+}
+```
+
+The printMap method uses covariant wildcards for both keys and values,  
+allowing it to accept maps with different value types. This demonstrates how  
+wildcards work with multi-parameter generic types. The method can read from  
+any map regardless of the specific key and value types.  
+
+
+## Generic method reference with wildcards
+
+This example demonstrates using method references with bounded wildcards.  
+
+```java
+void main() {
+
+  List<String> words = List.of("hello", "world", "java");
+  List<Integer> numbers = List.of(1, 2, 3, 4, 5);
+
+  process(words, String::toUpperCase);
+  process(numbers, Object::toString);
+}
+
+<T, R> void process(List<T> list, Function<? super T, R> mapper) {
+
+  list.stream()
+      .map(mapper)
+      .forEach(IO::println);
+}
+```
+
+The process method accepts a Function with contravariant input type, allowing  
+method references from supertypes. This enables using Object::toString on any  
+type or String::toUpperCase on strings. Contravariant wildcards with method  
+references provide flexible function composition.  
+
+
+## Recursive type bounds
+
+This example demonstrates using recursive type bounds with wildcards for  
+type-safe comparisons.  
+
+```java
+record Person(String name, int age) implements Comparable<Person> {
+
+  @Override
+  public int compareTo(Person other) {
+    return Integer.compare(this.age, other.age);
+  }
+}
+
+void main() {
+
+  List<Person> people = List.of(
+      new Person("Alice", 30),
+      new Person("Bob", 25),
+      new Person("Charlie", 35)
+  );
+
+  var oldest = findMaxElement(people);
+  IO.println("Oldest: " + oldest);
+}
+
+<T extends Comparable<? super T>> T findMaxElement(List<? extends T> list) {
+
+  T max = list.getFirst();
+  for (T element : list) {
+    if (element.compareTo(max) > 0) {
+      max = element;
+    }
+  }
+  return max;
+}
+```
+
+The recursive bound `T extends Comparable<? super T>` allows T to be compared  
+with its supertypes, not just itself. This is more flexible than  
+`Comparable<T>` and matches how many Java classes implement Comparable. The  
+covariant list parameter adds additional flexibility for inputs.  
+
+
+## Common pitfalls with wildcards
+
+This example demonstrates common mistakes when working with wildcards and how  
+to avoid them.  
+
+```java
+void main() {
+
+  List<Integer> integers = List.of(1, 2, 3);
+
+  // This demonstrates what NOT to do
+  demonstratePitfalls(integers);
+
+  // Correct approach
+  demonstrateCorrectUsage(integers);
+}
+
+void demonstratePitfalls(List<? extends Number> numbers) {
+
+  // Cannot add to covariant list (except null)
+  // numbers.add(42);  // Compile error!
+  // numbers.add(3.14);  // Compile error!
+
+  Number first = numbers.getFirst();
+  IO.println("Can read: " + first);
+}
+
+void demonstrateCorrectUsage(List<Integer> integers) {
+
+  // Use specific type when you need to add
+  List<Number> numbers = new ArrayList<>();
+  numbers.addAll(integers);
+  numbers.add(3.14);
+
+  IO.println("Correct: " + numbers);
+}
+```
+
+This example shows that you cannot add elements to a covariant list  
+(`? extends T`) because the compiler doesn't know the exact subtype. The  
+solution is to use the specific type when additions are needed, or use  
+contravariant wildcards (`? super T`) for consumer scenarios. Understanding  
+these limitations prevents compile errors.  
+
+
+## Wildcard guidelines and best practices
+
+This example demonstrates best practices for choosing between different  
+wildcard types.  
+
+```java
+void main() {
+
+  List<Integer> source = List.of(1, 2, 3, 4, 5);
+  List<Number> target = new ArrayList<>();
+
+  // Best practice: Use PECS
+  copyWithPECS(source, target);
+  IO.println("Copied: " + target);
+
+  // Reading only: use extends
+  double sum = sumNumbers(source);
+  IO.println("Sum: " + sum);
+
+  // Writing only: use super
+  List<Object> objects = new ArrayList<>();
+  addNumbers(objects);
+  IO.println("Objects: " + objects);
+}
+
+<T> void copyWithPECS(List<? extends T> src, List<? super T> dest) {
+
+  dest.addAll(src);
+}
+
+double sumNumbers(List<? extends Number> numbers) {
+
+  return numbers.stream()
+      .mapToDouble(Number::doubleValue)
+      .sum();
+}
+
+void addNumbers(List<? super Integer> list) {
+
+  for (int i = 1; i <= 5; i++) {
+    list.add(i);
+  }
+}
+```
+
+This example codifies best practices: use `? extends T` for producers (reading),  
+`? super T` for consumers (writing), and combine them when both operations are  
+needed (PECS principle). Following these guidelines results in flexible,  
+type-safe APIs that work naturally with Java's type system and provide maximum  
+usability for clients.  
diff --git a/gradle.md b/gradle.md
new file mode 100644
index 00000000..42916ab5
--- /dev/null
+++ b/gradle.md
@@ -0,0 +1,92 @@
+# Gradle 
+
+
+## Executable JAR
+
+*With plain JAR plugin:*
+
+This is the default Gradle task for creating a JAR archive. It packages your  
+compiled class files (*.class) and resources from your project into a single JAR  
+file.  
+
+It does not include any dependencies in the JAR. Your application needs the  
+libraries it depends on to be installed separately on the target system.  
+
+```gradle
+plugins {
+    id 'java'
+    id 'application'
+}
+
+group = 'com.zetcode'
+version = '1.0-SNAPSHOT'
+
+repositories {
+    mavenCentral()
+}
+
+application {
+    mainClass = 'com.zetcode.Main'
+}
+
+jar {
+    duplicatesStrategy(DuplicatesStrategy.EXCLUDE)
+    manifest {
+        attributes(
+                'Main-Class': 'com.zetcode.Main'
+        )
+    }
+    from {
+        configurations.runtimeClasspath.collect { it.isDirectory() ? it : zipTree(it) }
+    }
+}
+```
+
+*With shadow JAR plugin:*  
+
+It creates a fat JAR or shadow JAR, which is a single JAR containing your  
+application code and all its transitive dependencies.  
+
+It makes deployment easier as you only need to distribute the single JAR file  
+containing everything your application needs. The JAR file will be larger due to  
+the inclusion of all dependencies.  
+
+
+```gradle
+plugins {
+    id 'java'
+    id 'application'
+    id 'io.github.goooler.shadow' version '8.1.8'
+}
+
+group = 'com.zetcode'
+version = '1.0-SNAPSHOT'
+
+repositories {
+    mavenCentral()
+}
+
+application {
+    mainClass = 'com.zetcode.Main'
+}
+
+dependencies {
+    implementation 'org.eclipse.collections:eclipse-collections:11.1.0'
+}
+
+jar {
+//    duplicatesStrategy = DuplicatesStrategy.EXCLUDE
+    duplicatesStrategy(DuplicatesStrategy.EXCLUDE)
+    exclude 'META-INF/*.RSA', 'META-INF/*.SF', 'META-INF/*.DSA'
+    manifest {
+        attributes(
+                'Main-Class': 'com.zetcode.Main'
+        )
+    }
+    from {
+        configurations.runtimeClasspath.collect { it.isDirectory() ? it : zipTree(it) }
+    }
+}
+```
+
+
diff --git a/hash_code.md b/hash_code.md
new file mode 100644
index 00000000..28e37201
--- /dev/null
+++ b/hash_code.md
@@ -0,0 +1,241 @@
+# hashCode/equals contract
+
+The **hashCode/equals contract** in Java is a set of rules that governs the  
+behavior of the `hashCode` and `equals` methods, as defined in the `Object`  
+class, to ensure consistent and correct behavior in hash-based collections like  
+`HashSet` and `HashMap`. These methods must work together cohesively, as they  
+are used to determine object equality and hash-based storage. The contract  
+combines requirements for both methods, primarily from the `Object.hashCode` and  
+`Object.equals` documentation.  
+
+## Reasons of the contract
+
+The hashCode/equals contract is needed because hash-based collections optimize  
+performance using hash tables, relying on `hashCode` for fast bucket placement and  
+equals for collision resolution and duplicate checks. The contract ensures  
+consistency, equal objects sharing hash codes, and proper equality behavior,  
+enabling O(1) operations and preventing errors like duplicates or failed  
+lookups. In the `Thing` class later in the example, the mutable name field risks  
+breaking this contract, as changing it disrupts the hash table’s optimizations,  
+potentially causing duplicates or lookup failures in the HashSet. The contract is  
+critical to maintain the efficiency and correctness of these optimizations.    
+
+  
+## HashCode/Equals Contract Rules  
+  
+1. **Consistency**:  
+   - The `hashCode` method must consistently return the same integer for an  
+     object during a single execution of a Java application, provided no fields  
+     used in `hashCode` or `equals` are modified.  
+   - The `equals` method must also be consistent, returning the same result for  
+     the same pair of objects as long as their relevant fields remain unchanged.  
+   - **Implication**: Both methods should produce predictable results to ensure  
+     reliable behavior in collections. For example, an object’s hash code  
+     shouldn’t change unless its state (relevant to `equals`) changes.  
+  
+2. **Equality Implies Same Hash Code**:  
+   - If two objects are equal according to the `equals` method, they must return  
+     the same hash code via `hashCode`.  
+   - **Implication**: If `a.equals(b)` returns `true`, then `a.hashCode()` must  
+     equal `b.hashCode()`. This ensures that equal objects are placed in the  
+     same hash bucket in collections like `HashSet` or `HashMap`, preventing  
+     issues like duplicates or lookup failures.  
+  
+3. **Non-Equal Objects May Have Same Hash Code**:  
+   - If two objects are not equal according to `equals`, they are not required  
+     to have different hash codes, but ideally, they should to minimize hash  
+     collisions.  
+   - **Implication**: While distinct objects can share the same hash code (a  
+     collision), a well-designed `hashCode` method distributes hash codes evenly  
+     to optimize performance in hash-based collections.  
+  
+4. **Reflexivity, Symmetry, and Transitivity of `equals`**:  
+   - **Reflexivity**: For any non-null object `x`, `x.equals(x)` must return  
+     `true`.  
+   - **Symmetry**: For any non-null objects `x` and `y`, if `x.equals(y)`  
+     returns `true`, then `y.equals(x)` must also return `true`.  
+   - **Transitivity**: For any non-null objects `x`, `y`, and `z`, if  
+     `x.equals(y)` returns `true` and `y.equals(z)` returns `true`, then  
+     `x.equals(z)` must return `true`.  
+   - **Implication**: These properties ensure `equals` behaves like a proper  
+     equivalence relation, which is critical for consistent behavior in  
+     collections.  
+  
+5. **Null Handling in `equals`**:  
+   - For any non-null object `x`, `x.equals(null)` must return `false`.  
+   - **Implication**: This prevents `NullPointerException`s and ensures `equals`  
+     handles null comparisons correctly.  
+  
+### Additional Notes  
+  
+- **Consistency Between `hashCode` and `equals`**: The fields used in `equals`  
+  to determine equality should be the same as those used in `hashCode`. If  
+  `equals` compares certain fields, `hashCode` must compute its value based on  
+  those same fields to maintain the contract.  
+- **Immutability**: Fields used in `hashCode` and `equals` should ideally be  
+  immutable to prevent changes after an object is added to a hash-based  
+  collection. Modifying these fields (e.g., `name` in the provided `Thing`  
+  class) can break the contract, causing issues like duplicates or lookup  
+  failures.  
+- **Default Implementations**:  
+  - `Object.equals` checks for reference equality (`==`), which is insufficient  
+    for content-based comparison.  
+  - `Object.hashCode` returns a value based on the object’s memory address,  
+    which is inconsistent with a custom `equals` based on fields.  
+  - Custom implementations (like in the `Thing` class) override these to base  
+    equality and hash codes on object content (e.g., `name`).  
+  
+## Example from Provided Code  
+
+In the `Thing` class:  
+  
+```java  
+@Override  
+public int hashCode() {  
+    return name.hashCode();  
+}  
+@Override  
+public boolean equals(Object obj) {  
+  
+    if (this == obj) return true;  
+    if (!(obj instanceof Thing)) return false;  
+    Thing other = (Thing) obj;  
+    return Objects.equals(this.name, other.name);  
+}  
+```
+
+- **Consistency**: `hashCode` returns `name.hashCode()`, and `equals` compares  
+  `name` fields, both consistent as long as `name` is unchanged.  
+- **Equality and Hash Code**: If two `Thing` objects have the same `name`,  
+  `equals` returns `true`, and `hashCode` returns the same value, satisfying the  
+  contract.  
+- **Reflexivity, Symmetry, Transitivity**: The `equals` method satisfies these:  
+  - Reflexive: `t1.equals(t1)` is `true`.  
+  - Symmetric: If `t1.equals(t2)`, then `t2.equals(t1)`.  
+  - Transitive: If `t1.equals(t2)` and `t2.equals(t3)`, then `t1.equals(t3)`.  
+  - Null handling: `t1.equals(null)` returns `false` due to the `instanceof`  
+    check.  
+- **Issue**: The `name` field is mutable (not `final`). If changed after adding  
+  a `Thing` to a `HashSet` (e.g., via commented-out `t1.name = "Thing 1";`), the  
+  hash code changes, but the object remains in its original hash bucket. This  
+  violates consistency, potentially causing duplicates or lookup failures.  
+  
+## Why the Contract Matters  
+  
+Violating the hashCode/equals contract can lead to serious issues in hash-based  
+collections:  
+  
+- **Inconsistent Hash Codes**: If equal objects have different hash codes, they  
+  may be placed in different buckets, allowing duplicates in a `HashSet` or  
+  preventing `HashMap` lookups.  
+- **Mutating Fields**: Changing fields used in `hashCode` or `equals` after  
+  adding an object to a collection (as in the `Thing` example) breaks  
+  consistency, potentially causing the object to be unreachable or added  
+  multiple times.  
+- **Incorrect Equality**: An `equals` method that doesn’t satisfy reflexivity,  
+  symmetry, or transitivity can lead to unpredictable behavior in collections or  
+  other logic relying on equality checks.  
+
+
+```java
+import java.util.HashSet;
+import java.util.Set;
+
+class Thing {
+
+    public String name = "thing";
+
+    public Thing(String name) {
+        this.name = name;
+    }
+
+    @Override
+    public int hashCode() {
+        return name.hashCode();
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+
+        if (this == obj)
+            return true;
+        if (!(obj instanceof Thing))
+            return false;
+        Thing other = (Thing) obj;
+        return Objects.equals(this.name, other.name);
+    }
+
+    @Override
+    public String toString() {
+        return this.name;
+    }
+}
+
+void main() {
+
+    Set<Thing> vals = new HashSet<>();
+
+    var t1 = new Thing("thing 1");
+    var t2 = new Thing("thing 2");
+    var t3 = new Thing("thing 3");
+    var t4 = new Thing("thing 4");
+    var t5 = new Thing("thing 5");
+
+    vals.add(t1);
+    vals.add(t2);
+    vals.add(t3);
+    vals.add(t4);
+    vals.add(t5);
+
+    // t1.name = "Thing 1";
+    // t2.name = "Thing 2";
+    // t3.name = "Thing 3";
+
+    vals.add(t1);
+    vals.add(t3);
+    vals.add(t5);
+
+    System.out.println(vals);
+}
+```
+
+
+### Issues in the Provided Code
+
+1. **Mutable Field Used in `hashCode` and `equals`**:  
+   - The `name` field, used in `hashCode` and `equals`, is mutable (not  
+     `final`). If modified after a `Thing`  object is added to the `HashSet` (as  
+     in the commented-out lines `t1.name = "Thing 1";`, etc.), it changes the  
+     object’s hash code and equality behavior.  
+   - **Impact**: This breaks the `HashSet` contract, as the object remains in  
+     its original hash bucket (based on the old `name`). Subsequent operations  
+     like `vals.add(t1)` may add the same object again or fail to find it,  
+     leading to duplicates or lookup issues.  
+   - **Example**: If `t1.name` changes from `"thing 1"` to `"Thing 1"`, `t1`’s  
+     new hash code won’t match its bucket, potentially allowing `t1` to be added  
+     again as a "new" object.  
+  
+2. **Commented-Out Code Exposes Risk**:  
+   - The commented-out lines (`t1.name = "Thing 1";`, etc.) highlight the risk  
+     of mutating `name` after adding objects to the `HashSet`. While currently  
+     inactive, they indicate a potential design flaw, as the code allows such  
+     modifications.  
+   - **Impact**: If uncommented, these changes would corrupt the `HashSet`’s  
+     integrity, causing unpredictable behavior like duplicate entries or failure  
+     to find existing objects.  
+  
+3. **Lack of Immutability Enforcement**:  
+   - The `name` field is `public` and not `final`, making it easily modifiable  
+     from outside the class. This violates best practices for objects used in  
+     hash-based collections like `HashSet`, which require consistent `hashCode`  
+     and `equals` results.  
+   - **Impact**: External code can modify `name` at any time, risking the same  
+     issues as above (e.g., duplicates or lookup failures).  
+  
+### Summary  
+The primary issue is the mutability of the `name` field, which is used in  
+`hashCode` and `equals`. Modifying it after adding a `Thing` to a `HashSet` (as  
+suggested by the commented-out code) can break the set’s integrity, leading to  
+duplicates or lookup failures.    
+This is a design flaw, as objects in hash-based collections should be immutable  
+with respect to fields affecting `hashCode` and `equals`.  
diff --git a/hashing.md b/hashing.md
new file mode 100644
index 00000000..c3b7caef
--- /dev/null
+++ b/hashing.md
@@ -0,0 +1,718 @@
+# HashMap and HashSet in Java  
+
+HashMap and HashSet are fundamental hash-based collections in Java that provide  
+efficient data storage and retrieval. HashMap is a key-value store that maps keys  
+to values using hash codes, while HashSet is a collection of unique elements that  
+internally uses a HashMap with elements as keys and a constant dummy value.  
+
+Both collections offer constant-time average performance for basic operations like  
+`get`, `put`, `add`, and `remove`. This efficiency comes from their hash-based  
+implementation, which uses an array of buckets to distribute entries based on  
+their hash codes. Understanding how these collections work internally—including  
+bucket distribution, collision handling, and the equals/hashCode contract—is  
+essential for writing correct and performant Java code.  
+
+Hash-based collections are widely used because they excel at lookups. Whether  
+you need to check if an element exists, retrieve a value by key, or ensure  
+uniqueness, these collections provide optimal performance. However, their  
+correctness depends on proper implementation of `hashCode` and `equals` methods  
+for objects used as keys or elements.  
+
+
+## Buckets and Hashing  
+
+Hash-based collections store entries in an array called a hash table. Each  
+position in this array is called a bucket. When you add an entry, Java computes  
+its hash code and uses it to determine which bucket should store the entry.  
+
+The bucket index is typically calculated as: `index = hash(key) & (n - 1)`  
+where `n` is the current capacity (always a power of 2). This bitwise AND  
+operation is equivalent to modulo but faster.  
+
+### Bucket Distribution Diagram  
+
+```
+Hash Table (capacity = 8)
+┌───────┬───────┬───────┬───────┬───────┬───────┬───────┬───────┐
+│   0   │   1   │   2   │   3   │   4   │   5   │   6   │   7   │
+└───┬───┴───────┴───┬───┴───────┴───┬───┴───────┴───────┴───────┘
+    │               │               │
+    ▼               ▼               ▼
+┌───────┐       ┌───────┐       ┌───────┐
+│ Key A │       │ Key B │       │ Key C │
+│ Val 1 │       │ Val 2 │       │ Val 3 │
+└───┬───┘       └───────┘       └───┬───┘
+    │                               │
+    ▼                               ▼
+┌───────┐                       ┌───────┐
+│ Key D │ (collision)           │ Key E │ (collision)
+│ Val 4 │                       │ Val 5 │
+└───────┘                       └───────┘
+```
+
+### Hash Distribution Example  
+
+This example demonstrates how hash codes are distributed across buckets.  
+
+```java
+void main() {
+
+    var map = new HashMap<String, Integer>();
+
+    var keys = List.of("apple", "banana", "cherry", "date", "elderberry");
+
+    for (var key : keys) {
+        int hash = key.hashCode();
+        int bucket = hash & 7;  // Simulating capacity of 8
+        IO.println(key + " -> hash: " + hash + ", bucket: " + bucket);
+    }
+
+    for (var key : keys) {
+        map.put(key, key.length());
+    }
+
+    IO.println("Map contents: " + map);
+}
+```
+
+This example shows how different keys are distributed across buckets based on  
+their hash codes. The `& 7` operation simulates a hash table with 8 buckets  
+(index 0-7). In practice, HashMap automatically manages the capacity and  
+recalculates bucket indices as needed.  
+
+
+## Collision Handling  
+
+A collision occurs when two different keys hash to the same bucket. HashMap  
+handles collisions using two strategies: linked lists and tree bins.  
+
+### Linked List Collision Handling  
+
+Initially, each bucket contains a linked list of entries. When a collision  
+occurs, the new entry is added to the list at that bucket position.  
+
+```
+Bucket 3 with linked list collision handling:
+┌───────────┐    ┌───────────┐    ┌───────────┐
+│ Key: "a"  │───▶│ Key: "q"  │───▶│ Key: "z"  │───▶ null
+│ Val: 1    │    │ Val: 17   │    │ Val: 26   │
+└───────────┘    └───────────┘    └───────────┘
+```
+
+### Tree Bin Collision Handling (Java 8+)  
+
+When a bucket exceeds 8 entries, the linked list is converted to a balanced  
+red-black tree, improving worst-case performance from O(n) to O(log n).  
+
+```
+Bucket 3 with tree bin (red-black tree):
+              ┌─────────────┐
+              │ Key: "m"    │
+              │ Val: 13     │
+              └─────┬───────┘
+           ┌────────┴────────┐
+           ▼                 ▼
+     ┌─────────────┐   ┌─────────────┐
+     │ Key: "f"    │   │ Key: "t"    │
+     │ Val: 6      │   │ Val: 20     │
+     └─────────────┘   └─────────────┘
+```
+
+### Collision Demonstration  
+
+This example demonstrates how collisions are handled internally.  
+
+```java
+record BadHashKey(String value) {
+    @Override
+    public int hashCode() {
+        return 1;  // All keys go to the same bucket (bad practice!)
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        return obj instanceof BadHashKey other && 
+               Objects.equals(this.value, other.value);
+    }
+}
+
+void main() {
+
+    var map = new HashMap<BadHashKey, Integer>();
+
+    for (int i = 0; i < 10; i++) {
+        map.put(new BadHashKey("key" + i), i);
+    }
+
+    IO.println("Map size: " + map.size());
+    IO.println("All keys have same hashCode: " + 
+               (new BadHashKey("a").hashCode() == new BadHashKey("b").hashCode()));
+
+    long startTime = System.nanoTime();
+    var result = map.get(new BadHashKey("key5"));
+    long endTime = System.nanoTime();
+
+    IO.println("Retrieved value: " + result);
+    IO.println("Lookup time: " + (endTime - startTime) + " ns");
+}
+```
+
+This example creates keys with identical hash codes, forcing all entries into  
+the same bucket. While the map still functions correctly, performance degrades  
+because every lookup must traverse the collision chain. In real applications,  
+well-distributed hash codes are essential for maintaining O(1) average lookup.  
+
+
+## Optimization Algorithms  
+
+HashMap employs several optimization strategies to maintain performance as the  
+collection grows.  
+
+### Load Factor and Capacity  
+
+| Property | Default Value | Description |  
+|----------|---------------|-------------|  
+| Initial Capacity | 16 | Number of buckets at creation |  
+| Load Factor | 0.75 | Ratio of entries to capacity before resize |  
+| Threshold | capacity × loadFactor | Number of entries that trigger resize |  
+| Resize Factor | 2× | Capacity doubles on each resize |  
+
+### Rehashing and Resizing  
+
+When the number of entries exceeds the threshold, HashMap doubles its capacity  
+and rehashes all entries to redistribute them across the new bucket array.  
+
+```
+Before resize (capacity = 4, threshold = 3):
+┌───┬───┬───┬───┐
+│ A │ B │ C │ D │  ← 4 entries, exceeds threshold
+└───┴───┴───┴───┘
+
+After resize (capacity = 8, threshold = 6):
+┌───┬───┬───┬───┬───┬───┬───┬───┐
+│ A │   │ B │   │ C │   │ D │   │  ← entries redistributed
+└───┴───┴───┴───┴───┴───┴───┴───┘
+```
+
+### Resize Demonstration  
+
+This example shows how capacity changes affect performance.  
+
+```java
+void main() {
+
+    var mapSmall = new HashMap<Integer, String>(2, 0.75f);
+    var mapLarge = new HashMap<Integer, String>(1024, 0.75f);
+
+    int entries = 1000;
+
+    long startSmall = System.nanoTime();
+    for (int i = 0; i < entries; i++) {
+        mapSmall.put(i, "value" + i);
+    }
+    long timeSmall = System.nanoTime() - startSmall;
+
+    long startLarge = System.nanoTime();
+    for (int i = 0; i < entries; i++) {
+        mapLarge.put(i, "value" + i);
+    }
+    long timeLarge = System.nanoTime() - startLarge;
+
+    IO.println("Small initial capacity time: " + timeSmall / 1000 + " µs");
+    IO.println("Large initial capacity time: " + timeLarge / 1000 + " µs");
+    IO.println("Ratio: " + (double) timeSmall / timeLarge);
+}
+```
+
+Starting with a small initial capacity causes multiple resize operations as the  
+map grows, each requiring rehashing of all entries. When you know the approximate  
+size in advance, specifying an adequate initial capacity avoids these costly  
+resize operations and improves performance.  
+
+
+### Treeification Threshold  
+
+When a bucket contains more than 8 entries, HashMap converts the linked list  
+to a red-black tree. This improves worst-case lookup from O(n) to O(log n).  
+
+| Threshold | Value | Description |  
+|-----------|-------|-------------|  
+| TREEIFY_THRESHOLD | 8 | Entries before converting to tree |  
+| UNTREEIFY_THRESHOLD | 6 | Entries before reverting to list |  
+| MIN_TREEIFY_CAPACITY | 64 | Minimum capacity for treeification |  
+
+### Performance Comparison  
+
+| Scenario | Linked List | Red-Black Tree |  
+|----------|-------------|----------------|  
+| Average lookup | O(n/2) | O(log n) |  
+| Worst case | O(n) | O(log n) |  
+| Memory overhead | Lower | Higher |  
+| When used | ≤ 8 entries | > 8 entries |  
+
+
+## Equals and HashCode Contract  
+
+The equals/hashCode contract is a fundamental agreement that ensures correct  
+behavior in hash-based collections. Violating this contract leads to subtle  
+bugs that are difficult to diagnose.  
+
+### Contract Rules  
+
+1. **Consistency**: Multiple invocations of `hashCode` on the same object must  
+   return the same integer, provided the object hasn't changed.  
+
+2. **Equality implies same hash**: If `a.equals(b)` returns `true`, then  
+   `a.hashCode()` must equal `b.hashCode()`.  
+
+3. **Same hash does not imply equality**: Two objects with the same hash code  
+   are not required to be equal (collisions are allowed).  
+
+4. **Reflexivity**: `x.equals(x)` must return `true`.  
+
+5. **Symmetry**: If `x.equals(y)` returns `true`, then `y.equals(x)` must also  
+   return `true`.  
+
+6. **Transitivity**: If `x.equals(y)` and `y.equals(z)` return `true`, then  
+   `x.equals(z)` must also return `true`.  
+
+7. **Null handling**: `x.equals(null)` must return `false`.  
+
+### Contract Visualization  
+
+```
+                    ┌─────────────────────────────────┐
+                    │         Contract Rules          │
+                    └─────────────────────────────────┘
+                                    │
+        ┌───────────────────────────┼───────────────────────────┐
+        │                           │                           │
+        ▼                           ▼                           ▼
+┌───────────────┐         ┌───────────────┐         ┌───────────────┐
+│   If equal    │         │  Hash codes   │         │   equals()    │
+│   objects     │         │  can collide  │         │   properties  │
+│               │         │               │         │               │
+│ a.equals(b)   │         │  a.hash == b  │         │  Reflexive    │
+│      ↓        │         │  doesn't mean │         │  Symmetric    │
+│ a.hash ==     │         │  a.equals(b)  │         │  Transitive   │
+│ b.hash        │         │               │         │  Null-safe    │
+└───────────────┘         └───────────────┘         └───────────────┘
+```
+
+
+## Why the Contract is Needed  
+
+The equals/hashCode contract exists because hash-based collections use a  
+two-step lookup process:  
+
+1. **Hash code lookup**: Find the bucket using `hashCode()`  
+2. **Equality check**: Search within the bucket using `equals()`  
+
+If these methods are inconsistent, lookups fail even when objects exist.  
+
+### Broken Contract Scenarios  
+
+```
+Scenario: Equal objects with different hash codes
+
+Object A: hashCode() = 42, equals(B) = true
+Object B: hashCode() = 99, equals(A) = true
+
+HashMap stores A in bucket 42
+HashMap.get(B) searches bucket 99 → NOT FOUND!
+
+Result: Lost entry despite equal keys
+```
+
+### Contract Violation Example  
+
+This example demonstrates what happens when the contract is violated.  
+
+```java
+class BrokenKey {
+    private String id;
+    private int counter = 0;
+
+    public BrokenKey(String id) {
+        this.id = id;
+    }
+
+    @Override
+    public int hashCode() {
+        return id.hashCode() + counter++;  // Changes on each call!
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        return obj instanceof BrokenKey other && 
+               Objects.equals(this.id, other.id);
+    }
+}
+
+void main() {
+
+    var map = new HashMap<BrokenKey, String>();
+    var key = new BrokenKey("mykey");
+
+    map.put(key, "my value");
+    IO.println("Immediately after put: " + map.get(key));
+    IO.println("Second get attempt: " + map.get(key));
+    IO.println("Third get attempt: " + map.get(key));
+    IO.println("Map contains key? " + map.containsKey(key));
+    IO.println("Map size: " + map.size());
+}
+```
+
+The `BrokenKey` class violates the contract because `hashCode` returns a  
+different value each time it's called. After adding the key, subsequent lookups  
+fail because the new hash code doesn't match the original bucket location.  
+The entry exists but is unreachable—a particularly insidious bug.  
+
+
+### Mutable Key Problem  
+
+Another common violation occurs when mutable objects are used as keys and  
+their state changes after insertion.  
+
+```java
+class MutablePerson {
+    public String name;
+
+    public MutablePerson(String name) {
+        this.name = name;
+    }
+
+    @Override
+    public int hashCode() {
+        return name.hashCode();
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        return obj instanceof MutablePerson other && 
+               Objects.equals(this.name, other.name);
+    }
+
+    @Override
+    public String toString() {
+        return "Person[" + name + "]";
+    }
+}
+
+void main() {
+
+    var set = new HashSet<MutablePerson>();
+    var person = new MutablePerson("Alice");
+
+    set.add(person);
+    IO.println("Before mutation - contains Alice? " + 
+               set.contains(new MutablePerson("Alice")));
+
+    person.name = "Bob";  // Mutating the key!
+
+    IO.println("After mutation - contains Alice? " + 
+               set.contains(new MutablePerson("Alice")));
+    IO.println("After mutation - contains Bob? " + 
+               set.contains(new MutablePerson("Bob")));
+    IO.println("Set contents: " + set);
+    IO.println("Set size: " + set.size());
+
+    set.add(person);  // Adding "same" object again
+    IO.println("After re-add - Set size: " + set.size());
+}
+```
+
+When `name` changes from "Alice" to "Bob", the object's hash code changes but  
+its bucket location doesn't. Now the object can't be found with either name,  
+and adding it again creates a duplicate. This demonstrates why keys should be  
+immutable or why mutable fields should not be used in `hashCode` and `equals`.  
+
+
+## Correct Implementation  
+
+A proper implementation follows the contract and uses consistent fields.  
+
+### Using Records (Recommended)  
+
+Java records automatically generate correct `hashCode` and `equals` methods.  
+
+```java
+record Person(String name, int age) {}
+
+void main() {
+
+    var set = new HashSet<Person>();
+
+    var alice1 = new Person("Alice", 30);
+    var alice2 = new Person("Alice", 30);
+
+    set.add(alice1);
+    set.add(alice2);  // Same as alice1, won't be added
+
+    IO.println("Set size: " + set.size());
+    IO.println("alice1 equals alice2: " + alice1.equals(alice2));
+    IO.println("Same hash: " + (alice1.hashCode() == alice2.hashCode()));
+    IO.println("Contains alice2? " + set.contains(alice2));
+}
+```
+
+Records are the simplest way to create proper value-based classes. They  
+automatically implement `hashCode`, `equals`, and `toString` based on all  
+components. Since record components are final, the immutability requirement  
+is also satisfied.  
+
+
+### Manual Implementation  
+
+When you need a class instead of a record, implement both methods carefully.  
+
+```java
+class Product {
+    private final String sku;
+    private final String name;
+    private final double price;
+
+    public Product(String sku, String name, double price) {
+        this.sku = sku;
+        this.name = name;
+        this.price = price;
+    }
+
+    public String getSku() { return sku; }
+    public String getName() { return name; }
+    public double getPrice() { return price; }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(sku, name, price);
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (this == obj) return true;
+        if (!(obj instanceof Product other)) return false;
+        return Objects.equals(sku, other.sku) &&
+               Objects.equals(name, other.name) &&
+               Double.compare(price, other.price) == 0;
+    }
+
+    @Override
+    public String toString() {
+        return "Product[sku=%s, name=%s, price=%.2f]".formatted(sku, name, price);
+    }
+}
+
+void main() {
+
+    var inventory = new HashMap<Product, Integer>();
+
+    var laptop = new Product("LAP001", "Laptop", 999.99);
+    var sameLaptop = new Product("LAP001", "Laptop", 999.99);
+
+    inventory.put(laptop, 50);
+    inventory.put(sameLaptop, 75);  // Overwrites previous entry
+
+    IO.println("Inventory size: " + inventory.size());
+    IO.println("Laptop stock: " + inventory.get(laptop));
+    IO.println("Same laptop stock: " + inventory.get(sameLaptop));
+}
+```
+
+The `Product` class follows best practices: all fields are `final` for  
+immutability, `Objects.hash` combines field hash codes consistently, and  
+`equals` uses `Objects.equals` for null-safe comparison. Note the use of  
+`Double.compare` for floating-point equality instead of `==`.  
+
+
+## Best Practices  
+
+Follow these guidelines for robust hash-based collections:  
+
+### Implementation Guidelines  
+
+| Practice | Description |  
+|----------|-------------|  
+| Use records | Let Java generate correct implementations |  
+| Make fields final | Prevents mutation after insertion |  
+| Use Objects.hash | Combines multiple fields correctly |  
+| Use Objects.equals | Handles null values safely |  
+| Override both methods | Never override one without the other |  
+| Use same fields | hashCode and equals must use identical fields |  
+
+### Objects.hash and Objects.equals  
+
+These utility methods simplify correct implementation.  
+
+```java
+class Employee {
+    private final String id;
+    private final String department;
+    private final String email;
+
+    public Employee(String id, String department, String email) {
+        this.id = id;
+        this.department = department;
+        this.email = email;
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(id, department, email);
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (this == obj) return true;
+        if (!(obj instanceof Employee other)) return false;
+        return Objects.equals(id, other.id) &&
+               Objects.equals(department, other.department) &&
+               Objects.equals(email, other.email);
+    }
+}
+
+void main() {
+
+    var employees = new HashSet<Employee>();
+
+    employees.add(new Employee("E001", "Engineering", "john@example.com"));
+    employees.add(new Employee("E002", "Marketing", "jane@example.com"));
+    employees.add(new Employee("E001", "Engineering", "john@example.com"));
+
+    IO.println("Employee count: " + employees.size());
+
+    var lookup = new Employee("E001", "Engineering", "john@example.com");
+    IO.println("Contains E001? " + employees.contains(lookup));
+}
+```
+
+`Objects.hash` creates a composite hash code from multiple values, handling  
+nulls correctly. `Objects.equals` performs null-safe equality comparison.  
+Together, they provide a concise and correct implementation pattern that  
+avoids common pitfalls like NullPointerException.  
+
+
+### When to Override  
+
+| Scenario | Override? | Reason |  
+|----------|-----------|--------|  
+| Value semantics needed | Yes | Two objects with same data should be equal |  
+| Used as Map key | Yes | Correct lookup requires proper hash/equals |  
+| Used in Set | Yes | Uniqueness based on content, not reference |  
+| Entity with database ID | Partially | Often only ID is used for equality |  
+| Singleton or enum | No | Reference equality is correct |  
+| Temporary/internal class | Usually no | Reference equality often sufficient |  
+
+
+### HashSet Implementation Detail  
+
+HashSet internally uses HashMap with elements as keys. Understanding this  
+helps explain HashSet behavior.  
+
+```java
+void main() {
+
+    var set = new HashSet<String>();
+
+    set.add("apple");
+    set.add("banana");
+    set.add("apple");  // Duplicate, returns false
+
+    IO.println("Set: " + set);
+    IO.println("Size: " + set.size());
+
+    boolean added1 = set.add("cherry");
+    boolean added2 = set.add("cherry");
+
+    IO.println("First add returned: " + added1);
+    IO.println("Second add returned: " + added2);
+
+    for (var element : set) {
+        int hash = element.hashCode();
+        IO.println(element + " hash: " + hash);
+    }
+}
+```
+
+Internally, HashSet stores elements as keys in a HashMap with a dummy constant  
+value (PRESENT). The `add` method returns `true` if the element was new, `false`  
+if it already existed. This explains why HashSet operations have the same  
+performance characteristics as HashMap.  
+
+
+## HashMap Internal Structure  
+
+Understanding the internal structure helps with debugging and optimization.  
+
+```java
+import java.lang.reflect.Field;
+
+void main() throws Exception {
+
+    var map = new HashMap<String, Integer>();
+
+    for (int i = 0; i < 20; i++) {
+        map.put("key" + i, i);
+    }
+
+    Field tableField = HashMap.class.getDeclaredField("table");
+    tableField.setAccessible(true);
+    Object[] table = (Object[]) tableField.get(map);
+
+    IO.println("Bucket array length: " + table.length);
+    IO.println("Map size: " + map.size());
+    IO.println("Load factor threshold: " + (int)(table.length * 0.75));
+
+    int nonEmptyBuckets = 0;
+    for (Object bucket : table) {
+        if (bucket != null) nonEmptyBuckets++;
+    }
+    IO.println("Non-empty buckets: " + nonEmptyBuckets);
+    IO.println("Average entries per bucket: " + 
+               (double) map.size() / nonEmptyBuckets);
+}
+```
+
+This example uses reflection to inspect HashMap internals. The bucket array  
+grows in powers of 2, starting at 16. When size exceeds the threshold  
+(capacity × 0.75), the array doubles. Good hash distribution keeps entries  
+spread across buckets, maintaining O(1) average operations.  
+
+
+## Performance Characteristics  
+
+| Operation | HashMap | HashSet | TreeMap | LinkedHashMap |  
+|-----------|---------|---------|---------|---------------|  
+| get/contains | O(1) avg | O(1) avg | O(log n) | O(1) avg |  
+| put/add | O(1) avg | O(1) avg | O(log n) | O(1) avg |  
+| remove | O(1) avg | O(1) avg | O(log n) | O(1) avg |  
+| Iteration | O(n + capacity) | O(n + capacity) | O(n) | O(n) |  
+| Memory | Medium | Medium | Higher | Higher |  
+| Order | None | None | Sorted | Insertion |  
+
+
+## Summary  
+
+HashMap and HashSet are essential Java collections that provide efficient  
+storage and retrieval through hashing. Key concepts to remember:  
+
+**Buckets and Hashing**: Entries are distributed across buckets using hash  
+codes. Good distribution minimizes collisions and maintains O(1) performance.  
+
+**Collision Handling**: When collisions occur, entries are stored in linked  
+lists (≤8 entries) or red-black trees (>8 entries) within the same bucket.  
+
+**Optimization**: HashMap automatically resizes when load exceeds 75%, doubling  
+capacity and rehashing entries. Treeification converts high-collision buckets  
+to balanced trees for O(log n) worst-case performance.  
+
+**Equals/HashCode Contract**: Equal objects must have equal hash codes. Both  
+methods should use the same fields. Violation causes lost entries, duplicate  
+keys, and unpredictable behavior.  
+
+**Best Practices**: Use records for automatic correct implementation. Make  
+fields final. Use `Objects.hash` and `Objects.equals` for utility. Never  
+override only one of `equals` or `hashCode`.  
+
+Understanding these internals enables you to write efficient code, choose  
+appropriate initial capacities, implement proper key classes, and debug  
+collection-related issues effectively.  
diff --git a/hotspot.md b/hotspot.md
new file mode 100644
index 00000000..e31db66d
--- /dev/null
+++ b/hotspot.md
@@ -0,0 +1,1117 @@
+# HotSpot JVM  
+
+The **HotSpot JVM** (Java Virtual Machine) is the primary execution engine for Java  
+applications. Developed by Sun Microsystems and now maintained by Oracle, HotSpot  
+is the default JVM included in the Oracle JDK and OpenJDK distributions. It earned  
+its name from its ability to identify and optimize "hot spots" in code—sections  
+that execute frequently—through Just-In-Time (JIT) compilation.  
+
+HotSpot revolutionized Java performance by introducing adaptive optimization  
+techniques that allow Java applications to achieve near-native execution speeds.  
+Unlike static compilers that optimize code before execution, HotSpot continuously  
+monitors application behavior at runtime and applies targeted optimizations to  
+the most performance-critical code paths.  
+
+Understanding HotSpot's internals is essential for Java developers who want to  
+write high-performance applications, tune JVM settings for production workloads,  
+or diagnose performance issues. This document provides a comprehensive overview  
+of HotSpot's architecture, execution model, garbage collection, memory management,  
+and performance tuning techniques.  
+
+HotSpot's origins trace back to the mid-1990s at Longview Technologies, which  
+was acquired by Sun Microsystems in 1997. The first HotSpot JVM was released with  
+Java 1.2, and it became the default JVM starting with Java 1.3. Over the years,  
+HotSpot has evolved significantly, incorporating modern garbage collectors,  
+tiered compilation, and integration with advanced technologies like GraalVM.  
+
+
+## HotSpot Architecture  
+
+HotSpot's architecture is designed to balance startup performance with peak  
+throughput. The JVM consists of several key components that work together to  
+load, verify, compile, and execute Java bytecode efficiently.  
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           HotSpot JVM Architecture                          │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │                         Class Loader Subsystem                      │   │
+│   │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                  │   │
+│   │  │  Bootstrap  │  │  Extension  │  │ Application │                  │   │
+│   │  │   Loader    │  │   Loader    │  │   Loader    │                  │   │
+│   │  └─────────────┘  └─────────────┘  └─────────────┘                  │   │
+│   └─────────────────────────────────────────────────────────────────────┘   │
+│                                    │                                        │
+│                                    ▼                                        │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │                         Runtime Data Areas                          │   │
+│   │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────────┐  │   │
+│   │  │   Method    │  │    Heap     │  │    Per-Thread Areas         │  │   │
+│   │  │    Area     │  │  (Objects)  │  │  ┌───────┐ ┌────────────┐   │  │   │
+│   │  │ (Metaspace) │  │             │  │  │ Stack │ │ PC Register│   │  │   │
+│   │  └─────────────┘  └─────────────┘  │  └───────┘ └────────────┘   │  │   │
+│   │                                    └─────────────────────────────┘  │   │
+│   └─────────────────────────────────────────────────────────────────────┘   │
+│                                    │                                        │
+│                                    ▼                                        │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │                         Execution Engine                            │   │
+│   │  ┌─────────────┐  ┌─────────────────────────────┐  ┌─────────────┐  │   │
+│   │  │ Interpreter │  │       JIT Compiler          │  │   Garbage   │  │   │
+│   │  │             │  │  ┌─────┐      ┌─────────┐   │  │  Collector  │  │   │
+│   │  │             │  │  │ C1  │      │   C2    │   │  │             │  │   │
+│   │  │             │  │  │Client     │ Server  │   │  │             │  │   │
+│   │  └─────────────┘  │  └─────┘      └─────────┘   │  └─────────────┘  │   │
+│   │                   └─────────────────────────────┘                   │   │
+│   └─────────────────────────────────────────────────────────────────────┘   │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Class Loader Subsystem  
+
+The class loader subsystem is responsible for loading, linking, and initializing  
+Java classes. HotSpot uses a hierarchical class loading model with three main  
+class loaders that work together using the delegation principle.  
+
+| Loader Type     | Responsibility                                             |
+|-----------------|------------------------------------------------------------|
+| Bootstrap       | Loads core Java classes from rt.jar (or modules in Java 9+)|
+| Extension/Platform | Loads classes from extension directories                |
+| Application     | Loads classes from the application classpath               |
+
+When loading a class, each loader first delegates to its parent. Only if the  
+parent cannot find the class does the child attempt to load it. This ensures  
+that core Java classes are always loaded by the bootstrap loader, preventing  
+malicious code from replacing critical system classes.  
+
+### Runtime Data Areas  
+
+HotSpot manages several memory regions during program execution:  
+
+| Memory Area   | Shared? | Purpose                                           |
+|---------------|---------|---------------------------------------------------|
+| Heap          | Yes     | Stores all object instances                       |
+| Metaspace     | Yes     | Stores class metadata, replaces PermGen           |
+| Code Cache    | Yes     | Stores JIT-compiled native code                   |
+| Thread Stacks | No      | Per-thread call stacks and local variables        |
+| PC Registers  | No      | Per-thread program counter for bytecode execution |
+
+### Execution Engine Components  
+
+The execution engine transforms bytecode into machine code through multiple stages:  
+
+**Interpreter**: Provides immediate execution of bytecode without compilation  
+overhead. Essential for fast startup and rarely-executed code paths.  
+
+**C1 Compiler (Client)**: A fast compiler that produces moderately optimized  
+code quickly. Ideal for methods that need optimization sooner but may not  
+benefit from expensive analysis.  
+
+**C2 Compiler (Server)**: A highly optimizing compiler that produces the fastest  
+code but takes longer to compile. Applied to "hot" methods that benefit from  
+aggressive optimizations like inlining and loop unrolling.  
+
+**Garbage Collector**: Automatically reclaims memory from objects that are no  
+longer reachable. HotSpot offers multiple GC algorithms optimized for different  
+workload characteristics.  
+
+
+## Execution Model  
+
+HotSpot uses an adaptive execution model that balances startup performance with  
+peak throughput. When a Java application starts, methods are initially executed  
+by the interpreter. As methods are called repeatedly, they become candidates for  
+JIT compilation.  
+
+### Bytecode Interpretation  
+
+The interpreter executes Java bytecode instruction by instruction. While slower  
+than compiled code, interpretation provides several benefits:  
+
+- **Fast startup**: No compilation delay before execution begins  
+- **Low memory footprint**: No need to store compiled code  
+- **Accurate profiling**: Execution counters guide optimization decisions  
+- **Debugging support**: Easier to maintain source-level debugging  
+
+```java
+void main() {
+
+    // This method starts in the interpreter
+    // Each bytecode instruction is decoded and executed
+    int sum = 0;
+    for (int i = 0; i < 10; i++) {
+        sum += computeValue(i);
+    }
+    
+    IO.println("Sum: " + sum);
+}
+
+int computeValue(int x) {
+    // If called frequently, this becomes a "hot" method
+    // and will be compiled by the JIT compiler
+    return x * x + 2 * x + 1;
+}
+```
+
+During interpretation, HotSpot maintains invocation counters for methods and  
+back-edge counters for loops. When these counters exceed configured thresholds,  
+the method becomes eligible for JIT compilation.  
+
+### Tiered Compilation  
+
+Modern HotSpot uses tiered compilation, which combines the fast compilation of  
+C1 with the high-quality code of C2. Methods progress through compilation tiers  
+based on their execution frequency and profiling data.  
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                        Tiered Compilation Levels                            │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  Level 0: Interpreter                                                       │
+│     │                                                                       │
+│     │  Method invocation count exceeds threshold                            │
+│     ▼                                                                       │
+│  Level 1: C1 with Full Optimization (no profiling)                          │
+│     │      - Used for trivial methods                                       │
+│     │                                                                       │
+│  Level 2: C1 with Limited Profiling                                         │
+│     │      - Invocation and back-edge counters                              │
+│     ▼                                                                       │
+│  Level 3: C1 with Full Profiling                                            │
+│     │      - Type profiling, branch profiling                               │
+│     │      - Used to collect data for C2                                    │
+│     ▼                                                                       │
+│  Level 4: C2 with Full Optimization                                         │
+│            - Maximum optimization based on profiling data                   │
+│            - Speculative optimizations with deoptimization guards           │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+| Level | Compiler | Profiling  | Use Case                               |
+|-------|----------|------------|----------------------------------------|
+| 0     | None     | Basic      | Initial execution, cold code           |
+| 1     | C1       | None       | Trivial methods, getters/setters       |
+| 2     | C1       | Limited    | Limited profiling for quick warmup     |
+| 3     | C1       | Full       | Collecting data for C2 compilation     |
+| 4     | C2       | Uses L3    | Hot methods requiring maximum speed    |
+
+### Adaptive Optimization  
+
+HotSpot's adaptive optimization continuously monitors application behavior and  
+adjusts compilation strategies accordingly. The JVM collects several types of  
+profiling information:  
+
+**Invocation Counts**: How often each method is called  
+**Back-Edge Counts**: How many loop iterations execute  
+**Type Profiles**: Actual types of objects at call sites  
+**Branch Profiles**: Which branches are taken and how often  
+
+```java
+void main() {
+
+    // Type profiling example
+    List<String> items = new ArrayList<>();
+    items.add("one");
+    items.add("two");
+    items.add("three");
+    
+    // HotSpot profiles that 'items' is always ArrayList
+    // This enables virtual call devirtualization
+    int totalLength = 0;
+    for (var item : items) {
+        totalLength += item.length();
+    }
+    
+    IO.println("Total length: " + totalLength);
+}
+```
+
+The JIT compiler uses profiling data to make speculative optimizations. If the  
+runtime behavior changes and an optimization becomes invalid, HotSpot can  
+**deoptimize**—reverting compiled code back to interpretation and recompiling  
+with updated profiling information.  
+
+
+## Just-In-Time (JIT) Compilation  
+
+The JIT compiler is the heart of HotSpot's performance. It translates Java  
+bytecode into highly optimized native machine code at runtime, achieving  
+performance comparable to statically compiled languages.  
+
+### Hot Method Detection  
+
+HotSpot identifies "hot" methods through execution counters. Methods that exceed  
+compilation thresholds are queued for background compilation. The thresholds are  
+configurable via JVM flags:  
+
+| Flag                          | Default | Description                     |
+|-------------------------------|---------|----------------------------------|
+| `-XX:CompileThreshold`        | 10000   | Invocations before C2 compile   |
+| `-XX:Tier3InvocationThreshold`| 200     | Invocations before C1 L3        |
+| `-XX:Tier4InvocationThreshold`| 5000    | Invocations before C2 from L3   |
+
+### Key JIT Optimizations  
+
+HotSpot's JIT compilers apply numerous optimizations to improve performance:  
+
+**Inlining**: Replaces method calls with the method body, eliminating call  
+overhead and enabling further optimizations.  
+
+```java
+void main() {
+
+    long sum = 0;
+    
+    // Without inlining: method call overhead for each iteration
+    // With inlining: getSquare code is inserted directly into loop
+    for (int i = 0; i < 1000000; i++) {
+        sum += getSquare(i);
+    }
+    
+    IO.println("Sum of squares: " + sum);
+}
+
+// This small method is an ideal inlining candidate
+int getSquare(int n) {
+    return n * n;
+}
+```
+
+**Escape Analysis**: Determines if objects are accessible outside their  
+allocating scope. Non-escaping objects can be stack-allocated or eliminated  
+entirely.  
+
+```java
+void main() {
+
+    long total = 0;
+    
+    for (int i = 0; i < 1000000; i++) {
+        // The Point object doesn't escape this method
+        // HotSpot may eliminate the allocation entirely
+        var point = new Point(i, i * 2);
+        total += point.distance();
+    }
+    
+    IO.println("Total distance: " + total);
+}
+
+record Point(int x, int y) {
+    double distance() {
+        return Math.sqrt(x * x + y * y);
+    }
+}
+```
+
+**Loop Unrolling**: Replicates loop bodies to reduce loop overhead and enable  
+instruction-level parallelism.  
+
+**Dead Code Elimination**: Removes code that has no effect on program output.  
+
+**Constant Folding**: Evaluates constant expressions at compile time.  
+
+**Bounds Check Elimination**: Removes redundant array bounds checks when the  
+compiler can prove safety.  
+
+**Null Check Elimination**: Removes null checks when the compiler can prove  
+non-nullness.  
+
+### Performance Monitoring  
+
+Monitor JIT compilation activity with these flags:  
+
+```
+-XX:+PrintCompilation           # Log compilation events
+-XX:+UnlockDiagnosticVMOptions  # Enable diagnostic options
+-XX:+PrintInlining              # Show inlining decisions
+-XX:+LogCompilation             # Generate detailed XML logs
+```
+
+```java
+void main() {
+
+    // Run with -XX:+PrintCompilation to see compilation output
+    // Methods will show compilation tier and timing
+    
+    var startTime = System.nanoTime();
+    
+    long result = 0;
+    for (int i = 0; i < 10_000_000; i++) {
+        result += fibonacci(20);
+    }
+    
+    var endTime = System.nanoTime();
+    var durationMs = (endTime - startTime) / 1_000_000;
+    
+    IO.println("Result: " + result);
+    IO.println("Duration: " + durationMs + " ms");
+}
+
+int fibonacci(int n) {
+    if (n <= 1) return n;
+    return fibonacci(n - 1) + fibonacci(n - 2);
+}
+```
+
+After repeated invocations, the `fibonacci` method will be compiled by C2,  
+resulting in significantly faster execution compared to interpretation.  
+
+
+## Garbage Collection in HotSpot  
+
+Garbage collection (GC) is the process of automatically reclaiming memory  
+occupied by objects that are no longer reachable by the application. HotSpot  
+provides multiple garbage collectors, each optimized for different workload  
+characteristics.  
+
+### Generational Hypothesis  
+
+HotSpot's garbage collectors are based on the generational hypothesis:  
+
+- Most objects die young (are short-lived)  
+- Few references from old objects to young objects exist  
+
+This observation enables efficient collection by focusing on the young  
+generation, where most garbage resides.  
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                          Heap Memory Structure                              │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  ┌───────────────────────────────────┐  ┌───────────────────────────────┐   │
+│  │          Young Generation         │  │        Old Generation         │   │
+│  │  ┌───────┐ ┌───────┐ ┌───────┐   │  │                               │   │
+│  │  │ Eden  │ │  S0   │ │  S1   │   │  │    Tenured/Old Objects        │   │
+│  │  │       │ │       │ │       │   │  │                               │   │
+│  │  │ New   │ │Survivor│Survivor│   │  │  (Long-lived objects that     │   │
+│  │  │Objects│ │ From  │ │  To   │   │  │   survived multiple GCs)      │   │
+│  │  └───────┘ └───────┘ └───────┘   │  │                               │   │
+│  └───────────────────────────────────┘  └───────────────────────────────┘   │
+│                                                                             │
+│  Object lifecycle:                                                          │
+│  1. New objects allocated in Eden                                           │
+│  2. Surviving objects move to Survivor spaces                               │
+│  3. After aging, objects promote to Old generation                          │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Available Garbage Collectors  
+
+| Collector    | Young GC | Old GC  | Pause Goal        | Best For            |
+|--------------|----------|---------|-------------------|---------------------|
+| Serial GC    | Serial   | Serial  | None              | Small apps, testing |
+| Parallel GC  | Parallel | Parallel| Throughput        | Batch processing    |
+| G1 GC        | Parallel | Concurrent| Predictable     | General purpose     |
+| ZGC          | Concurrent| Concurrent| Sub-millisecond| Low latency, large heaps|
+| Shenandoah   | Concurrent| Concurrent| Low latency    | Low latency         |
+
+**Serial GC** (`-XX:+UseSerialGC`): Single-threaded collector suitable for  
+single-processor machines or applications with small heaps and minimal pause  
+time requirements.  
+
+**Parallel GC** (`-XX:+UseParallelGC`): Multi-threaded collector optimized for  
+throughput. Performs stop-the-world collections using multiple threads.  
+
+**G1 GC** (`-XX:+UseG1GC`): The default collector since Java 9. Divides the  
+heap into regions and collects garbage incrementally to meet pause time targets.  
+
+**ZGC** (`-XX:+UseZGC`): Scalable, low-latency collector with pause times under  
+10 milliseconds regardless of heap size. Ideal for large heaps and latency-  
+sensitive applications.  
+
+**Shenandoah** (`-XX:+UseShenandoahGC`): Similar to ZGC with concurrent  
+compaction. Available in OpenJDK but not Oracle JDK.  
+
+### GC Selection Guidelines  
+
+```java
+void main() {
+
+    // Demonstrate memory allocation patterns
+    var objects = new ArrayList<byte[]>();
+    
+    IO.println("Allocating objects...");
+    
+    for (int i = 0; i < 100; i++) {
+        // Allocate 1 MB chunks
+        objects.add(new byte[1024 * 1024]);
+        
+        // Occasionally release some to trigger GC
+        if (i % 20 == 0 && i > 0) {
+            objects.subList(0, 10).clear();
+        }
+    }
+    
+    IO.println("Allocated " + objects.size() + " MB worth of objects");
+    
+    // Force GC for observation (don't do this in production)
+    System.gc();
+    
+    Runtime runtime = Runtime.getRuntime();
+    long usedMemory = runtime.totalMemory() - runtime.freeMemory();
+    IO.println("Used memory: " + (usedMemory / 1024 / 1024) + " MB");
+}
+```
+
+| Requirement                    | Recommended GC       | Key Flags              |
+|--------------------------------|----------------------|------------------------|
+| Maximum throughput             | Parallel GC          | `-XX:+UseParallelGC`   |
+| Predictable pause times < 200ms| G1 GC                | `-XX:MaxGCPauseMillis` |
+| Sub-millisecond pauses         | ZGC                  | `-XX:+UseZGC`          |
+| Very large heap (TB+)          | ZGC                  | `-XX:+UseZGC`          |
+| Single processor               | Serial GC            | `-XX:+UseSerialGC`     |
+
+### GC Tuning Options  
+
+Common flags for tuning garbage collection:  
+
+```
+# G1 GC tuning
+-XX:MaxGCPauseMillis=200          # Target maximum pause time
+-XX:G1HeapRegionSize=16m          # Region size (1-32 MB, power of 2)
+-XX:InitiatingHeapOccupancyPercent=45  # When to start concurrent GC
+
+# ZGC tuning
+-XX:ZCollectionInterval=5         # Force GC every 5 seconds (for testing)
+-XX:SoftMaxHeapSize=4g            # Soft limit for heap size
+
+# General GC logging
+-Xlog:gc*:file=gc.log:time,level,tags  # Modern unified logging
+```
+
+
+## Memory Management  
+
+HotSpot manages memory across several distinct regions, each serving a specific  
+purpose in the execution of Java applications.  
+
+### Heap Structure  
+
+The heap is where all Java objects live. Its structure depends on the garbage  
+collector but typically includes generational divisions.  
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                      JVM Memory Layout (Non-Heap + Heap)                    │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │                           Heap (-Xmx, -Xms)                         │    │
+│  │  ┌─────────────────────────┐  ┌─────────────────────────────────┐   │    │
+│  │  │    Young Generation     │  │         Old Generation          │   │    │
+│  │  │        (-Xmn)           │  │                                 │   │    │
+│  │  │  ┌─────┬───────┬─────┐  │  │    Long-lived objects that     │   │    │
+│  │  │  │Eden │  S0   │ S1  │  │  │    survived multiple minor GCs  │   │    │
+│  │  │  └─────┴───────┴─────┘  │  │                                 │   │    │
+│  │  └─────────────────────────┘  └─────────────────────────────────┘   │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │                    Metaspace (native memory)                        │    │
+│  │   - Class metadata           - Method bytecode                      │    │
+│  │   - Constant pools           - Annotations                          │    │
+│  │   - Controlled by: -XX:MaxMetaspaceSize                             │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │                         Code Cache                                  │    │
+│  │   - JIT compiled code        - Native method stubs                  │    │
+│  │   - Controlled by: -XX:ReservedCodeCacheSize                        │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │                    Thread Stacks (per thread)                       │    │
+│  │   - Local variables          - Method call frames                   │    │
+│  │   - Controlled by: -Xss (stack size per thread)                     │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │                    Native Memory (Direct Buffers)                   │    │
+│  │   - NIO direct buffers       - JNI allocations                      │    │
+│  │   - Controlled by: -XX:MaxDirectMemorySize                          │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Memory Configuration Flags  
+
+| Flag                        | Purpose                                     |
+|-----------------------------|---------------------------------------------|
+| `-Xms<size>`                | Initial heap size                           |
+| `-Xmx<size>`                | Maximum heap size                           |
+| `-Xmn<size>`                | Young generation size                       |
+| `-Xss<size>`                | Thread stack size                           |
+| `-XX:MaxMetaspaceSize`      | Maximum metaspace size                      |
+| `-XX:ReservedCodeCacheSize` | Maximum code cache size                     |
+| `-XX:MaxDirectMemorySize`   | Maximum direct buffer memory                |
+
+### Monitoring Memory Usage  
+
+```java
+void main() {
+
+    Runtime runtime = Runtime.getRuntime();
+    
+    // Heap memory
+    long maxMemory = runtime.maxMemory();
+    long totalMemory = runtime.totalMemory();
+    long freeMemory = runtime.freeMemory();
+    long usedMemory = totalMemory - freeMemory;
+    
+    IO.println("=== Heap Memory ===");
+    IO.println("Max:   " + formatBytes(maxMemory));
+    IO.println("Total: " + formatBytes(totalMemory));
+    IO.println("Used:  " + formatBytes(usedMemory));
+    IO.println("Free:  " + formatBytes(freeMemory));
+    
+    // Processors
+    IO.println("\n=== System ===");
+    IO.println("Available processors: " + runtime.availableProcessors());
+}
+
+String formatBytes(long bytes) {
+    if (bytes < 1024) return bytes + " B";
+    if (bytes < 1024 * 1024) return (bytes / 1024) + " KB";
+    if (bytes < 1024 * 1024 * 1024) return (bytes / 1024 / 1024) + " MB";
+    return (bytes / 1024 / 1024 / 1024) + " GB";
+}
+```
+
+For detailed memory analysis, use the MemoryMXBean:  
+
+```java
+import java.lang.management.ManagementFactory;
+import java.lang.management.MemoryMXBean;
+import java.lang.management.MemoryUsage;
+
+void main() {
+
+    MemoryMXBean memoryBean = ManagementFactory.getMemoryMXBean();
+    
+    MemoryUsage heapUsage = memoryBean.getHeapMemoryUsage();
+    MemoryUsage nonHeapUsage = memoryBean.getNonHeapMemoryUsage();
+    
+    IO.println("=== Heap Memory ===");
+    printMemoryUsage(heapUsage);
+    
+    IO.println("\n=== Non-Heap Memory ===");
+    printMemoryUsage(nonHeapUsage);
+}
+
+void printMemoryUsage(MemoryUsage usage) {
+    IO.println("Init:      " + formatBytes(usage.getInit()));
+    IO.println("Used:      " + formatBytes(usage.getUsed()));
+    IO.println("Committed: " + formatBytes(usage.getCommitted()));
+    IO.println("Max:       " + formatBytes(usage.getMax()));
+}
+
+String formatBytes(long bytes) {
+    if (bytes < 0) return "undefined";
+    if (bytes < 1024) return bytes + " B";
+    if (bytes < 1024 * 1024) return (bytes / 1024) + " KB";
+    return (bytes / 1024 / 1024) + " MB";
+}
+```
+
+
+## Performance Tuning  
+
+Performance tuning in HotSpot involves configuring JVM flags, monitoring  
+runtime behavior, and iteratively adjusting settings based on observations.  
+Effective tuning requires understanding the application's workload  
+characteristics and performance goals.  
+
+### Essential JVM Flags  
+
+**Heap Sizing**:  
+```
+-Xms4g                           # Initial heap size
+-Xmx4g                           # Maximum heap size (set equal to -Xms for production)
+-Xmn1g                           # Young generation size
+```
+
+**GC Selection and Tuning**:  
+```
+-XX:+UseG1GC                     # Use G1 garbage collector
+-XX:MaxGCPauseMillis=200         # Target maximum pause time
+-XX:G1HeapRegionSize=16m         # G1 region size
+```
+
+**JIT Compilation**:  
+```
+-XX:+TieredCompilation           # Enable tiered compilation (default)
+-XX:TieredStopAtLevel=1          # Stop at C1 for faster startup
+-XX:CompileThreshold=5000        # Lower threshold for faster warmup
+```
+
+**Diagnostic Flags**:  
+```
+-XX:+HeapDumpOnOutOfMemoryError  # Generate heap dump on OOM
+-XX:HeapDumpPath=/path/dump.hprof # Heap dump location
+-XX:+PrintFlagsFinal             # Print all JVM flags
+```
+
+### Profiling Tools  
+
+HotSpot includes several tools for performance analysis:  
+
+**Java Flight Recorder (JFR)**: A low-overhead profiling tool built into  
+the JVM. Collects detailed runtime information with minimal performance impact.  
+
+```
+# Enable JFR from command line
+-XX:StartFlightRecording=duration=60s,filename=recording.jfr
+
+# Enable JFR programmatically
+jcmd <pid> JFR.start duration=60s filename=recording.jfr
+```
+
+**JDK Mission Control**: GUI application for analyzing JFR recordings.  
+Visualizes CPU usage, memory allocation, thread activity, and more.  
+
+**VisualVM**: Standalone profiler that can connect to running JVMs.  
+Provides CPU and memory profiling, thread analysis, and heap dumps.  
+
+**Async Profiler**: Third-party profiler with low overhead flame graph  
+generation. Excellent for production profiling.  
+
+```java
+import java.lang.management.ManagementFactory;
+import java.lang.management.GarbageCollectorMXBean;
+
+void main() {
+
+    IO.println("=== GC Statistics ===");
+    
+    for (GarbageCollectorMXBean gc : ManagementFactory.getGarbageCollectorMXBeans()) {
+        IO.println("Collector: " + gc.getName());
+        IO.println("  Collection count: " + gc.getCollectionCount());
+        IO.println("  Collection time:  " + gc.getCollectionTime() + " ms");
+        IO.println("  Memory pools:     " + String.join(", ", gc.getMemoryPoolNames()));
+        IO.println();
+    }
+}
+```
+
+### Tuning Workflow  
+
+1. **Establish Baseline**: Measure current performance with realistic workload  
+2. **Identify Bottleneck**: Use profiling tools to find the constraint  
+3. **Make One Change**: Modify a single setting at a time  
+4. **Measure Impact**: Compare against baseline with same workload  
+5. **Iterate**: Repeat until performance goals are met  
+
+| Symptom                    | Likely Cause           | Tuning Action               |
+|----------------------------|------------------------|------------------------------|
+| Long GC pauses             | Heap too small/large   | Adjust -Xmx, switch GC       |
+| Frequent minor GCs         | Young gen too small    | Increase -Xmn                |
+| Full GCs                   | Old gen fragmentation  | Use G1 or ZGC                |
+| Slow startup               | JIT warmup             | Lower CompileThreshold       |
+| High CPU in GC             | Inefficient collection | Use Parallel or G1 GC        |
+
+
+## Advanced Features  
+
+HotSpot continues to evolve with new features that enhance performance,  
+scalability, and developer productivity.  
+
+### Tiered Compilation Deep Dive  
+
+Tiered compilation was introduced in Java 7 and became the default in Java 8.  
+It combines the benefits of fast C1 compilation with the optimizing power of  
+C2, providing both quick warmup and peak performance.  
+
+The compilation policy considers:  
+- Method invocation frequency  
+- Loop iteration counts  
+- Compilation queue length  
+- Available compiler threads  
+
+```java
+void main() {
+
+    IO.println("=== Compilation Tier Demo ===");
+    
+    // Cold method - interpreted initially
+    int result = calculate(5);
+    IO.println("First call (interpreted): " + result);
+    
+    // Warming up - triggers C1 compilation
+    for (int i = 0; i < 10000; i++) {
+        result = calculate(i % 100);
+    }
+    IO.println("After warmup (C1 compiled): " + result);
+    
+    // Hot path - triggers C2 compilation
+    long total = 0;
+    for (int i = 0; i < 1000000; i++) {
+        total += calculate(i % 100);
+    }
+    IO.println("After hot loop (C2 compiled): total = " + total);
+}
+
+int calculate(int n) {
+    // Simple method that benefits from inlining and optimization
+    int sum = 0;
+    for (int i = 0; i <= n; i++) {
+        sum += i;
+    }
+    return sum;
+}
+```
+
+### GraalVM Integration  
+
+GraalVM is an advanced polyglot virtual machine that includes the Graal  
+compiler—a modern, highly optimizing JIT compiler written in Java. Graal can  
+be used as a drop-in replacement for C2 in HotSpot.  
+
+```
+# Use Graal as the JIT compiler (requires GraalVM or JDK with JVMCI)
+-XX:+UnlockExperimentalVMOptions
+-XX:+EnableJVMCI
+-XX:+UseJVMCICompiler
+```
+
+Graal provides several advantages:  
+- Written in Java for easier maintenance and extension  
+- Advanced optimizations for dynamic languages  
+- Native image compilation (ahead-of-time)  
+- Better support for partial escape analysis  
+
+### Project Loom (Virtual Threads)  
+
+Project Loom introduces virtual threads—lightweight threads managed by the  
+JVM rather than the operating system. Virtual threads enable scalable  
+concurrent applications with the simple thread-per-request model.  
+
+```java
+void main() throws InterruptedException {
+
+    IO.println("=== Virtual Threads Demo ===");
+    
+    var startTime = System.currentTimeMillis();
+    
+    // Create 100,000 virtual threads
+    var threads = new ArrayList<Thread>();
+    for (int i = 0; i < 100_000; i++) {
+        int taskId = i;
+        Thread vt = Thread.ofVirtual().start(() -> {
+            // Simulate blocking I/O
+            try {
+                Thread.sleep(100);
+            } catch (InterruptedException e) {
+                Thread.currentThread().interrupt();
+            }
+        });
+        threads.add(vt);
+    }
+    
+    // Wait for all virtual threads to complete
+    for (Thread t : threads) {
+        t.join();
+    }
+    
+    var duration = System.currentTimeMillis() - startTime;
+    IO.println("Completed 100,000 virtual threads in " + duration + " ms");
+}
+```
+
+Virtual threads are designed for high-throughput I/O-bound workloads. They  
+efficiently handle blocking operations by unmounting from platform threads,  
+allowing a small number of platform threads to execute millions of virtual  
+threads.  
+
+### Project Valhalla (Value Objects)  
+
+Project Valhalla introduces value objects—objects that are defined by their  
+data rather than their identity. Value objects can be flattened into arrays  
+and stored inline, eliminating object header overhead and improving cache  
+locality.  
+
+Value objects will eventually provide:  
+- Primitive-like performance for user-defined types  
+- Specialized generics (no more boxing for primitives)  
+- Better memory layout for data-intensive applications  
+
+### Compact Object Headers  
+
+Recent JDK versions include experimental support for compact object headers,  
+reducing the per-object memory overhead from 12-16 bytes to 8 bytes.  
+
+```
+-XX:+UnlockExperimentalVMOptions
+-XX:+UseCompactObjectHeaders
+```
+
+
+## Common Pitfalls  
+
+Understanding common mistakes helps developers avoid performance problems and  
+configuration issues.  
+
+### Over-Tuning JVM Flags  
+
+One of the most common mistakes is excessive tuning based on assumptions rather  
+than measurements.  
+
+**Problem**: Setting too many JVM flags without understanding their interactions  
+can lead to worse performance or unexpected behavior.  
+
+**Solution**: Start with defaults, measure performance, and tune only based on  
+observed bottlenecks. Modern HotSpot versions have excellent ergonomics that  
+automatically adjust many settings.  
+
+```java
+void main() {
+
+    // Bad: Assuming more threads is always better
+    // -XX:ParallelGCThreads=64 (on an 8-core machine)
+    
+    // Good: Let HotSpot choose based on available processors
+    int processors = Runtime.getRuntime().availableProcessors();
+    IO.println("Available processors: " + processors);
+    IO.println("HotSpot will configure GC threads appropriately");
+    
+    // Only override defaults when measurements show improvement
+}
+```
+
+### Ignoring Application-Level Bottlenecks  
+
+**Problem**: Focusing on JVM tuning when the real issue is in application code,  
+database queries, or external service calls.  
+
+**Solution**: Profile the application first. Often, optimizing algorithms or  
+reducing I/O has far greater impact than JVM tuning.  
+
+```java
+void main() {
+
+    // Example: Inefficient string concatenation in a loop
+    // No amount of JVM tuning will fix this O(n²) algorithm
+    
+    String result = "";
+    for (int i = 0; i < 10000; i++) {
+        result += i + ",";  // Creates new String each iteration
+    }
+    
+    // Better: Use StringBuilder (O(n))
+    var sb = new StringBuilder();
+    for (int i = 0; i < 10000; i++) {
+        sb.append(i).append(",");
+    }
+    result = sb.toString();
+    
+    IO.println("Length: " + result.length());
+}
+```
+
+### Misunderstanding GC Logs  
+
+**Problem**: Misinterpreting garbage collection logs leads to incorrect  
+tuning decisions.  
+
+**Solution**: Learn to read GC logs properly. Understand the difference between  
+minor GC, major GC, and full GC. Know what metrics indicate problems.  
+
+```
+# Enable comprehensive GC logging
+-Xlog:gc*:file=gc.log:time,level,tags:filecount=5,filesize=10m
+```
+
+Key GC log metrics to monitor:  
+
+| Metric                | Healthy Range    | Problem Indicator              |
+|-----------------------|------------------|--------------------------------|
+| Minor GC pause        | < 50ms           | > 200ms regularly              |
+| Full GC frequency     | Rare             | Multiple per minute            |
+| GC throughput         | > 95%            | < 90%                          |
+| Heap after GC         | < 70% of max     | > 90% consistently             |
+
+### Setting -Xms Different from -Xmx  
+
+**Problem**: Setting different values for initial and maximum heap causes  
+the JVM to resize the heap during operation, triggering garbage collections.  
+
+**Solution**: In production, set `-Xms` equal to `-Xmx` to avoid heap resizing.  
+
+```
+# Production configuration - avoid heap resizing
+-Xms4g -Xmx4g
+
+# Development configuration - OK to let heap grow
+-Xms256m -Xmx2g
+```
+
+
+## Best Practices  
+
+Following these guidelines helps achieve optimal HotSpot performance while  
+maintaining system stability.  
+
+### Monitoring Guidelines  
+
+1. **Establish Baseline Metrics**: Before any tuning, capture normal operation  
+   metrics including throughput, latency, GC frequency, and memory usage.  
+
+2. **Use Proper Tools**: JFR for detailed profiling, GC logs for collection  
+   analysis, and metrics systems for long-term trending.  
+
+3. **Monitor in Production**: Performance characteristics differ between  
+   development and production. Monitor continuously.  
+
+```java
+import java.lang.management.ManagementFactory;
+import java.lang.management.ThreadMXBean;
+
+void main() {
+
+    ThreadMXBean threadBean = ManagementFactory.getThreadMXBean();
+    
+    IO.println("=== Thread Monitoring ===");
+    IO.println("Thread count:        " + threadBean.getThreadCount());
+    IO.println("Peak thread count:   " + threadBean.getPeakThreadCount());
+    IO.println("Daemon thread count: " + threadBean.getDaemonThreadCount());
+    
+    // Check for deadlocks
+    long[] deadlockedThreads = threadBean.findDeadlockedThreads();
+    if (deadlockedThreads == null) {
+        IO.println("No deadlocks detected");
+    } else {
+        IO.println("DEADLOCK DETECTED: " + deadlockedThreads.length + " threads");
+    }
+}
+```
+
+### When to Tune vs Accept Defaults  
+
+| Scenario                         | Recommendation                           |
+|----------------------------------|------------------------------------------|
+| Standard web application         | Accept G1 GC defaults                    |
+| Sub-millisecond latency required | Switch to ZGC, tune carefully            |
+| Batch processing                 | Consider Parallel GC for throughput      |
+| Memory constrained environment   | Tune heap sizes, consider Serial GC      |
+| Microservices with fast startup  | Consider GraalVM native image            |
+
+### Production Deployment Checklist  
+
+1. **Memory Configuration**  
+   ```
+   -Xms4g -Xmx4g                     # Equal heap bounds
+   -XX:MaxMetaspaceSize=256m         # Bound metaspace
+   -XX:+HeapDumpOnOutOfMemoryError   # Capture OOM heap dump
+   ```
+
+2. **GC Configuration**  
+   ```
+   -XX:+UseG1GC                      # Default collector
+   -XX:MaxGCPauseMillis=200          # Pause time target
+   -Xlog:gc*:file=gc.log:time        # Enable GC logging
+   ```
+
+3. **Diagnostic Preparation**  
+   ```
+   -XX:+UnlockDiagnosticVMOptions    # Enable diagnostics
+   -XX:+DebugNonSafepoints           # Better profiling accuracy
+   -XX:ErrorFile=/path/hs_err.log    # Error log location
+   ```
+
+### Testing Under Realistic Workloads  
+
+Performance tuning is only valid when tested under production-like conditions:  
+
+- Use production data volumes  
+- Simulate realistic request patterns  
+- Include warmup period before measurements  
+- Run tests for extended periods  
+- Test failure scenarios (high memory, high CPU)  
+
+```java
+void main() throws InterruptedException {
+
+    IO.println("=== Warmup and Measurement Demo ===");
+    
+    // Warmup phase - trigger JIT compilation
+    IO.println("Warming up...");
+    for (int i = 0; i < 100_000; i++) {
+        doWork();
+    }
+    
+    // Measurement phase
+    IO.println("Measuring...");
+    long startTime = System.nanoTime();
+    int iterations = 1_000_000;
+    
+    for (int i = 0; i < iterations; i++) {
+        doWork();
+    }
+    
+    long endTime = System.nanoTime();
+    double avgNanos = (endTime - startTime) / (double) iterations;
+    
+    IO.println("Average time per operation: " + String.format("%.2f", avgNanos) + " ns");
+    IO.println("Operations per second: " + String.format("%.0f", 1_000_000_000.0 / avgNanos));
+}
+
+int doWork() {
+    // Simulated work
+    int result = 0;
+    for (int i = 0; i < 100; i++) {
+        result += i * i;
+    }
+    return result;
+}
+```
+
+
+## Conclusion  
+
+The HotSpot JVM is a sophisticated runtime environment that has enabled Java  
+to achieve excellent performance across a wide range of applications. Its  
+adaptive optimization approach, combining interpretation with tiered JIT  
+compilation, provides both fast startup and peak throughput.  
+
+### Key Takeaways  
+
+| Aspect                | Summary                                              |
+|-----------------------|------------------------------------------------------|
+| Architecture          | Class loading, runtime data areas, execution engine  |
+| Execution Model       | Interpreter + tiered JIT compilation (C1, C2)        |
+| JIT Compilation       | Hot method detection, inlining, escape analysis      |
+| Garbage Collection    | Generational collectors: G1 (default), ZGC, etc.     |
+| Memory Management     | Heap, metaspace, code cache, thread stacks           |
+| Performance Tuning    | Profile first, tune based on measurements            |
+| Advanced Features     | Virtual threads, Graal integration, compact headers  |
+
+Understanding HotSpot internals enables developers to:  
+
+- **Write Efficient Code**: Understanding JIT optimizations helps write code  
+  that compiles well, avoiding patterns that prevent optimization.  
+
+- **Configure for Production**: Knowledge of GC algorithms and memory layout  
+  enables appropriate configuration for specific workload requirements.  
+
+- **Diagnose Performance Issues**: Familiarity with profiling tools and  
+  runtime behavior helps identify and resolve performance bottlenecks.  
+
+- **Plan for Scalability**: Understanding resource usage patterns helps design  
+  systems that scale efficiently with load.  
+
+HotSpot continues to evolve with each JDK release, incorporating new features  
+and optimizations. Staying current with developments—such as virtual threads,  
+value objects, and improved garbage collectors—ensures that applications can  
+take advantage of the latest performance improvements.  
+
+The best approach to HotSpot performance is to start with defaults, measure  
+under realistic conditions, and tune only when measurements indicate specific  
+bottlenecks. Modern HotSpot ergonomics handle most situations well, and  
+over-tuning often causes more problems than it solves.  
diff --git a/intellij.md b/intellij.md
new file mode 100644
index 00000000..c6b27535
--- /dev/null
+++ b/intellij.md
@@ -0,0 +1,17 @@
+# IntelliJ tips
+
+## Shortcuts
+
+- `Alt + J` - Select next identifier
+- `Alt + F1 + 1` - Select file in Project view
+- `Ctrl + Alt + Shift + J` - Select all identifiers
+- `Alt + 1` - Toggle project visibility
+- `Ctrl + B` - Go to definition
+- `Shift + F10` - Run app
+- `Shift + Shift` - Select Anything
+- `Ctrl + Alt + L` - Reformat code
+- `Ctrl + Alt + O` - Organize imports
+- `Ctrl + Q` - Quick info
+- `Ctrl + Alt + G` - Add carets at the end of selection
+- `Ctrl + D` - Duplicate line
+- `Ctrl + Shift + Down` - Move statement down
diff --git a/interview-questions.md b/interview-questions.md
new file mode 100644
index 00000000..8b137891
--- /dev/null
+++ b/interview-questions.md
@@ -0,0 +1 @@
+
diff --git a/io/ReadFileEx.java b/io/ReadFileEx.java
deleted file mode 100644
index b22e479d..00000000
--- a/io/ReadFileEx.java
+++ /dev/null
@@ -1,17 +0,0 @@
-package com.zetcode;
-
-import java.io.IOException;
-import java.nio.file.Files;
-import java.nio.file.Paths;
-
-public class ReadFileEx {
-
-    public static void main(String[] args) throws IOException {
-
-        var path = Paths.get("src/resources/thermopylae.txt");
-
-        var content = Files.readString(path);
-
-        System.out.println(content);
-    }
-}
diff --git a/io/input.md b/io/input.md
new file mode 100644
index 00000000..87ba38aa
--- /dev/null
+++ b/io/input.md
@@ -0,0 +1,23 @@
+# Input
+
+
+## Scanner 
+
+Read input from user from command line
+
+```java
+import java.io.IOException;
+import java.util.Scanner;
+
+void main() throws IOException {
+
+    try (var scanner = new Scanner(System.in)) {
+
+        System.out.print("Enter your name: ");
+        String name = scanner.nextLine(); // Read a line of text (including spaces)
+
+        String msg = STR."Hello \{name}!";
+        System.out.println(msg);
+    }
+}
+```
diff --git a/io/readtext.md b/io/readtext.md
new file mode 100644
index 00000000..5760e759
--- /dev/null
+++ b/io/readtext.md
@@ -0,0 +1,83 @@
+# Read text
+
+
+```
+The Battle of Thermopylae was fought between an alliance of
+Greek city-states, led by King Leonidas of Sparta, and the Persian Empire of
+Xerxes I over the course of three days, during the second Persian invasion of
+Greece. 
+```
+
+This is the `thermopylae.txt` file.  
+
+## FileReader with BufferedReader
+
+```java
+import java.io.BufferedReader;
+import java.io.FileReader;
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+
+void main() throws IOException {
+
+    var fileName = "thermopylae.txt";
+
+    try (var br = new BufferedReader(new FileReader(fileName,
+            StandardCharsets.UTF_8))) {
+
+        String line;
+        while ((line = br.readLine()) != null) {
+
+            System.out.println(line);
+        }
+    }
+}
+```
+
+## Word frequency
+
+```java
+import java.io.BufferedReader;
+import java.io.FileReader;
+import java.io.IOException;
+import java.util.HashMap;
+import java.nio.charset.StandardCharsets;
+
+
+void main() throws IOException {
+
+    var fileName = "thermopylae.txt";
+    var wordFreq = new HashMap<String, Integer>();
+
+    try (var bufferedReader = new BufferedReader(new FileReader(fileName, 
+            StandardCharsets.UTF_8))) {
+
+        String line;
+        while ((line = bufferedReader.readLine()) != null) {
+
+            var words = line.split("\s");
+
+            for (var word : words) {
+
+                if (word.endsWith(",") || word.endsWith("?")
+                    || word.endsWith("!") || word.endsWith(".")) {
+
+                    word = word.substring(0, word.length()-1);
+                }
+
+                if (wordFreq.containsKey(word)) {
+                    wordFreq.put(word, wordFreq.get(word) + 1);
+                } else {
+                    wordFreq.put(word, 1);
+                }
+
+            }
+        }
+
+        wordFreq.forEach((k, v) -> {
+            System.out.printf("%s -> %d%n", k, v);
+        });
+    }
+}
+```
+
diff --git a/io/readtext/FileReaderEx.java b/io/readtext/FileReaderEx.java
deleted file mode 100644
index 738832a6..00000000
--- a/io/readtext/FileReaderEx.java
+++ /dev/null
@@ -1,29 +0,0 @@
-package com.zetcode;
-
-import java.io.BufferedReader;
-import java.io.FileReader;
-import java.io.IOException;
-import java.nio.charset.StandardCharsets;
-
-public class FileReaderEx {
-
-    public static void main(String[] args) throws IOException {
-
-        var fileName = "src/resources/thermopylae.txt";
-
-        try (BufferedReader br = new BufferedReader(
-                new FileReader(fileName, StandardCharsets.UTF_8))) {
-
-            var sb = new StringBuilder();
-
-            String line;
-            while ((line = br.readLine()) != null) {
-
-                sb.append(line);
-                sb.append(System.lineSeparator());
-            }
-
-            System.out.println(sb);
-        }
-    }
-}
diff --git a/io/readtext/FilesLinesEx.java b/io/readtext/FilesLinesEx.java
deleted file mode 100644
index 721d0f9e..00000000
--- a/io/readtext/FilesLinesEx.java
+++ /dev/null
@@ -1,15 +0,0 @@
-package com.zetcode;
-
-import java.io.IOException;
-import java.nio.file.Files;
-import java.nio.file.Paths;
-
-public class FilesLinesEx {
-
-    public static void main(String[] args) throws IOException {
-
-        var fileName = "src/resources/thermopylae.txt";
-
-        Files.lines(Paths.get(fileName)).forEachOrdered(System.out::println);
-    }
-}
diff --git a/io/readtext/README.md b/io/readtext/README.md
new file mode 100644
index 00000000..de93e938
--- /dev/null
+++ b/io/readtext/README.md
@@ -0,0 +1,147 @@
+# Reading text
+
+
+## Files.ReadString
+
+```java
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+
+import java.nio.file.Files;
+import java.nio.file.Paths;
+
+void main() throws IOException {
+
+    var fileName = "thermopylae.txt";
+
+    String contents = Files.readString(Paths.get(fileName),
+            StandardCharsets.UTF_8);
+    System.out.println(contents);
+}
+```
+
+## Files.readAllLines
+
+Read all lines into a list.  
+
+```java
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Paths;
+import java.util.List;
+
+void main() throws IOException {
+
+    var fname = "thermopylae.txt";
+
+    List<String> lines = Files.readAllLines(Paths.get(fname), StandardCharsets.UTF_8);
+
+    for (String line : lines) {
+
+        System.out.println(line);
+    }
+}
+```
+
+## Files.lines
+
+```java
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+
+import java.nio.file.Files;
+import java.nio.file.Paths;
+
+void main() throws IOException {
+
+    var fileName = "thermopylae.txt";
+
+    Files.lines(Paths.get(fileName), 
+        StandardCharsets.UTF_8).forEachOrdered(System.out::println);
+}
+```
+
+## FileReader
+
+```java
+import java.io.BufferedReader;
+import java.io.FileReader;
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+
+void main() throws IOException {
+
+    var fname = "thermopylae.txt";
+
+    try (var br = new BufferedReader(new FileReader(fname, StandardCharsets.UTF_8))) {
+
+        String line;
+        while ((line = br.readLine()) != null) {
+
+            System.out.println(line);
+        }
+
+    }
+}
+```
+
+## FileReader with CharBuffer
+
+```java
+import java.io.FileReader;
+import java.io.IOException;
+import java.nio.CharBuffer;
+import java.nio.charset.StandardCharsets;
+
+void main() {
+
+    String fname = "thermopylae.txt";
+
+    try (var reader = new FileReader(fname, StandardCharsets.UTF_8)) {
+        // Create a CharBuffer with a reasonable size (adjust as needed)
+        var buffer = CharBuffer.allocate(1024);
+
+        int charsRead;
+        StringBuilder content = new StringBuilder();
+
+        // Read characters in chunks using read(CharBuffer)
+        while ((charsRead = reader.read(buffer)) != -1) {
+            // Flip the buffer to prepare it for reading
+            buffer.flip();
+            // Append the read characters to the StringBuilder
+            content.append(buffer);
+            // Clear the buffer for the next read
+            buffer.clear();
+        }
+
+        System.out.println(content.toString());
+    } catch (IOException e) {
+        e.printStackTrace();
+    }
+}
+```
+
+## Scanner 
+
+```java
+
+import java.io.IOException;
+import java.io.File;
+import java.util.Scanner;
+
+void main() throws IOException {
+
+    var fname = "thermopylae.txt";
+
+    try (var scanner = new Scanner(new File(fname))) {
+
+        while (scanner.hasNext()) {
+
+            String line = scanner.nextLine();
+            System.out.println(line);
+        }
+    }
+}
+```
+
diff --git a/io/readtext/ReadAllLinesEx.java b/io/readtext/ReadAllLinesEx.java
deleted file mode 100644
index c213e689..00000000
--- a/io/readtext/ReadAllLinesEx.java
+++ /dev/null
@@ -1,23 +0,0 @@
-package com.zetcode;
-
-import java.io.IOException;
-import java.nio.charset.StandardCharsets;
-import java.nio.file.Files;
-import java.nio.file.Paths;
-import java.util.List;
-
-public class ReadAllLinesEx {
-
-    public static void main(String[] args) throws IOException {
-
-        var fileName = "src/resources/thermopylae.txt";
-
-        List<String> lines = Files.readAllLines(Paths.get(fileName),
-                StandardCharsets.UTF_8);
-
-        for (String line : lines) {
-
-            System.out.println(line);
-        }
-    }
-}
diff --git a/io/readtext/ReadFileAsStringEx.java b/io/readtext/ReadFileAsStringEx.java
deleted file mode 100644
index fea0be5b..00000000
--- a/io/readtext/ReadFileAsStringEx.java
+++ /dev/null
@@ -1,18 +0,0 @@
-package com.zetcode;
-
-import java.io.IOException;
-import java.nio.file.Files;
-import java.nio.file.Paths;
-
-public class ReadFileAsStringEx {
-
-    public static void main(String[] args) throws IOException {
-
-        var fileName = "src/resources/thermopylae.txt";
-        var filePath = Paths.get(fileName);
-
-        var content = Files.readString(filePath);
-
-        System.out.println(content);
-    }
-}
diff --git a/io/readtext/ScannerEx.java b/io/readtext/ScannerEx.java
deleted file mode 100644
index e82f711f..00000000
--- a/io/readtext/ScannerEx.java
+++ /dev/null
@@ -1,22 +0,0 @@
-package com.zetcode;
-
-import java.io.File;
-import java.io.FileNotFoundException;
-import java.util.Scanner;
-
-public class ScannerEx {
-
-    public static void main(String[] args) throws FileNotFoundException {
-
-        var fileName = "src/resources/thermopylae.txt";
-
-        try (var scanner = new Scanner(new File(fileName))) {
-
-            while (scanner.hasNext()) {
-
-                String line = scanner.nextLine();
-                System.out.println(line);
-            }
-        }
-    }
-}
diff --git a/jvm-tuning.md b/jvm-tuning.md
new file mode 100644
index 00000000..465de07d
--- /dev/null
+++ b/jvm-tuning.md
@@ -0,0 +1,1387 @@
+# JVM Tuning and Profiling
+
+**JVM tuning** is the process of adjusting Java Virtual Machine parameters to  
+optimize application performance, memory usage, and response times. **Profiling**  
+involves analyzing runtime behavior to identify bottlenecks, memory leaks, and  
+inefficient code paths. Together, these practices form the foundation of Java  
+performance engineering.  
+
+Understanding JVM tuning and profiling is essential for building high-performance  
+Java applications. Modern applications face demanding requirements: low latency,  
+high throughput, efficient resource utilization, and predictable behavior under  
+load. Without proper tuning, applications may suffer from excessive garbage  
+collection pauses, memory exhaustion, or suboptimal thread utilization.  
+
+Tuning should always be guided by profiling data. Premature optimization based  
+on assumptions often leads to wasted effort or even degraded performance. The  
+correct approach is to measure first, identify actual bottlenecks, apply targeted  
+changes, and validate improvements through repeated measurement.  
+
+## JVM Memory Management Basics  
+
+The JVM manages memory automatically, freeing developers from manual memory  
+allocation and deallocation. However, understanding how the JVM organizes and  
+manages memory is crucial for effective tuning.  
+
+### Memory Regions Overview  
+
+The JVM divides memory into several distinct regions, each serving a specific  
+purpose:  
+
+| Region        | Description                                              |
+|---------------|----------------------------------------------------------|
+| Heap          | Primary storage for objects; managed by garbage collector|
+| Stack         | Per-thread memory for method calls and local variables   |
+| Metaspace     | Class metadata, method definitions, constant pools       |
+| Code Cache    | JIT-compiled native code                                 |
+| Native Memory | Direct buffers, JNI allocations, thread stacks           |
+
+### JVM Memory Architecture Diagram  
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           JVM Process Memory                                │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  ┌───────────────────────────────────────────────────────────────────────┐  │
+│  │                              HEAP                                     │  │
+│  │  ┌─────────────────────────┐  ┌─────────────────────────────────────┐ │  │
+│  │  │      Young Generation   │  │          Old Generation             │ │  │
+│  │  │  ┌───────┐ ┌──────────┐ │  │                                     │ │  │
+│  │  │  │ Eden  │ │ Survivor │ │  │    Long-lived objects survive      │ │  │
+│  │  │  │       │ │  S0 | S1 │ │  │    multiple GC cycles here         │ │  │
+│  │  │  │ New   │ │          │ │  │                                     │ │  │
+│  │  │  │objects│ │ Aging    │ │  │    Collected by Major/Full GC      │ │  │
+│  │  │  │ here  │ │ objects  │ │  │                                     │ │  │
+│  │  │  └───────┘ └──────────┘ │  │                                     │ │  │
+│  │  └─────────────────────────┘  └─────────────────────────────────────┘ │  │
+│  └───────────────────────────────────────────────────────────────────────┘  │
+│                                                                             │
+│  ┌───────────────────────────────────────────────────────────────────────┐  │
+│  │                           NON-HEAP                                    │  │
+│  │  ┌─────────────────┐  ┌─────────────────┐  ┌───────────────────────┐  │  │
+│  │  │    Metaspace    │  │   Code Cache    │  │   Direct Buffers      │  │  │
+│  │  │                 │  │                 │  │                       │  │  │
+│  │  │  Class metadata │  │  JIT compiled   │  │  Off-heap memory      │  │  │
+│  │  │  Method data    │  │  native code    │  │  for NIO operations   │  │  │
+│  │  │  Constant pool  │  │                 │  │                       │  │  │
+│  │  └─────────────────┘  └─────────────────┘  └───────────────────────┘  │  │
+│  └───────────────────────────────────────────────────────────────────────┘  │
+│                                                                             │
+│  ┌───────────────────────────────────────────────────────────────────────┐  │
+│  │                        THREAD STACKS                                  │  │
+│  │  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐     │  │
+│  │  │ Thread1 │  │ Thread2 │  │ Thread3 │  │ Thread4 │  │  ...    │     │  │
+│  │  │  Stack  │  │  Stack  │  │  Stack  │  │  Stack  │  │         │     │  │
+│  │  └─────────┘  └─────────┘  └─────────┘  └─────────┘  └─────────┘     │  │
+│  └───────────────────────────────────────────────────────────────────────┘  │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Heap Memory  
+
+The heap is the runtime data area from which memory for all class instances and  
+arrays is allocated. It is created when the JVM starts and may increase or  
+decrease in size during application runtime.  
+
+**Young Generation**: Where new objects are allocated. Most objects die young  
+and are collected quickly through Minor GC. It is further divided into Eden  
+space (initial allocation) and Survivor spaces (S0 and S1) for aging objects.  
+
+**Old Generation**: Objects that survive multiple Minor GC cycles are promoted  
+here. Collected less frequently through Major GC or Full GC operations.  
+
+### Stack Memory  
+
+Each thread has its own stack, created when the thread is created. The stack  
+stores frames containing local variables, partial results, and method invocation  
+data. Stack size is fixed per thread and configured via `-Xss`.  
+
+```java
+void main() {
+
+    // Each method call creates a new stack frame
+    int result = calculateFactorial(5);
+    println("Factorial: " + result);
+}
+
+int calculateFactorial(int n) {
+    // Local variables stored in stack frame
+    if (n <= 1) {
+        return 1;
+    }
+    // Recursive call creates new stack frame
+    return n * calculateFactorial(n - 1);
+}
+```
+
+Stack memory is automatically reclaimed when a method returns. Deep recursion  
+or excessively large local variables can cause `StackOverflowError`.  
+
+### Metaspace  
+
+Metaspace replaced PermGen in Java 8. It stores class metadata, including:  
+- Class definitions and bytecode  
+- Method metadata and compiled method information  
+- Constant pool data  
+- Annotation processing information  
+
+Unlike PermGen, Metaspace uses native memory and can grow dynamically. It is  
+still subject to garbage collection when classes are unloaded.  
+
+### Garbage Collection Regions (G1 Collector)  
+
+Modern collectors like G1 organize the heap into regions for more efficient  
+collection:  
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         G1 Heap Region Layout                               │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  ┌─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┐  │
+│  │  E  │  E  │  S  │  O  │  O  │  E  │  H  │  H  │  O  │  E  │  S  │  O  │  │
+│  ├─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤  │
+│  │  O  │  E  │  O  │  O  │  E  │  E  │  H  │  O  │  O  │  E  │  E  │  O  │  │
+│  ├─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤  │
+│  │  O  │  O  │  E  │  S  │  O  │  E  │  O  │  O  │  E  │  O  │  O  │  E  │  │
+│  └─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┘  │
+│                                                                             │
+│  E = Eden Region    S = Survivor Region    O = Old Region    H = Humongous  │
+│                                                                             │
+│  - Each region is typically 1-32 MB in size                                 │
+│  - Regions can change role dynamically                                      │
+│  - Humongous regions store objects larger than half a region                │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Tuning with JVM Flags  
+
+JVM flags control memory allocation, garbage collection behavior, and various  
+runtime optimizations. Flags are categorized into standard options (stable across  
+releases) and non-standard options (may change between JVM versions).  
+
+### Flag Categories  
+
+| Prefix     | Description                                              |
+|------------|----------------------------------------------------------|
+| `-`        | Standard options (e.g., `-version`, `-classpath`)        |
+| `-X`       | Non-standard options, relatively stable                  |
+| `-XX:`     | Advanced options, may change without notice              |
+| `-XX:+`    | Enable boolean option                                    |
+| `-XX:-`    | Disable boolean option                                   |
+| `-XX:=`    | Set numeric or string value                              |
+
+### Heap Size Flags  
+
+#### Maximum Heap Size (-Xmx)  
+
+The `-Xmx` flag sets the maximum heap size the JVM can allocate. When heap  
+usage approaches this limit, aggressive garbage collection occurs. If memory  
+cannot be freed, `OutOfMemoryError` is thrown.  
+
+```bash
+# Set maximum heap to 4 gigabytes
+java -Xmx4g MyApplication
+
+# Set maximum heap to 2048 megabytes
+java -Xmx2048m MyApplication
+
+# Set maximum heap to specific kilobytes
+java -Xmx2097152k MyApplication
+```
+
+**Best practices for -Xmx:**  
+- Set based on available physical memory (typically 50-75% of total RAM)  
+- Account for non-heap memory (Metaspace, native memory, thread stacks)  
+- Monitor actual usage before increasing; larger heaps mean longer GC pauses  
+- Container deployments should consider memory limits carefully  
+
+#### Initial Heap Size (-Xms)  
+
+The `-Xms` flag sets the initial heap size. The JVM starts with this amount  
+and grows toward `-Xmx` as needed. Setting `-Xms` equal to `-Xmx` prevents  
+heap resizing during runtime.  
+
+```bash
+# Start with 2GB, can grow to 4GB
+java -Xms2g -Xmx4g MyApplication
+
+# Fixed heap size of 4GB (recommended for production)
+java -Xms4g -Xmx4g MyApplication
+```
+
+**Best practices for -Xms:**  
+- Set equal to `-Xmx` for production systems to avoid resize overhead  
+- Lower values acceptable for development to conserve resources  
+- Monitor startup time; larger initial heap may slow JVM initialization  
+
+#### Viewing Current Memory Settings  
+
+```java
+void main() {
+
+    var runtime = Runtime.getRuntime();
+
+    long maxMemory = runtime.maxMemory();
+    long totalMemory = runtime.totalMemory();
+    long freeMemory = runtime.freeMemory();
+    long usedMemory = totalMemory - freeMemory;
+
+    println("JVM Memory Information:");
+    println("─".repeat(50));
+    println("Max Memory (Xmx):     " + formatBytes(maxMemory));
+    println("Total Memory:         " + formatBytes(totalMemory));
+    println("Used Memory:          " + formatBytes(usedMemory));
+    println("Free Memory:          " + formatBytes(freeMemory));
+    println("Available Processors: " + runtime.availableProcessors());
+}
+
+String formatBytes(long bytes) {
+    if (bytes < 1024) return bytes + " B";
+    if (bytes < 1024 * 1024) return (bytes / 1024) + " KB";
+    if (bytes < 1024 * 1024 * 1024) return (bytes / (1024 * 1024)) + " MB";
+    return String.format("%.2f GB", bytes / (1024.0 * 1024 * 1024));
+}
+```
+
+Running this program shows current JVM memory configuration. Use it to verify  
+that your flags are applied correctly.  
+
+### Garbage Collection Flags  
+
+The JVM includes several garbage collectors, each optimized for different  
+workloads. Selecting the appropriate collector significantly impacts performance.  
+
+#### Garbage Collector Comparison  
+
+| Collector      | Best For                    | Pause Times    | Throughput     |
+|----------------|-----------------------------|----------------|----------------|
+| G1GC           | General purpose, balanced   | Medium (10-200ms) | High        |
+| ZGC            | Low latency, large heaps    | Very low (<1-10ms) | High       |
+| Shenandoah     | Low latency, any heap size  | Very low (<10ms)   | High       |
+| Parallel GC    | Batch processing, throughput| Higher         | Highest        |
+| Serial GC      | Small heaps, single CPU     | Variable       | Low            |
+
+#### G1 Garbage Collector  
+
+G1 (Garbage-First) is the default collector since Java 9. It divides the heap  
+into regions and prioritizes collecting regions with the most garbage.  
+
+```bash
+# Enable G1GC (default in Java 9+)
+java -XX:+UseG1GC MyApplication
+
+# Set target pause time (milliseconds)
+java -XX:+UseG1GC -XX:MaxGCPauseMillis=200 MyApplication
+
+# Set heap region size (1MB-32MB, must be power of 2)
+java -XX:+UseG1GC -XX:G1HeapRegionSize=16m MyApplication
+
+# Tune concurrent GC threads
+java -XX:+UseG1GC -XX:ConcGCThreads=4 MyApplication
+```
+
+**Key G1 tuning options:**  
+
+| Flag                        | Description                              |
+|-----------------------------|------------------------------------------|
+| `-XX:MaxGCPauseMillis=200`  | Target maximum GC pause time             |
+| `-XX:G1HeapRegionSize=16m`  | Size of G1 heap regions                  |
+| `-XX:G1NewSizePercent=5`    | Minimum young generation percentage      |
+| `-XX:G1MaxNewSizePercent=60`| Maximum young generation percentage      |
+| `-XX:InitiatingHeapOccupancyPercent=45` | Heap occupancy to trigger marking |
+
+#### ZGC (Z Garbage Collector)  
+
+ZGC is designed for applications requiring extremely low latency. It performs  
+most work concurrently, keeping pause times consistently under 10ms regardless  
+of heap size.  
+
+```bash
+# Enable ZGC
+java -XX:+UseZGC MyApplication
+
+# ZGC with generational mode (Java 21+)
+java -XX:+UseZGC -XX:+ZGenerational MyApplication
+
+# Set concurrent GC threads
+java -XX:+UseZGC -XX:ConcGCThreads=4 MyApplication
+```
+
+**ZGC characteristics:**  
+- Pause times typically under 1ms  
+- Scales to multi-terabyte heaps  
+- Slightly lower throughput than G1  
+- Best for latency-sensitive applications  
+
+#### Shenandoah GC  
+
+Shenandoah is another low-pause collector, performing concurrent compaction  
+to minimize stop-the-world pauses.  
+
+```bash
+# Enable Shenandoah
+java -XX:+UseShenandoahGC MyApplication
+
+# Set heuristics mode
+java -XX:+UseShenandoahGC -XX:ShenandoahGCHeuristics=adaptive MyApplication
+
+# Compact mode for smaller heaps
+java -XX:+UseShenandoahGC -XX:ShenandoahGCHeuristics=compact MyApplication
+```
+
+#### Parallel GC  
+
+Parallel GC maximizes throughput by using multiple threads for collection.  
+It is ideal for batch processing where pause times are acceptable.  
+
+```bash
+# Enable Parallel GC
+java -XX:+UseParallelGC MyApplication
+
+# Set number of GC threads
+java -XX:+UseParallelGC -XX:ParallelGCThreads=8 MyApplication
+
+# Enable adaptive sizing
+java -XX:+UseParallelGC -XX:+UseAdaptiveSizePolicy MyApplication
+```
+
+### Other Useful Flags  
+
+#### Metaspace Configuration  
+
+```bash
+# Set maximum Metaspace size
+java -XX:MaxMetaspaceSize=256m MyApplication
+
+# Set initial Metaspace size
+java -XX:MetaspaceSize=128m MyApplication
+
+# Limit class metadata allocation
+java -XX:CompressedClassSpaceSize=128m MyApplication
+```
+
+#### GC Logging Flags  
+
+Modern GC logging (Java 9+) uses the Unified Logging Framework:  
+
+```bash
+# Basic GC logging
+java -Xlog:gc MyApplication
+
+# Detailed GC logging with timestamps
+java -Xlog:gc*:file=gc.log:time,uptime,level,tags MyApplication
+
+# Include heap information
+java -Xlog:gc+heap=debug:file=gc.log MyApplication
+
+# Log GC pauses only
+java -Xlog:gc+pause=info MyApplication
+```
+
+**Legacy GC logging (Java 8):**  
+
+```bash
+# Print GC details (Java 8)
+java -XX:+PrintGCDetails -XX:+PrintGCDateStamps MyApplication
+
+# Write to file
+java -XX:+PrintGCDetails -Xloggc:gc.log MyApplication
+```
+
+#### Heap Dump Configuration  
+
+```bash
+# Generate heap dump on OutOfMemoryError
+java -XX:+HeapDumpOnOutOfMemoryError MyApplication
+
+# Specify heap dump location
+java -XX:+HeapDumpOnOutOfMemoryError \
+     -XX:HeapDumpPath=/var/dumps/heap.hprof MyApplication
+
+# Run script on OutOfMemoryError
+java -XX:+HeapDumpOnOutOfMemoryError \
+     -XX:OnOutOfMemoryError="./notify-admin.sh %p" MyApplication
+```
+
+#### Thread Stack Size  
+
+```bash
+# Set thread stack size to 512KB
+java -Xss512k MyApplication
+
+# Larger stacks for deep recursion
+java -Xss2m MyApplication
+```
+
+### Complete Flag Reference Table  
+
+| Flag                              | Description                          |
+|-----------------------------------|--------------------------------------|
+| `-Xmx<size>`                      | Maximum heap size                    |
+| `-Xms<size>`                      | Initial heap size                    |
+| `-Xss<size>`                      | Thread stack size                    |
+| `-XX:+UseG1GC`                    | Enable G1 garbage collector          |
+| `-XX:+UseZGC`                     | Enable Z garbage collector           |
+| `-XX:+UseShenandoahGC`            | Enable Shenandoah collector          |
+| `-XX:+UseParallelGC`              | Enable Parallel collector            |
+| `-XX:MaxGCPauseMillis=<ms>`       | Target maximum GC pause time         |
+| `-XX:MaxMetaspaceSize=<size>`     | Maximum Metaspace size               |
+| `-XX:+HeapDumpOnOutOfMemoryError` | Dump heap on OOM                     |
+| `-XX:HeapDumpPath=<path>`         | Heap dump file location              |
+| `-Xlog:gc*`                       | Enable GC logging                    |
+| `-XX:+PrintFlagsFinal`            | Print all flag values                |
+| `-XX:+UnlockDiagnosticVMOptions`  | Enable diagnostic options            |
+| `-XX:+UnlockExperimentalVMOptions`| Enable experimental options          |
+
+## Profiling Tools  
+
+Profiling tools provide visibility into application behavior, enabling data-  
+driven optimization decisions. Java includes several powerful profiling tools  
+that integrate directly with the JVM.  
+
+### Java Flight Recorder (JFR)  
+
+Java Flight Recorder is a low-overhead profiling framework built into the JVM.  
+It continuously collects diagnostic data with minimal performance impact,  
+making it suitable for production environments.  
+
+#### Enabling JFR  
+
+```bash
+# Start recording from command line
+java -XX:StartFlightRecording=duration=60s,filename=recording.jfr \
+     MyApplication
+
+# Start with continuous recording
+java -XX:StartFlightRecording=disk=true,maxage=1h,maxsize=500m \
+     MyApplication
+
+# Start recording without disk writes
+java -XX:StartFlightRecording=memory MyApplication
+```
+
+#### Recording Settings  
+
+| Setting            | Description                                       |
+|--------------------|---------------------------------------------------|
+| `duration`         | Recording length (e.g., `60s`, `5m`, `1h`)        |
+| `filename`         | Output file path                                  |
+| `disk`             | Enable disk repository (`true`/`false`)           |
+| `maxage`           | Maximum age of data to keep                       |
+| `maxsize`          | Maximum disk space for recording                  |
+| `settings`         | Predefined profile (`default`, `profile`)         |
+
+#### Starting Recording Programmatically  
+
+```java
+import jdk.jfr.Configuration;
+import jdk.jfr.Recording;
+
+import java.nio.file.Path;
+
+void main() throws Exception {
+
+    // Load a configuration
+    var config = Configuration.getConfiguration("profile");
+
+    // Create and start recording
+    var recording = new Recording(config);
+    recording.setName("MyRecording");
+    recording.setMaxAge(java.time.Duration.ofMinutes(10));
+    recording.start();
+
+    println("Recording started: " + recording.getName());
+    println("Recording ID: " + recording.getId());
+
+    // Run your application workload here
+    simulateWorkload();
+
+    // Stop and save recording
+    recording.stop();
+    recording.dump(Path.of("programmatic-recording.jfr"));
+
+    println("Recording saved to programmatic-recording.jfr");
+    recording.close();
+}
+
+void simulateWorkload() throws InterruptedException {
+    var list = new ArrayList<String>();
+    for (int i = 0; i < 100000; i++) {
+        list.add("Item " + i);
+        if (i % 10000 == 0) {
+            Thread.sleep(100);
+            println("Processed " + i + " items");
+        }
+    }
+}
+```
+
+This example creates a JFR recording programmatically, which is useful for  
+capturing specific application scenarios or integrating profiling into  
+automated testing.  
+
+#### Creating Custom JFR Events  
+
+```java
+import jdk.jfr.Category;
+import jdk.jfr.Description;
+import jdk.jfr.Event;
+import jdk.jfr.Label;
+import jdk.jfr.Name;
+
+@Name("com.example.OrderProcessed")
+@Label("Order Processed")
+@Category("Business Events")
+@Description("Fired when an order is successfully processed")
+class OrderProcessedEvent extends Event {
+
+    @Label("Order ID")
+    String orderId;
+
+    @Label("Customer")
+    String customer;
+
+    @Label("Total Amount")
+    double amount;
+
+    @Label("Processing Time (ms)")
+    long processingTimeMs;
+}
+
+void main() {
+
+    // Process several orders
+    for (int i = 1; i <= 5; i++) {
+        processOrder("ORD-" + i, "Customer-" + i, i * 100.0);
+    }
+
+    println("Order processing complete");
+}
+
+void processOrder(String orderId, String customer, double amount) {
+
+    var event = new OrderProcessedEvent();
+    event.orderId = orderId;
+    event.customer = customer;
+    event.amount = amount;
+
+    long startTime = System.currentTimeMillis();
+
+    // Simulate order processing
+    try {
+        Thread.sleep((long) (Math.random() * 100 + 50));
+    } catch (InterruptedException e) {
+        Thread.currentThread().interrupt();
+    }
+
+    event.processingTimeMs = System.currentTimeMillis() - startTime;
+
+    // Commit the event if enabled
+    event.commit();
+
+    println("Processed order: " + orderId + 
+            " in " + event.processingTimeMs + "ms");
+}
+```
+
+Custom events enable tracking application-specific metrics alongside standard  
+JVM events. They are invaluable for correlating business logic with system  
+behavior.  
+
+#### Analyzing JFR Recordings  
+
+Use `jfr` command-line tool to extract data from recordings:  
+
+```bash
+# Print recording summary
+jfr summary recording.jfr
+
+# Print specific event types
+jfr print --events jdk.GCPhasePause recording.jfr
+
+# Print CPU sampling data
+jfr print --events jdk.ExecutionSample recording.jfr
+
+# Export to JSON format
+jfr print --json recording.jfr > recording.json
+
+# List all event types
+jfr metadata recording.jfr
+```
+
+### VisualVM  
+
+VisualVM is a graphical tool for monitoring, troubleshooting, and profiling  
+Java applications. It combines several command-line JDK tools into an intuitive  
+interface.  
+
+#### Key Features  
+
+| Feature             | Description                                        |
+|---------------------|---------------------------------------------------|
+| Monitor             | Real-time CPU, memory, classes, threads display   |
+| Threads             | Thread state visualization and deadlock detection |
+| Sampler             | CPU and memory sampling with low overhead         |
+| Profiler            | Detailed method-level CPU and memory profiling    |
+| Heap Dump           | Capture and analyze heap snapshots                |
+| Thread Dump         | Capture and view thread stack traces              |
+
+#### Installation and Setup  
+
+VisualVM is available as a standalone download or bundled with GraalVM. For  
+remote profiling, start the application with JMX enabled:  
+
+```bash
+# Enable JMX for remote connection
+java -Dcom.sun.management.jmxremote \
+     -Dcom.sun.management.jmxremote.port=9090 \
+     -Dcom.sun.management.jmxremote.authenticate=false \
+     -Dcom.sun.management.jmxremote.ssl=false \
+     MyApplication
+```
+
+#### Diagnosing Memory Leaks  
+
+Memory leaks occur when objects are no longer needed but remain reachable,  
+preventing garbage collection. VisualVM helps identify leaks through:  
+
+1. **Monitor tab**: Watch heap usage grow over time without stabilizing  
+2. **Sampler tab**: Identify classes consuming the most memory  
+3. **Heap Dump**: Analyze object references to find retention paths  
+
+```java
+import java.util.HashMap;
+
+void main() throws InterruptedException {
+
+    // Simulated memory leak: map grows indefinitely
+    var leakyMap = new HashMap<String, byte[]>();
+
+    int counter = 0;
+    while (counter < 1000) {
+        // Each entry holds 1MB, never removed
+        leakyMap.put("key-" + counter, new byte[1024 * 1024]);
+        counter++;
+
+        if (counter % 100 == 0) {
+            println("Entries: " + counter + 
+                    ", Memory: " + formatBytes(
+                        Runtime.getRuntime().totalMemory() - 
+                        Runtime.getRuntime().freeMemory()));
+        }
+
+        Thread.sleep(100);
+    }
+}
+
+String formatBytes(long bytes) {
+    return String.format("%.2f MB", bytes / (1024.0 * 1024));
+}
+```
+
+When profiling this application with VisualVM:  
+1. Connect to the running application  
+2. Open the Monitor tab to observe heap growth  
+3. Take a heap dump when memory is high  
+4. Analyze retained size by class to find the byte[] arrays  
+5. Trace references to discover the HashMap holding them  
+
+### JDK Mission Control  
+
+JDK Mission Control (JMC) is an advanced suite of tools for analyzing JFR  
+recordings. It provides deep insights into application behavior through  
+specialized views and automated analysis.  
+
+#### Key Analysis Views  
+
+| View                | Purpose                                           |
+|---------------------|---------------------------------------------------|
+| Outline             | High-level recording summary                      |
+| Method Profiling    | Hot methods and call stacks                       |
+| Memory              | Allocation patterns and object statistics         |
+| Lock Instances      | Contention analysis and lock profiling            |
+| Garbage Collections | GC events, durations, and pause analysis          |
+| Event Browser       | Raw access to all recorded events                 |
+
+#### Automated Analysis  
+
+JMC includes an automated analysis engine that examines recordings and  
+provides actionable recommendations:  
+
+- Memory pressure warnings  
+- Thread contention hotspots  
+- I/O bottleneck identification  
+- GC inefficiency detection  
+- Code execution anomalies  
+
+#### Starting Recording for JMC  
+
+```bash
+# Detailed recording for JMC analysis
+java -XX:StartFlightRecording=settings=profile,\
+     duration=5m,\
+     filename=analysis.jfr \
+     MyApplication
+
+# Continuous recording for production
+java -XX:StartFlightRecording=settings=default,\
+     disk=true,\
+     maxage=24h,\
+     dumponexit=true,\
+     dumponexitpath=exit-recording.jfr \
+     MyApplication
+```
+
+### Profiling Tools Comparison  
+
+| Tool               | Best For                    | Overhead   | Production-Safe |
+|--------------------|-----------------------------|------------|-----------------|
+| JFR                | Continuous monitoring       | Very Low   | Yes             |
+| VisualVM           | Interactive debugging       | Medium     | Development     |
+| JMC                | Deep analysis of JFR files  | N/A        | Analysis tool   |
+| async-profiler     | CPU/allocation profiling    | Low        | Yes             |
+| jstack             | Quick thread dump           | Minimal    | Yes             |
+| jmap               | Heap statistics/dump        | High       | With caution    |
+
+## Performance Tuning Workflow  
+
+Effective performance tuning follows a systematic, iterative process. Avoid  
+random flag changes; instead, use data to guide decisions.  
+
+### Step-by-Step Tuning Process  
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                      Performance Tuning Workflow                            │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│   ┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐             │
+│   │  1.     │     │  2.     │     │  3.     │     │  4.     │             │
+│   │ MEASURE │────►│ ANALYZE │────►│  TUNE   │────►│ VERIFY  │────┐        │
+│   │         │     │         │     │         │     │         │    │        │
+│   └─────────┘     └─────────┘     └─────────┘     └─────────┘    │        │
+│        ▲                                                          │        │
+│        │                                                          │        │
+│        └──────────────────────────────────────────────────────────┘        │
+│                              Iterate                                        │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Step 1: Measure (Identify Performance Issues)  
+
+Before tuning, establish baseline metrics:  
+
+```bash
+# Enable GC logging
+java -Xlog:gc*:file=baseline-gc.log:time,level,tags \
+     -XX:+HeapDumpOnOutOfMemoryError \
+     MyApplication
+
+# Start JFR recording
+java -XX:StartFlightRecording=duration=10m,filename=baseline.jfr \
+     MyApplication
+```
+
+Key metrics to capture:  
+- Response times (p50, p95, p99 percentiles)  
+- Throughput (requests/second)  
+- GC pause times and frequency  
+- Heap usage patterns  
+- CPU utilization  
+- Thread counts and states  
+
+### Step 2: Analyze (Collect and Interpret Profiling Data)  
+
+Use profiling tools to identify bottlenecks:  
+
+```bash
+# Analyze GC patterns
+jfr print --events jdk.GCPhasePause,jdk.GarbageCollection baseline.jfr
+
+# Find hot methods
+jfr print --events jdk.ExecutionSample baseline.jfr | \
+    sort | uniq -c | sort -rn | head -20
+
+# Check memory allocation
+jfr print --events jdk.ObjectAllocationInNewTLAB baseline.jfr
+```
+
+Common findings and solutions:  
+
+| Finding                        | Likely Cause                    | Solution            |
+|--------------------------------|---------------------------------|---------------------|
+| Frequent Full GC               | Heap too small or leak          | Increase Xmx, fix leak |
+| High GC pause times            | Large old generation            | Tune GC, consider ZGC  |
+| Many young GC collections      | High allocation rate            | Reduce object creation |
+| Thread contention              | Lock bottlenecks                | Reduce synchronization |
+| High CPU in specific methods   | Algorithmic inefficiency        | Optimize code          |
+
+### Step 3: Tune (Adjust JVM Flags)  
+
+Apply targeted changes based on analysis:  
+
+```bash
+# If heap is too small
+java -Xms4g -Xmx4g MyApplication
+
+# If GC pauses are too long
+java -XX:+UseZGC MyApplication
+
+# If throughput is priority
+java -XX:+UseParallelGC -XX:ParallelGCThreads=8 MyApplication
+
+# Combined tuning example
+java -Xms8g -Xmx8g \
+     -XX:+UseG1GC \
+     -XX:MaxGCPauseMillis=100 \
+     -XX:+HeapDumpOnOutOfMemoryError \
+     -Xlog:gc*:file=tuned-gc.log:time,level,tags \
+     MyApplication
+```
+
+### Step 4: Verify (Validate Improvements)  
+
+Compare tuned metrics against baseline:  
+
+```bash
+# Record with same duration as baseline
+java -XX:StartFlightRecording=duration=10m,filename=tuned.jfr \
+     [tuning flags] \
+     MyApplication
+```
+
+Verification criteria:  
+- Did target metric improve?  
+- Did other metrics degrade?  
+- Is improvement consistent under load?  
+- Does change behave as expected?  
+
+### Sample Workflow: VisualVM and JFR  
+
+This example demonstrates a complete tuning cycle:  
+
+**Scenario**: Application has slow response times during peak load.  
+
+**Step 1: Measure**  
+```bash
+# Start with JFR recording and GC logging
+java -XX:StartFlightRecording=settings=profile,duration=30m,\
+     filename=perf-issue.jfr \
+     -Xlog:gc*:file=perf-gc.log:time,level,tags \
+     -Xms2g -Xmx2g \
+     MyApplication
+```
+
+**Step 2: Analyze in JMC**  
+Open `perf-issue.jfr` in JDK Mission Control:  
+1. Check Automated Analysis for warnings  
+2. Review GC tab: many Full GCs taking >500ms  
+3. Memory tab: heap consistently near 100%  
+4. Conclusion: Heap is too small  
+
+**Step 3: Tune**  
+```bash
+# Increase heap and set initial = max
+java -Xms4g -Xmx4g \
+     -XX:StartFlightRecording=settings=profile,duration=30m,\
+     filename=after-tune.jfr \
+     -Xlog:gc*:file=after-tune-gc.log:time,level,tags \
+     MyApplication
+```
+
+**Step 4: Verify**  
+Compare recordings in JMC:  
+- Full GC count: 47 → 3  
+- Average GC pause: 423ms → 45ms  
+- p99 response time: 2.3s → 0.8s  
+
+The change achieved the goal. Document the configuration and monitor  
+production metrics.  
+
+## Best Practices  
+
+Following these guidelines leads to more effective and maintainable  
+performance tuning.  
+
+### Start with Defaults  
+
+Modern JVMs are well-tuned for general workloads. The HotSpot JVM uses  
+ergonomics to automatically configure many settings based on available  
+resources.  
+
+```bash
+# Let JVM choose GC and heap size
+java MyApplication
+
+# View auto-selected options
+java -XX:+PrintFlagsFinal -version 2>&1 | grep -E "UseG1GC|MaxHeapSize"
+```
+
+Only override defaults when profiling reveals specific issues.  
+
+### Test Under Realistic Workloads  
+
+Tuning in isolation often produces misleading results. Performance  
+characteristics change significantly between test and production:  
+
+| Factor              | Test Environment        | Production              |
+|---------------------|------------------------|-------------------------|
+| Data volume         | Sample data            | Full dataset            |
+| Concurrent users    | 1-10                   | 100-10000+              |
+| Request patterns    | Uniform                | Spiky, varied           |
+| Duration            | Minutes                | Days/weeks              |
+| External services   | Mocked                 | Real latency            |
+
+Use load testing tools (JMeter, Gatling, k6) to simulate production  
+conditions during tuning.  
+
+### Monitor GC Logs and Heap Usage  
+
+Establish continuous monitoring in production:  
+
+```bash
+# Production GC logging configuration
+java -Xlog:gc*:file=/var/log/app/gc.log:time,uptime,level,tags:filecount=10,filesize=100m \
+     -XX:+HeapDumpOnOutOfMemoryError \
+     -XX:HeapDumpPath=/var/dumps/ \
+     MyApplication
+```
+
+Key monitoring metrics:  
+- GC pause time distribution (especially p99)  
+- GC frequency and type (Minor vs Full)  
+- Heap occupancy over time  
+- Promotion rate (objects moving to old generation)  
+- Allocation rate  
+
+### Profile Before Changing Flags  
+
+Never tune blindly. Each change should address a specific, measured issue:  
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                    Flag Change Decision Process                             │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│   Question                           │  Action                              │
+│   ─────────────────────────────────  │  ──────────────────────────────────  │
+│   Is there a performance problem?    │  No  → Don't tune                   │
+│   Have you profiled?                 │  No  → Profile first                │
+│   Did profiling identify root cause? │  No  → Investigate more             │
+│   Will this flag address the cause?  │  No  → Find correct solution        │
+│   Have you tested the change?        │  No  → Test in staging              │
+│   Does it improve target metric?     │  No  → Revert and try alternative   │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Document Configuration Decisions  
+
+Maintain records of tuning decisions:  
+
+```bash
+# production-jvm-config.sh
+# JVM Configuration for Order Processing Service
+# Last updated: 2024-01-15
+# Owner: Performance Team
+
+# Heap Configuration
+# Reason: Production load analysis showed peak usage of 3.2GB
+HEAP_OPTS="-Xms4g -Xmx4g"
+
+# GC Configuration  
+# Reason: p99 latency requirement of <100ms
+GC_OPTS="-XX:+UseG1GC -XX:MaxGCPauseMillis=80"
+
+# Monitoring
+# Reason: Required for production troubleshooting
+MONITOR_OPTS="-Xlog:gc*:file=/var/log/gc.log:time,level,tags"
+MONITOR_OPTS="$MONITOR_OPTS -XX:+HeapDumpOnOutOfMemoryError"
+MONITOR_OPTS="$MONITOR_OPTS -XX:HeapDumpPath=/var/dumps"
+
+java $HEAP_OPTS $GC_OPTS $MONITOR_OPTS -jar app.jar
+```
+
+## Common Pitfalls  
+
+Avoid these frequent mistakes when tuning JVM performance.  
+
+### Setting Heap Sizes Incorrectly  
+
+**Too Small**: Causes frequent garbage collection, OutOfMemoryError, and  
+degraded performance. The JVM spends more time collecting than executing  
+application code.  
+
+**Too Large**: Results in longer GC pauses, slower startup, and wasted  
+resources. Very large heaps may exceed physical memory, causing swapping.  
+
+```bash
+# Incorrect: Heap larger than physical RAM
+java -Xmx32g MyApplication  # On machine with 16GB RAM
+
+# Incorrect: Heap too small for workload
+java -Xmx256m MyApplication  # With 2GB working set
+
+# Correct: Sized based on analysis, accounting for non-heap
+java -Xmx12g MyApplication  # On 16GB machine (leaves room for OS, Metaspace)
+```
+
+### Misinterpreting GC Logs  
+
+Common log interpretation errors:  
+
+| Misinterpretation           | Reality                                  |
+|-----------------------------|------------------------------------------|
+| All GC is bad               | Minor GC is normal and efficient         |
+| Longer pause = bigger heap  | Pause depends on live objects, not heap  |
+| More GC threads always helps| Too many causes contention               |
+| G1 needs extensive tuning   | Defaults work well for most workloads    |
+
+**Example log entry:**  
+```
+[2024-01-15T10:30:00.123+0000] GC(42) Pause Young (Normal) 
+    (G1 Evacuation Pause) 2048M->1024M(4096M) 45.123ms
+```
+
+Interpretation:  
+- Minor GC (#42), copying live objects from young generation  
+- Heap reduced from 2GB to 1GB (4GB max)  
+- Pause of 45ms - acceptable for G1  
+
+### Ignoring Application-Level Bottlenecks  
+
+JVM tuning cannot fix algorithmic problems:  
+
+```java
+void main() {
+
+    // No amount of JVM tuning helps this inefficient code
+    var list = new ArrayList<String>();
+    for (int i = 0; i < 100000; i++) {
+        list.add("item-" + i);
+    }
+
+    // O(n) lookup instead of O(1) with Set
+    for (int i = 0; i < 100000; i++) {
+        boolean found = list.contains("item-" + i);  // Slow!
+    }
+}
+```
+
+Profiling with JFR or VisualVM would show hot spots in `ArrayList.contains`.  
+The solution is changing data structure, not GC tuning.  
+
+### Over-Reliance on Tuning Without Profiling  
+
+The "cargo cult" approach of copying configurations without understanding:  
+
+```bash
+# Copied from blog post without context
+java -Xms32g -Xmx32g \
+     -XX:+UseG1GC \
+     -XX:MaxGCPauseMillis=50 \
+     -XX:G1HeapRegionSize=32m \
+     -XX:G1NewSizePercent=30 \
+     -XX:G1MaxNewSizePercent=50 \
+     -XX:InitiatingHeapOccupancyPercent=35 \
+     -XX:G1MixedGCLiveThresholdPercent=85 \
+     -XX:ConcGCThreads=8 \
+     -XX:ParallelGCThreads=16 \
+     MyApplication
+```
+
+Problems with this approach:  
+- Heap size may be wrong for your hardware  
+- Pause time target may be unrealistic  
+- Thread counts may not match CPU count  
+- Some flags may conflict or be deprecated  
+
+### Tuning in Wrong Environment  
+
+Development and production environments differ significantly:  
+
+| Aspect                | Development           | Production            |
+|-----------------------|-----------------------|-----------------------|
+| Heap size             | 512MB                 | 4GB+                  |
+| CPU cores             | 4                     | 16+                   |
+| OS memory             | Shared                | Dedicated             |
+| JIT optimization      | Minimal               | Fully warmed          |
+| Class loading         | Dynamic               | Stable                |
+
+Always validate tuning changes in an environment that mirrors production.  
+
+## Examples  
+
+These examples provide starting configurations for common deployment scenarios.  
+Adjust based on your specific requirements and profiling results.  
+
+### Web Application Configuration  
+
+Web applications typically prioritize low latency and consistent response times.  
+
+```bash
+#!/bin/bash
+# Web Application JVM Configuration
+# Characteristics: Many concurrent requests, session state, moderate heap
+
+# Heap: 4GB for medium traffic site
+HEAP="-Xms4g -Xmx4g"
+
+# G1GC with low pause target
+GC="-XX:+UseG1GC"
+GC="$GC -XX:MaxGCPauseMillis=100"
+GC="$GC -XX:+ParallelRefProcEnabled"
+
+# Large code cache for compiled JSPs/servlets
+CODE_CACHE="-XX:ReservedCodeCacheSize=256m"
+
+# Thread stack (default is usually fine)
+STACK="-Xss512k"
+
+# Metaspace for web frameworks with many classes
+META="-XX:MaxMetaspaceSize=256m"
+
+# Production monitoring
+MONITOR="-Xlog:gc*:file=/var/log/app/gc.log:time,uptime:filecount=5,filesize=50m"
+MONITOR="$MONITOR -XX:+HeapDumpOnOutOfMemoryError"
+MONITOR="$MONITOR -XX:HeapDumpPath=/var/dumps/"
+
+# JFR for production profiling
+JFR="-XX:StartFlightRecording=disk=true,maxage=12h,maxsize=500m"
+JFR="$JFR -XX:FlightRecorderOptions=repository=/var/jfr/"
+
+java $HEAP $GC $CODE_CACHE $STACK $META $MONITOR $JFR \
+     -jar web-application.jar
+```
+
+**Rationale:**  
+- Fixed heap prevents resize pauses during traffic spikes  
+- G1GC provides predictable pause times  
+- Generous Metaspace for framework class loading  
+- Continuous JFR for diagnosing production issues  
+
+### Microservice Configuration  
+
+Microservices need fast startup, small footprint, and container awareness.  
+
+```bash
+#!/bin/bash
+# Microservice JVM Configuration
+# Characteristics: Small heap, fast startup, container deployment
+
+# Smaller heap for microservice (adjust based on service)
+HEAP="-Xms512m -Xmx512m"
+
+# ZGC for consistent low latency (or G1 for smaller heaps)
+GC="-XX:+UseZGC"
+
+# Enable container support (default in modern JVMs)
+CONTAINER="-XX:+UseContainerSupport"
+CONTAINER="$CONTAINER -XX:MaxRAMPercentage=75.0"
+
+# Optimize for startup time
+STARTUP="-XX:TieredStopAtLevel=1"
+STARTUP="$STARTUP -XX:+UseSerialGC"  # Use for very small services
+
+# Alternative: CDS for faster startup
+# Generate: java -Xshare:dump
+CDS="-Xshare:on"
+
+# Minimal monitoring in container (use sidecar for full logging)
+MONITOR="-Xlog:gc:stderr:time"
+MONITOR="$MONITOR -XX:+HeapDumpOnOutOfMemoryError"
+MONITOR="$MONITOR -XX:HeapDumpPath=/tmp/"
+
+# For production microservice with moderate load
+java $HEAP $GC $CONTAINER $MONITOR \
+     -jar microservice.jar
+
+# For startup-optimized (dev/test)
+# java $HEAP $STARTUP $CDS $MONITOR -jar microservice.jar
+```
+
+**Rationale:**  
+- Container awareness respects cgroup limits  
+- MaxRAMPercentage for automatic sizing in containers  
+- ZGC provides low latency without tuning  
+- Startup options available for faster cold starts  
+
+### High-Throughput Batch Job Configuration  
+
+Batch jobs prioritize throughput over latency, processing maximum data per  
+unit time.  
+
+```bash
+#!/bin/bash
+# Batch Processing JVM Configuration
+# Characteristics: Large heap, throughput priority, long-running
+
+# Large heap for batch data processing
+HEAP="-Xms16g -Xmx16g"
+
+# Parallel GC maximizes throughput
+GC="-XX:+UseParallelGC"
+GC="$GC -XX:ParallelGCThreads=12"
+GC="$GC -XX:+UseNUMA"
+
+# Alternative: G1 if pauses become too long
+# GC="-XX:+UseG1GC -XX:MaxGCPauseMillis=500"
+
+# Large young generation for allocation-heavy workloads
+YOUNG="-XX:NewRatio=2"
+
+# Aggressive inlining for hot paths
+JIT="-XX:MaxInlineSize=100"
+JIT="$JIT -XX:FreqInlineSize=200"
+
+# Monitoring for batch analysis
+MONITOR="-Xlog:gc*:file=/var/log/batch/gc.log:time,uptime"
+MONITOR="$MONITOR -XX:+HeapDumpOnOutOfMemoryError"
+
+# JFR for post-run analysis
+JFR="-XX:StartFlightRecording=settings=profile,dumponexit=true"
+JFR="$JFR -XX:FlightRecorderOptions=repository=/var/jfr/"
+
+java $HEAP $GC $YOUNG $JIT $MONITOR $JFR \
+     -jar batch-processor.jar
+```
+
+**Rationale:**  
+- Parallel GC provides highest throughput  
+- Large heap accommodates batch data sets  
+- NUMA support for multi-socket systems  
+- Aggressive JIT settings for long-running hot paths  
+
+### Configuration Summary Table  
+
+| Scenario           | Heap    | GC           | Key Priorities            |
+|--------------------|---------|--------------|---------------------------|
+| Web Application    | 4-8GB   | G1GC         | Low latency, consistent   |
+| Microservice       | 256M-1GB| ZGC/G1GC     | Fast startup, small footprint |
+| Batch Processing   | 8-32GB  | Parallel GC  | Throughput, large dataset |
+| Low-Latency Trading| 4-16GB  | ZGC          | Sub-ms pauses             |
+| Desktop/GUI        | 256M-2GB| G1GC         | Responsive, modest heap   |
+
+### Complete Example Application  
+
+```java
+import java.lang.management.GarbageCollectorMXBean;
+import java.lang.management.ManagementFactory;
+import java.lang.management.MemoryMXBean;
+
+void main() {
+
+    println("=== JVM Configuration Analysis ===");
+    println();
+
+    // Runtime info
+    var runtime = Runtime.getRuntime();
+    println("Available Processors: " + runtime.availableProcessors());
+    println();
+
+    // Memory configuration
+    println("Memory Configuration:");
+    println("  Max Memory (-Xmx):     " + formatBytes(runtime.maxMemory()));
+    println("  Total Memory (current):" + formatBytes(runtime.totalMemory()));
+    println("  Free Memory:           " + formatBytes(runtime.freeMemory()));
+    println("  Used Memory:           " + 
+            formatBytes(runtime.totalMemory() - runtime.freeMemory()));
+    println();
+
+    // Garbage collector info
+    println("Garbage Collectors:");
+    for (GarbageCollectorMXBean gc : ManagementFactory.getGarbageCollectorMXBeans()) {
+        println("  " + gc.getName());
+        println("    Collection Count: " + gc.getCollectionCount());
+        println("    Collection Time:  " + gc.getCollectionTime() + "ms");
+    }
+    println();
+
+    // Memory pools
+    MemoryMXBean memory = ManagementFactory.getMemoryMXBean();
+    println("Heap Memory Usage:");
+    var heapUsage = memory.getHeapMemoryUsage();
+    println("  Init:      " + formatBytes(heapUsage.getInit()));
+    println("  Used:      " + formatBytes(heapUsage.getUsed()));
+    println("  Committed: " + formatBytes(heapUsage.getCommitted()));
+    println("  Max:       " + formatBytes(heapUsage.getMax()));
+    println();
+
+    println("Non-Heap Memory Usage:");
+    var nonHeapUsage = memory.getNonHeapMemoryUsage();
+    println("  Init:      " + formatBytes(nonHeapUsage.getInit()));
+    println("  Used:      " + formatBytes(nonHeapUsage.getUsed()));
+    println("  Committed: " + formatBytes(nonHeapUsage.getCommitted()));
+    println();
+
+    // JVM arguments
+    println("JVM Arguments:");
+    var runtimeMXBean = ManagementFactory.getRuntimeMXBean();
+    for (String arg : runtimeMXBean.getInputArguments()) {
+        println("  " + arg);
+    }
+}
+
+String formatBytes(long bytes) {
+    if (bytes < 0) return "N/A";
+    if (bytes < 1024) return bytes + " B";
+    if (bytes < 1024 * 1024) return (bytes / 1024) + " KB";
+    if (bytes < 1024 * 1024 * 1024) return (bytes / (1024 * 1024)) + " MB";
+    return String.format("%.2f GB", bytes / (1024.0 * 1024 * 1024));
+}
+```
+
+This utility displays current JVM configuration. Run it with different flags  
+to verify settings are applied correctly.  
+
+## Conclusion  
+
+JVM tuning and profiling are essential skills for building high-performance  
+Java applications. Effective performance engineering requires a disciplined,  
+data-driven approach rather than ad-hoc flag adjustments.  
+
+### Key Takeaways  
+
+| Principle                   | Guidance                                     |
+|-----------------------------|----------------------------------------------|
+| Measure First               | Always profile before tuning                 |
+| Start Simple                | Use JVM defaults until proven insufficient   |
+| Make One Change at a Time   | Isolate variables to understand impact       |
+| Validate Improvements       | Confirm changes achieve desired outcomes     |
+| Test Realistically          | Use production-like conditions               |
+| Document Decisions          | Record rationale for future reference        |
+| Monitor Continuously        | Track metrics to detect regressions          |
+
+### Balancing Performance, Stability, and Maintainability  
+
+The goal of tuning is not maximum performance at any cost. Instead, aim for  
+the optimal balance:  
+
+**Performance**: Meet response time and throughput requirements with  
+appropriate resource utilization. Avoid over-optimization that yields  
+diminishing returns.  
+
+**Stability**: Ensure consistent behavior under varying loads. A well-tuned  
+application handles traffic spikes gracefully without crashes or severe  
+degradation.  
+
+**Maintainability**: Keep configurations understandable and documented. Complex  
+tuning that nobody understands becomes a liability during incidents.  
+
+### Continued Learning  
+
+JVM performance engineering evolves with each Java release. Stay current by:  
+- Reading JVM release notes for new GC features and deprecations  
+- Following OpenJDK mailing lists and JEPs  
+- Experimenting with new collectors (ZGC, Shenandoah) as they mature  
+- Practicing with profiling tools on sample applications  
+- Reviewing production metrics to understand real-world behavior  
+
+With the foundation provided in this document and continued practice, you can  
+effectively diagnose performance issues, apply targeted improvements, and  
+build Java applications that meet demanding performance requirements.  
diff --git a/lambda/QuitButtonEx.java b/lambda/QuitButtonEx.java
index 95bdf8ed..d9ce7f8c 100644
--- a/lambda/QuitButtonEx.java
+++ b/lambda/QuitButtonEx.java
@@ -17,7 +17,7 @@ private void initUI() {
 
         var quitButton = new JButton("Quit");
 
-        quitButton.addActionListener(e -> System.exit(0));
+        quitButton.addActionListener(_ -> System.exit(0));
 
         createLayout(quitButton);
 
diff --git a/lambda/lambda.md b/lambda/lambda.md
new file mode 100644
index 00000000..d159fda3
--- /dev/null
+++ b/lambda/lambda.md
@@ -0,0 +1,70 @@
+# Lambda
+
+
+## throw IOException
+
+```
+import java.io.IOException;
+import java.nio.file.FileStore;
+import java.nio.file.FileSystem;
+import java.nio.file.FileSystems;
+import java.util.function.Consumer;
+
+@FunctionalInterface
+public interface ThrowingConsumer<T> extends Consumer<T> {
+
+    @Override
+    default void accept(final T elem) {
+        try {
+            acceptThrows(elem);
+        } catch (final Exception e) {
+            // Implement your own exception handling logic here..
+            // For example:
+//            System.out.println("handling an exception...");
+            // Or ...
+            throw new RuntimeException(e);
+        }
+    }
+
+    void acceptThrows(T elem) throws Exception;
+
+}
+
+void main(String[] args) throws IOException {
+
+    FileSystem fileSystem = FileSystems.getDefault();
+
+    System.out.printf("%30s | %10s | %23s | %20s \n", "", "Type", "Total space", "Free space");
+    System.out.println("-------------------------------------------------"
+            + "----------------------------------------------------------");
+
+    Iterable<FileStore> fileStores = fileSystem.getFileStores();
+
+//    for (var fileStore : fileStores) {
+//        System.out.printf("%30s | %10s | %20s GB | %20s GB\n", fileStore, fileStore.type(),
+//                (fileStore.getTotalSpace() / 1073741824f),
+//                (fileStore.getUsableSpace() / 1073741824f));
+//    }
+
+    fileStores.forEach((ThrowingConsumer<FileStore>) fileStore -> {
+
+            System.out.printf("%30s | %10s | %20s GB | %20s GB\n", fileStore, fileStore.type(),
+                    (fileStore.getTotalSpace() / 1073741824f),
+                    (fileStore.getUsableSpace() / 1073741824f));
+        });
+}
+
+
+
+
+//class MyConsumer implements Consumer<FileStore>
+//{
+//
+//    @Override
+//    public void accept(FileStore fileStore) throws IOException {
+//        System.out.printf("%30s | %10s | %20s GB | %20s GB\n", fileStore, fileStore.type(),
+//                (fileStore.getTotalSpace() / 1073741824f),
+//                (fileStore.getUsableSpace() / 1073741824f));
+//    }
+//}
+```
diff --git a/maven.md b/maven.md
new file mode 100644
index 00000000..ae5af542
--- /dev/null
+++ b/maven.md
@@ -0,0 +1,61 @@
+# Maven
+
+
+## Executable JARS
+
+Using shaded plugin
+
+```xml
+<plugin>
+    <groupId>org.apache.maven.plugins</groupId>
+    <artifactId>maven-shade-plugin</artifactId>
+    <version>3.5.1</version>
+    <executions>
+        <execution>
+            <phase>package</phase>
+            <goals>
+                <goal>shade</goal>
+            </goals>
+            <configuration>
+                <transformers>
+                    <transformer
+                        implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
+                        <manifestEntries>
+                            <Main-Class>com.zetcode.Main</Main-Class>
+                        </manifestEntries>
+                    </transformer>
+                </transformers>
+            </configuration>
+        </execution>
+    </executions>
+</plugin>
+```
+
+Using assembly plugin
+
+```xml
+<plugin>
+    <groupId>org.apache.maven.plugins</groupId>
+    <artifactId>maven-assembly-plugin</artifactId>
+    <version>3.4.0</version>
+    <configuration>
+        <descriptorRefs>
+            <descriptorRef>jar-with-dependencies</descriptorRef>
+        </descriptorRefs>
+        <archive>
+            <manifest>
+                <mainClass>com.zetcode.Main</mainClass>
+            </manifest>
+        </archive>
+    </configuration>
+    <executions>
+        <execution>
+            <id>make-assembly</id>
+            <phase>package</phase>
+            <goals>
+                <goal>single</goal>
+            </goals>
+        </execution>
+    </executions>
+</plugin>
+```
diff --git a/memory-model.md b/memory-model.md
new file mode 100644
index 00000000..7f56ba48
--- /dev/null
+++ b/memory-model.md
@@ -0,0 +1,1866 @@
+# Java Memory Model
+
+The **Java Memory Model (JMM)** defines how threads interact through memory and  
+specifies the rules that govern when changes made by one thread become visible  
+to other threads. It is a fundamental part of the Java Language Specification  
+that provides the formal semantics of concurrent programming in Java.  
+
+Understanding the JMM is critical for writing correct multithreaded programs.  
+Without proper understanding, developers may write code that appears correct  
+but fails unpredictably due to subtle concurrency issues like race conditions,  
+stale data reads, or instruction reordering. The JMM establishes a contract  
+between the programmer and the JVM, defining what guarantees the JVM provides  
+and what responsibilities the programmer must fulfill.  
+
+The JMM addresses three fundamental challenges in concurrent programming:  
+
+- **Visibility**: Ensuring that changes made by one thread are visible to  
+  other threads when needed  
+- **Atomicity**: Guaranteeing that certain operations complete as indivisible  
+  units without interference from other threads  
+- **Ordering**: Defining the order in which operations appear to execute from  
+  the perspective of different threads  
+
+The JMM is defined in terms of **happens-before** relationships, which provide  
+a formal framework for reasoning about memory visibility and operation ordering.  
+These rules allow developers to write portable concurrent code that behaves  
+consistently across different hardware platforms and JVM implementations.  
+
+## Core Concepts  
+
+The Java Memory Model abstracts the complex realities of modern computer  
+architectures into a simplified model that developers can reason about. Modern  
+CPUs use multiple levels of caching, out-of-order execution, and various  
+optimizations that can cause operations to appear in different orders than  
+specified in the source code.  
+
+### Main Memory and Working Memory  
+
+In the JMM, there is a conceptual distinction between **main memory** and  
+**working memory**:  
+
+| Memory Type     | Description                                              |
+|-----------------|----------------------------------------------------------|
+| Main Memory     | Shared memory where all variables are stored             |
+| Working Memory  | Per-thread cache of variables (CPU caches/registers)     |
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                              Main Memory                                │
+│   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐   │
+│   │  Variable A │  │  Variable B │  │  Variable C │  │  Variable D │   │
+│   └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘   │
+└─────────────────────────────────────────────────────────────────────────┘
+         ▲                  ▲                  ▲                  ▲
+         │ load/store       │ load/store       │ load/store       │
+         ▼                  ▼                  ▼                  ▼
+┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────────────┐
+│  Thread 1       │  │  Thread 2       │  │  Thread 3                   │
+│  Working Memory │  │  Working Memory │  │  Working Memory             │
+│  ┌───────────┐  │  │  ┌───────────┐  │  │  ┌───────────┐ ┌─────────┐  │
+│  │ Copy of A │  │  │  │ Copy of B │  │  │  │ Copy of C │ │ Copy of │  │
+│  │ Copy of B │  │  │  │ Copy of C │  │  │  │ Copy of D │ │    A    │  │
+│  └───────────┘  │  │  └───────────┘  │  │  └───────────┘ └─────────┘  │
+└─────────────────┘  └─────────────────┘  └─────────────────────────────┘
+```
+
+Each thread has its own working memory, which is an abstract concept  
+representing CPU caches, registers, and compiler optimizations. When a thread  
+reads a variable, it may read from its working memory rather than main memory.  
+When a thread writes a variable, the change may remain in working memory  
+temporarily before being flushed to main memory.  
+
+### Visibility  
+
+**Visibility** refers to when changes made by one thread become visible to  
+other threads. Without proper synchronization, there is no guarantee that a  
+thread will ever see changes made by another thread.  
+
+```java
+class VisibilityProblem {
+    boolean running = true;
+    int counter = 0;
+}
+
+void main() throws InterruptedException {
+
+    var shared = new VisibilityProblem();
+
+    var worker = new Thread(() -> {
+        while (shared.running) {
+            shared.counter++;
+        }
+        println("Worker stopped, counter = " + shared.counter);
+    });
+
+    worker.start();
+    Thread.sleep(100);
+    shared.running = false;
+    println("Main thread set running to false");
+
+    worker.join(2000);
+    if (worker.isAlive()) {
+        println("Worker thread did not see the change!");
+        worker.interrupt();
+    }
+}
+```
+
+In this example, the worker thread may never see the change to `running`  
+because it might cache the value in its working memory. The JMM does not  
+require the thread to ever refresh its cached value without explicit  
+synchronization.  
+
+### Atomicity  
+
+**Atomicity** ensures that an operation completes as an indivisible unit.  
+Simple reads and writes of most primitive types are atomic, but compound  
+operations like `counter++` are not.  
+
+| Operation Type                | Atomic?                                     |
+|-------------------------------|---------------------------------------------|
+| Read/write of reference       | Yes                                         |
+| Read/write of most primitives | Yes                                         |
+| Read/write of long/double     | Not guaranteed (may require volatile)       |
+| Increment (`i++`)             | No (read-modify-write)                      |
+| Compare-and-set               | Yes (when using atomic classes)             |
+
+```java
+void main() throws InterruptedException {
+
+    var counter = new int[]{0};
+    var threads = new ArrayList<Thread>();
+
+    for (int i = 0; i < 10; i++) {
+        var thread = new Thread(() -> {
+            for (int j = 0; j < 1000; j++) {
+                counter[0]++;  // NOT atomic: read, increment, write
+            }
+        });
+        threads.add(thread);
+        thread.start();
+    }
+
+    for (var thread : threads) {
+        thread.join();
+    }
+
+    println("Expected: 10000, Actual: " + counter[0]);
+}
+```
+
+The increment operation `counter[0]++` consists of three separate steps:  
+read the current value, add one, and write the new value. Multiple threads  
+can interleave these steps, causing lost updates and an incorrect final count.  
+
+### Ordering  
+
+**Ordering** defines the sequence in which operations appear to execute.  
+Without synchronization, the compiler, JVM, and CPU are free to reorder  
+operations for performance, as long as the reordering is not observable by  
+a single thread.  
+
+```java
+class ReorderingExample {
+    int x = 0;
+    int y = 0;
+    int a = 0;
+    int b = 0;
+}
+
+void main() throws InterruptedException {
+
+    for (int iteration = 0; iteration < 100000; iteration++) {
+
+        var shared = new ReorderingExample();
+
+        var thread1 = new Thread(() -> {
+            shared.x = 1;
+            shared.a = shared.y;
+        });
+
+        var thread2 = new Thread(() -> {
+            shared.y = 1;
+            shared.b = shared.x;
+        });
+
+        thread1.start();
+        thread2.start();
+        thread1.join();
+        thread2.join();
+
+        if (shared.a == 0 && shared.b == 0) {
+            println("Reordering detected at iteration " + iteration);
+            println("a = " + shared.a + ", b = " + shared.b);
+            break;
+        }
+    }
+}
+```
+
+This example may detect reordering where both `a` and `b` are zero, which  
+would be impossible under sequential consistency. This happens because the  
+CPU or compiler may reorder the write and read operations within each thread.  
+
+### Sequential Consistency vs Real JVM Execution  
+
+**Sequential consistency** is a theoretical model where all operations appear  
+to execute in some total order that respects the program order of each thread.  
+The JMM does NOT guarantee sequential consistency for unsynchronized programs.  
+
+| Model                  | Description                                      |
+|------------------------|--------------------------------------------------|
+| Sequential Consistency | All operations appear in a single total order    |
+| JMM (unsynchronized)   | Allows reorderings and visibility delays         |
+| JMM (synchronized)     | Provides happens-before guarantees               |
+
+The JMM provides sequential consistency only when programs are properly  
+synchronized using mechanisms like `synchronized`, `volatile`, or atomic  
+operations. This relaxed model allows JVMs and CPUs to apply optimizations  
+that would be impossible under strict sequential consistency.  
+
+## Happens-Before Relationship  
+
+The **happens-before** relationship is the cornerstone of the Java Memory  
+Model. It defines when the results of one operation are guaranteed to be  
+visible to another operation. If operation A happens-before operation B,  
+then the memory effects of A are visible to B.  
+
+### Happens-Before Rules  
+
+The JMM defines several rules that establish happens-before relationships:  
+
+| Rule                    | Description                                        |
+|-------------------------|----------------------------------------------------|
+| Program Order           | Each action in a thread happens-before every       |
+|                         | subsequent action in that same thread              |
+| Monitor Lock            | An unlock on a monitor happens-before every        |
+|                         | subsequent lock on that same monitor               |
+| Volatile Variable       | A write to a volatile field happens-before every   |
+|                         | subsequent read of that same volatile field        |
+| Thread Start            | A call to `start` on a thread happens-before any   |
+|                         | action in the started thread                       |
+| Thread Join             | All actions in a thread happen-before another      |
+|                         | thread successfully returns from `join`            |
+| Thread Interruption     | A call to `interrupt` happens-before the           |
+|                         | interrupted thread detects the interruption        |
+| Object Finalization     | The end of a constructor happens-before the        |
+|                         | start of the finalizer for that object             |
+| Transitivity            | If A happens-before B and B happens-before C,      |
+|                         | then A happens-before C                            |
+
+### Program Order Rule  
+
+Within a single thread, all operations happen-before subsequent operations  
+according to the program text. This is the most basic happens-before rule.  
+
+```java
+void main() {
+
+    int x = 0;      // (1)
+    x = 5;          // (2) - happens-before (3)
+    int y = x + 1;  // (3) - sees x = 5
+
+    println("x = " + x + ", y = " + y);
+}
+```
+
+Operation (2) happens-before operation (3) due to program order, so (3)  
+is guaranteed to see the value written by (2). This is intuitive within  
+a single thread but becomes crucial when understanding cross-thread visibility.  
+
+### Monitor Lock Rule  
+
+The release of a lock (unlock) happens-before every subsequent acquisition  
+of that same lock. This ensures visibility of changes made while holding  
+the lock.  
+
+```java
+class MonitorExample {
+    int sharedData = 0;
+}
+
+void main() throws InterruptedException {
+
+    var shared = new MonitorExample();
+    var lock = new Object();
+
+    var writer = new Thread(() -> {
+        synchronized (lock) {
+            shared.sharedData = 42;  // (1)
+        }                            // (2) unlock
+    });
+
+    var reader = new Thread(() -> {
+        try { Thread.sleep(50); } catch (InterruptedException e) {}
+        synchronized (lock) {        // (3) lock - happens-after (2)
+            println("Read: " + shared.sharedData);  // sees 42
+        }
+    });
+
+    writer.start();
+    reader.start();
+    writer.join();
+    reader.join();
+}
+```
+
+The unlock at (2) happens-before the lock at (3). By transitivity, write  
+(1) happens-before the read in the reader thread. This guarantees that the  
+reader sees the value 42 written by the writer.  
+
+### Volatile Variable Rule  
+
+A write to a volatile variable happens-before every subsequent read of that  
+variable. This provides visibility guarantees without mutual exclusion.  
+
+```java
+class VolatileExample {
+    volatile boolean ready = false;
+    int data = 0;
+}
+
+void main() throws InterruptedException {
+
+    var shared = new VolatileExample();
+
+    var writer = new Thread(() -> {
+        shared.data = 42;         // (1)
+        shared.ready = true;      // (2) volatile write
+    });
+
+    var reader = new Thread(() -> {
+        while (!shared.ready) {}  // (3) volatile read - happens-after (2)
+        println("Data: " + shared.data);  // (4) sees 42
+    });
+
+    writer.start();
+    reader.start();
+    writer.join();
+    reader.join();
+}
+```
+
+The volatile write at (2) happens-before the volatile read at (3). Due to  
+program order, (1) happens-before (2). By transitivity, (1) happens-before  
+(4), ensuring the reader sees `data = 42`.  
+
+### Thread Start Rule  
+
+A call to `Thread.start` happens-before any action in the started thread.  
+This ensures that the new thread sees all changes made before the start call.  
+
+```java
+void main() throws InterruptedException {
+
+    var data = new int[]{0};
+
+    data[0] = 100;  // (1)
+
+    var thread = new Thread(() -> {
+        // (3) sees data[0] = 100
+        println("Thread sees: " + data[0]);
+    });
+
+    thread.start();  // (2) - all changes before this are visible to thread
+    thread.join();
+}
+```
+
+The assignment at (1) happens-before the start call at (2), which  
+happens-before all actions in the new thread. The new thread is guaranteed  
+to see `data[0] = 100`.  
+
+### Thread Join Rule  
+
+All actions in a thread happen-before the successful return from `join`  
+on that thread. This ensures that results computed by a thread are visible  
+after joining.  
+
+```java
+void main() throws InterruptedException {
+
+    var result = new int[]{0};
+
+    var worker = new Thread(() -> {
+        result[0] = computeValue();  // (1)
+    });                              // (2) thread terminates
+
+    worker.start();
+    worker.join();  // (3) - happens-after (2)
+
+    // (4) sees result[0] from worker
+    println("Result: " + result[0]);
+}
+
+int computeValue() {
+    int sum = 0;
+    for (int i = 1; i <= 100; i++) {
+        sum += i;
+    }
+    return sum;
+}
+```
+
+All actions in the worker thread, including (1), happen-before the join  
+returns at (3). This guarantees that the main thread sees the result  
+computed by the worker.  
+
+### Happens-Before Diagram  
+
+```
+Thread 1                          Thread 2
+─────────                         ─────────
+   │                                  │
+   ▼                                  │
+[x = 1]                               │
+   │                                  │
+   │ program order                    │
+   ▼                                  │
+[volatile write: ready = true] ─────────────────► [volatile read: ready]
+                               happens-before      │
+                                                   │ program order
+                                                   ▼
+                                                [read x]
+                                                (sees x = 1)
+```
+
+This diagram illustrates how happens-before relationships chain together  
+across threads through a volatile variable, ensuring that Thread 2 sees  
+the write to `x` performed by Thread 1.  
+
+## Volatile Variables  
+
+The `volatile` keyword in Java provides two key guarantees:  
+
+1. **Visibility**: Changes to a volatile variable are immediately visible  
+   to all threads  
+2. **Ordering**: Volatile reads and writes cannot be reordered with other  
+   memory operations  
+
+### How Volatile Works  
+
+When a thread writes to a volatile variable, the JMM requires that all  
+variables visible to that thread are flushed from working memory to main  
+memory. When a thread reads a volatile variable, it refreshes all cached  
+variables from main memory.  
+
+```
+Before volatile write:           After volatile write:
+┌──────────────────────┐         ┌──────────────────────┐
+│   Working Memory     │         │   Main Memory        │
+│   ┌────────────────┐ │         │   ┌────────────────┐ │
+│   │ x = 5          │─┼────────►│   │ x = 5          │ │
+│   │ y = 10         │─┼────────►│   │ y = 10         │ │
+│   │ ready = true   │─┼────────►│   │ ready = true   │ │
+│   └────────────────┘ │ flush   │   └────────────────┘ │
+└──────────────────────┘         └──────────────────────┘
+```
+
+### Correct Usage of Volatile  
+
+Volatile is suitable for flags and status indicators where only one thread  
+writes and multiple threads read, or when the written value does not depend  
+on the current value.  
+
+```java
+class GracefulShutdown {
+    volatile boolean shutdownRequested = false;
+}
+
+void main() throws InterruptedException {
+
+    var controller = new GracefulShutdown();
+
+    var workers = new ArrayList<Thread>();
+    for (int i = 0; i < 3; i++) {
+        int workerId = i;
+        var worker = new Thread(() -> {
+            int count = 0;
+            while (!controller.shutdownRequested) {
+                count++;
+                // Simulate work
+                try { Thread.sleep(10); } catch (InterruptedException e) {
+                    break;
+                }
+            }
+            println("Worker " + workerId + " processed " + count + " items");
+        });
+        workers.add(worker);
+        worker.start();
+    }
+
+    Thread.sleep(500);
+    controller.shutdownRequested = true;  // All workers will see this
+    println("Shutdown requested");
+
+    for (var worker : workers) {
+        worker.join();
+    }
+    println("All workers stopped");
+}
+```
+
+The volatile `shutdownRequested` flag ensures that all worker threads see  
+the shutdown signal promptly. Without volatile, workers might cache the  
+value and never observe the change.  
+
+### Volatile for Publication  
+
+Volatile can be used to safely publish immutable objects to other threads.  
+
+```java
+record Configuration(String host, int port, boolean secure) {}
+
+class ConfigHolder {
+    volatile Configuration config;
+}
+
+void main() throws InterruptedException {
+
+    var holder = new ConfigHolder();
+
+    var publisher = new Thread(() -> {
+        // Create and publish configuration
+        holder.config = new Configuration("localhost", 8080, true);
+        println("Configuration published");
+    });
+
+    var consumer = new Thread(() -> {
+        Configuration cfg = null;
+        while ((cfg = holder.config) == null) {
+            Thread.onSpinWait();
+        }
+        println("Received: " + cfg.host() + ":" + cfg.port());
+    });
+
+    consumer.start();
+    Thread.sleep(100);
+    publisher.start();
+
+    publisher.join();
+    consumer.join();
+}
+```
+
+The volatile reference ensures that when the consumer reads a non-null  
+config, it sees the fully constructed Configuration object with all  
+fields properly initialized.  
+
+### Common Pitfalls with Volatile  
+
+Volatile does NOT provide atomicity for compound operations like increment.  
+
+```java
+class VolatileCounter {
+    volatile int count = 0;
+}
+
+void main() throws InterruptedException {
+
+    var counter = new VolatileCounter();
+    var threads = new ArrayList<Thread>();
+
+    for (int i = 0; i < 10; i++) {
+        var thread = new Thread(() -> {
+            for (int j = 0; j < 1000; j++) {
+                counter.count++;  // NOT atomic even with volatile!
+            }
+        });
+        threads.add(thread);
+        thread.start();
+    }
+
+    for (var thread : threads) {
+        thread.join();
+    }
+
+    println("Expected: 10000, Actual: " + counter.count);
+    println("Volatile does not make ++ atomic!");
+}
+```
+
+Even though `count` is volatile, the increment operation is still a  
+read-modify-write sequence that can be interleaved by other threads.  
+Use `AtomicInteger` or `synchronized` for atomic compound operations.  
+
+### When to Use Volatile  
+
+| Use Case                          | Suitable?                           |
+|-----------------------------------|-------------------------------------|
+| Single writer, multiple readers   | Yes                                 |
+| Status flags (running, shutdown)  | Yes                                 |
+| Publishing immutable objects      | Yes                                 |
+| Counters with increment           | No, use AtomicInteger               |
+| Check-then-act patterns           | No, use synchronized                |
+| Multiple writers                  | Usually no, use synchronized        |
+
+## Synchronization  
+
+The `synchronized` keyword provides both mutual exclusion and memory  
+visibility guarantees. It is the most fundamental synchronization primitive  
+in Java.  
+
+### Synchronized Methods  
+
+When a method is declared `synchronized`, only one thread can execute that  
+method on a particular object instance at a time.  
+
+```java
+class BankAccount {
+    private int balance;
+
+    BankAccount(int initialBalance) {
+        this.balance = initialBalance;
+    }
+
+    synchronized void deposit(int amount) {
+        balance += amount;
+    }
+
+    synchronized void withdraw(int amount) {
+        if (balance >= amount) {
+            balance -= amount;
+        }
+    }
+
+    synchronized int getBalance() {
+        return balance;
+    }
+}
+
+void main() throws InterruptedException {
+
+    var account = new BankAccount(1000);
+    var threads = new ArrayList<Thread>();
+
+    // Multiple depositors
+    for (int i = 0; i < 5; i++) {
+        var thread = new Thread(() -> {
+            for (int j = 0; j < 100; j++) {
+                account.deposit(10);
+            }
+        });
+        threads.add(thread);
+        thread.start();
+    }
+
+    // Multiple withdrawers
+    for (int i = 0; i < 5; i++) {
+        var thread = new Thread(() -> {
+            for (int j = 0; j < 100; j++) {
+                account.withdraw(5);
+            }
+        });
+        threads.add(thread);
+        thread.start();
+    }
+
+    for (var thread : threads) {
+        thread.join();
+    }
+
+    println("Final balance: " + account.getBalance());
+    println("Expected: 1000 + (5*100*10) - (5*100*5) = 3500");
+}
+```
+
+The `synchronized` keyword ensures that only one thread can execute any  
+synchronized method on the same BankAccount instance at a time. This  
+prevents race conditions where simultaneous deposits and withdrawals  
+could corrupt the balance.  
+
+### Synchronized Blocks  
+
+Synchronized blocks provide more fine-grained control over locking by  
+allowing you to specify the lock object and limit the scope of locking.  
+
+```java
+class TransferService {
+    void transfer(BankAccount from, BankAccount to, int amount) {
+        // Lock ordering to prevent deadlock
+        Object firstLock = System.identityHashCode(from) < 
+                           System.identityHashCode(to) ? from : to;
+        Object secondLock = firstLock == from ? to : from;
+
+        synchronized (firstLock) {
+            synchronized (secondLock) {
+                if (from.getBalance() >= amount) {
+                    from.withdraw(amount);
+                    to.deposit(amount);
+                }
+            }
+        }
+    }
+}
+
+class BankAccount {
+    private int balance;
+
+    BankAccount(int initialBalance) {
+        this.balance = initialBalance;
+    }
+
+    synchronized void deposit(int amount) {
+        balance += amount;
+    }
+
+    synchronized void withdraw(int amount) {
+        balance -= amount;
+    }
+
+    synchronized int getBalance() {
+        return balance;
+    }
+}
+
+void main() throws InterruptedException {
+
+    var account1 = new BankAccount(1000);
+    var account2 = new BankAccount(1000);
+    var service = new TransferService();
+
+    var threads = new ArrayList<Thread>();
+
+    for (int i = 0; i < 100; i++) {
+        threads.add(new Thread(() -> service.transfer(account1, account2, 10)));
+        threads.add(new Thread(() -> service.transfer(account2, account1, 10)));
+    }
+
+    for (var thread : threads) {
+        thread.start();
+    }
+
+    for (var thread : threads) {
+        thread.join();
+    }
+
+    println("Account 1: " + account1.getBalance());
+    println("Account 2: " + account2.getBalance());
+    println("Total: " + (account1.getBalance() + account2.getBalance()));
+}
+```
+
+The transfer method uses a consistent lock ordering based on object  
+identity hash codes to prevent deadlock when multiple threads try to  
+transfer between the same accounts in different directions.  
+
+### ReentrantLock  
+
+`ReentrantLock` provides the same mutual exclusion as `synchronized` but  
+with additional features like tryLock, timed lock, and interruptible locking.  
+
+```java
+import java.util.concurrent.locks.ReentrantLock;
+import java.util.concurrent.TimeUnit;
+
+class ResourcePool {
+    private final ReentrantLock lock = new ReentrantLock();
+    private int available = 5;
+
+    boolean tryAcquire(long timeout) throws InterruptedException {
+        if (lock.tryLock(timeout, TimeUnit.MILLISECONDS)) {
+            try {
+                if (available > 0) {
+                    available--;
+                    return true;
+                }
+                return false;
+            } finally {
+                lock.unlock();
+            }
+        }
+        return false;
+    }
+
+    void release() {
+        lock.lock();
+        try {
+            available++;
+        } finally {
+            lock.unlock();
+        }
+    }
+
+    int getAvailable() {
+        lock.lock();
+        try {
+            return available;
+        } finally {
+            lock.unlock();
+        }
+    }
+}
+
+void main() throws InterruptedException {
+
+    var pool = new ResourcePool();
+    var threads = new ArrayList<Thread>();
+
+    for (int i = 0; i < 10; i++) {
+        int id = i;
+        var thread = new Thread(() -> {
+            try {
+                if (pool.tryAcquire(100)) {
+                    println("Thread " + id + " acquired resource");
+                    Thread.sleep(200);
+                    pool.release();
+                    println("Thread " + id + " released resource");
+                } else {
+                    println("Thread " + id + " timed out");
+                }
+            } catch (InterruptedException e) {
+                Thread.currentThread().interrupt();
+            }
+        });
+        threads.add(thread);
+        thread.start();
+    }
+
+    for (var thread : threads) {
+        thread.join();
+    }
+
+    println("Final available: " + pool.getAvailable());
+}
+```
+
+ReentrantLock's tryLock with timeout prevents threads from waiting  
+indefinitely, which is useful for avoiding deadlocks and implementing  
+responsive applications that can give up on acquiring a resource.  
+
+### Comparison: synchronized vs ReentrantLock  
+
+| Feature                   | synchronized        | ReentrantLock             |
+|---------------------------|---------------------|---------------------------|
+| Lock acquisition          | Implicit            | Explicit lock/unlock      |
+| Interruptible locking     | No                  | Yes (lockInterruptibly)   |
+| Timed locking             | No                  | Yes (tryLock with timeout)|
+| Non-blocking tryLock      | No                  | Yes                       |
+| Multiple conditions       | No                  | Yes (newCondition)        |
+| Fairness policy           | No                  | Yes (optional)            |
+| Must release in finally   | Automatic           | Yes, manual               |
+| Performance               | Slightly faster     | Slightly slower           |
+
+```java
+import java.util.concurrent.locks.ReentrantLock;
+import java.util.concurrent.locks.Condition;
+
+class BoundedBuffer {
+    private final String[] buffer;
+    private int count, putIndex, takeIndex;
+    private final ReentrantLock lock = new ReentrantLock();
+    private final Condition notFull = lock.newCondition();
+    private final Condition notEmpty = lock.newCondition();
+
+    BoundedBuffer(int capacity) {
+        buffer = new String[capacity];
+    }
+
+    void put(String item) throws InterruptedException {
+        lock.lock();
+        try {
+            while (count == buffer.length) {
+                notFull.await();
+            }
+            buffer[putIndex] = item;
+            putIndex = (putIndex + 1) % buffer.length;
+            count++;
+            notEmpty.signal();
+        } finally {
+            lock.unlock();
+        }
+    }
+
+    String take() throws InterruptedException {
+        lock.lock();
+        try {
+            while (count == 0) {
+                notEmpty.await();
+            }
+            String item = buffer[takeIndex];
+            takeIndex = (takeIndex + 1) % buffer.length;
+            count--;
+            notFull.signal();
+            return item;
+        } finally {
+            lock.unlock();
+        }
+    }
+}
+
+void main() throws InterruptedException {
+
+    var buffer = new BoundedBuffer(5);
+
+    var producer = new Thread(() -> {
+        try {
+            for (int i = 0; i < 10; i++) {
+                buffer.put("Item-" + i);
+                println("Produced: Item-" + i);
+            }
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+        }
+    });
+
+    var consumer = new Thread(() -> {
+        try {
+            for (int i = 0; i < 10; i++) {
+                Thread.sleep(200);
+                String item = buffer.take();
+                println("Consumed: " + item);
+            }
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+        }
+    });
+
+    producer.start();
+    consumer.start();
+    producer.join();
+    consumer.join();
+}
+```
+
+This bounded buffer example demonstrates using multiple Condition objects  
+with ReentrantLock. Separate conditions for "not full" and "not empty"  
+allow precise signaling, waking only the appropriate waiting threads.  
+
+## Atomic Operations  
+
+The `java.util.concurrent.atomic` package provides classes that support  
+lock-free, thread-safe operations on single variables. These classes use  
+Compare-And-Swap (CAS) instructions provided by modern CPUs.  
+
+### Compare-And-Swap (CAS)  
+
+CAS is an atomic instruction that compares the current value of a memory  
+location with an expected value and, only if they match, updates the  
+location to a new value.  
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                    Compare-And-Swap (CAS) Operation                     │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                         │
+│   CAS(memory_location, expected_value, new_value)                       │
+│                                                                         │
+│   1. Read current value at memory_location                              │
+│   2. Compare with expected_value                                        │
+│   3. If equal: write new_value (success)                                │
+│      If not equal: do nothing (failure)                                 │
+│   4. Return whether update was successful                               │
+│                                                                         │
+│   All steps happen atomically!                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### AtomicInteger  
+
+`AtomicInteger` provides atomic operations on int values without locking.  
+
+```java
+import java.util.concurrent.atomic.AtomicInteger;
+
+void main() throws InterruptedException {
+
+    var counter = new AtomicInteger(0);
+    var threads = new ArrayList<Thread>();
+
+    for (int i = 0; i < 10; i++) {
+        var thread = new Thread(() -> {
+            for (int j = 0; j < 1000; j++) {
+                counter.incrementAndGet();  // Atomic increment
+            }
+        });
+        threads.add(thread);
+        thread.start();
+    }
+
+    for (var thread : threads) {
+        thread.join();
+    }
+
+    println("Final count: " + counter.get());
+    println("Expected: 10000");
+}
+```
+
+The `incrementAndGet` method uses CAS internally. If the CAS fails because  
+another thread modified the value, it retries with the new current value  
+until success. This provides atomicity without blocking.  
+
+### Atomic Operations Methods  
+
+| Method                    | Description                                  |
+|---------------------------|----------------------------------------------|
+| `get()`                   | Returns the current value                    |
+| `set(value)`              | Sets to the given value                      |
+| `getAndSet(value)`        | Sets and returns the old value               |
+| `compareAndSet(exp, upd)` | Sets if current equals expected              |
+| `incrementAndGet()`       | Increments and returns new value             |
+| `getAndIncrement()`       | Returns current value, then increments       |
+| `decrementAndGet()`       | Decrements and returns new value             |
+| `addAndGet(delta)`        | Adds delta and returns new value             |
+| `getAndAdd(delta)`        | Returns current value, then adds delta       |
+| `updateAndGet(function)`  | Updates using function, returns new value    |
+| `accumulateAndGet(x, op)` | Applies operator with x, returns new value   |
+
+```java
+import java.util.concurrent.atomic.AtomicInteger;
+
+void main() {
+
+    var value = new AtomicInteger(10);
+
+    println("Initial: " + value.get());
+    println("getAndIncrement: " + value.getAndIncrement() + 
+            " -> now: " + value.get());
+    println("incrementAndGet: " + value.incrementAndGet());
+    println("addAndGet(5): " + value.addAndGet(5));
+    println("compareAndSet(17, 20): " + value.compareAndSet(17, 20) + 
+            " -> value: " + value.get());
+    println("updateAndGet(x -> x * 2): " + value.updateAndGet(x -> x * 2));
+    println("accumulateAndGet(3, (x,y) -> x+y): " + 
+            value.accumulateAndGet(3, (x, y) -> x + y));
+}
+```
+
+The `updateAndGet` and `accumulateAndGet` methods accept functions,  
+enabling complex atomic updates. The function may be called multiple  
+times if CAS fails, so it should be side-effect free.  
+
+### AtomicReference  
+
+`AtomicReference` provides atomic operations on object references.  
+
+```java
+import java.util.concurrent.atomic.AtomicReference;
+
+record ImmutablePoint(int x, int y) {}
+
+void main() throws InterruptedException {
+
+    var pointRef = new AtomicReference<>(new ImmutablePoint(0, 0));
+
+    var threads = new ArrayList<Thread>();
+    for (int i = 0; i < 10; i++) {
+        int delta = i;
+        var thread = new Thread(() -> {
+            for (int j = 0; j < 100; j++) {
+                pointRef.updateAndGet(p -> 
+                    new ImmutablePoint(p.x() + 1, p.y() + delta));
+            }
+        });
+        threads.add(thread);
+        thread.start();
+    }
+
+    for (var thread : threads) {
+        thread.join();
+    }
+
+    var finalPoint = pointRef.get();
+    println("Final point: (" + finalPoint.x() + ", " + finalPoint.y() + ")");
+    println("Expected x: 1000");
+}
+```
+
+AtomicReference is useful for atomically updating immutable objects or  
+implementing lock-free data structures. The `updateAndGet` method  
+atomically replaces the reference with a new value computed from the  
+current value.  
+
+### AtomicStampedReference  
+
+`AtomicStampedReference` solves the ABA problem by associating an integer  
+stamp with the reference.  
+
+```java
+import java.util.concurrent.atomic.AtomicStampedReference;
+
+void main() {
+
+    var ref = new AtomicStampedReference<>("A", 0);
+
+    println("Initial: " + ref.getReference() + ", stamp: " + ref.getStamp());
+
+    // Thread 1 reads value and stamp
+    String expected = ref.getReference();
+    int expectedStamp = ref.getStamp();
+
+    // Simulate ABA: another thread changes A -> B -> A
+    ref.compareAndSet("A", "B", 0, 1);
+    println("After A->B: " + ref.getReference() + ", stamp: " + ref.getStamp());
+
+    ref.compareAndSet("B", "A", 1, 2);
+    println("After B->A: " + ref.getReference() + ", stamp: " + ref.getStamp());
+
+    // Thread 1 tries to update - fails because stamp changed
+    boolean success = ref.compareAndSet(expected, "C", expectedStamp, 3);
+    println("Update with old stamp: " + success);
+
+    // Update with correct stamp succeeds
+    success = ref.compareAndSet("A", "C", 2, 3);
+    println("Update with correct stamp: " + success);
+    println("Final: " + ref.getReference() + ", stamp: " + ref.getStamp());
+}
+```
+
+The ABA problem occurs when a value changes from A to B and back to A,  
+making a simple CAS appear to succeed even though the value was modified.  
+The stamp tracks modifications, preventing this issue.  
+
+## Memory Reordering  
+
+Modern CPUs and compilers reorder instructions for performance. These  
+reorderings are invisible to single-threaded programs but can cause issues  
+in multithreaded code without proper synchronization.  
+
+### Types of Reordering  
+
+| Type               | Description                                        |
+|--------------------|----------------------------------------------------|
+| Compiler Reorder   | Compiler rearranges instructions for optimization  |
+| CPU Reorder        | CPU executes instructions out of program order     |
+| Store Buffer       | Writes are buffered before reaching main memory    |
+| Cache Coherence    | Different CPUs may see writes in different orders  |
+
+### Reordering Example  
+
+```java
+class ReorderDemo {
+    int a = 0;
+    int b = 0;
+    int x = 0;
+    int y = 0;
+}
+
+void main() throws InterruptedException {
+
+    int bothZero = 0;
+    int iterations = 1000000;
+
+    for (int i = 0; i < iterations; i++) {
+        var demo = new ReorderDemo();
+
+        var t1 = new Thread(() -> {
+            demo.a = 1;
+            demo.x = demo.b;
+        });
+
+        var t2 = new Thread(() -> {
+            demo.b = 1;
+            demo.y = demo.a;
+        });
+
+        t1.start();
+        t2.start();
+        t1.join();
+        t2.join();
+
+        if (demo.x == 0 && demo.y == 0) {
+            bothZero++;
+        }
+    }
+
+    println("Both zero occurred: " + bothZero + " times out of " + iterations);
+    if (bothZero > 0) {
+        println("Reordering detected! This proves memory reordering occurs.");
+    }
+}
+```
+
+Under sequential consistency, x=0 and y=0 simultaneously would be  
+impossible. If this result occurs, it proves that either the compiler  
+or CPU reordered the writes and reads within each thread.  
+
+### How JMM Prevents Unsafe Reorderings  
+
+The JMM uses **memory barriers** (also called fences) to prevent certain  
+reorderings. Synchronization operations insert these barriers:  
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                        Memory Barrier Types                             │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                         │
+│  LoadLoad Barrier:   Load1; LoadLoad; Load2                             │
+│                      Ensures Load1 completes before Load2               │
+│                                                                         │
+│  StoreStore Barrier: Store1; StoreStore; Store2                         │
+│                      Ensures Store1 is visible before Store2            │
+│                                                                         │
+│  LoadStore Barrier:  Load1; LoadStore; Store2                           │
+│                      Ensures Load1 completes before Store2              │
+│                                                                         │
+│  StoreLoad Barrier:  Store1; StoreLoad; Load2                           │
+│                      Ensures Store1 is visible before Load2             │
+│                      (Most expensive, provides full fence)              │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### Volatile and Memory Barriers  
+
+Volatile accesses insert memory barriers that prevent reordering:  
+
+| Operation          | Barriers                                          |
+|--------------------|---------------------------------------------------|
+| Volatile Read      | LoadLoad + LoadStore after the read              |
+| Volatile Write     | StoreStore before + StoreLoad after the write    |
+
+```java
+class VolatileBarrierDemo {
+    int a = 0;
+    int b = 0;
+    volatile boolean flag = false;
+}
+
+void main() throws InterruptedException {
+
+    var demo = new VolatileBarrierDemo();
+
+    var writer = new Thread(() -> {
+        demo.a = 1;                    // (1)
+        demo.b = 2;                    // (2)
+        // StoreStore barrier here
+        demo.flag = true;              // (3) volatile write
+        // StoreLoad barrier here
+    });
+
+    var reader = new Thread(() -> {
+        while (!demo.flag) {}          // (4) volatile read
+        // LoadLoad + LoadStore barrier here
+        println("a = " + demo.a);      // (5) guaranteed to see 1
+        println("b = " + demo.b);      // (6) guaranteed to see 2
+    });
+
+    writer.start();
+    reader.start();
+    writer.join();
+    reader.join();
+}
+```
+
+The StoreStore barrier before the volatile write ensures (1) and (2)  
+are visible before (3). The LoadLoad barrier after the volatile read  
+ensures (5) and (6) see the values written by the writer thread.  
+
+## Practical Examples  
+
+This section demonstrates common concurrency issues and how to solve them  
+using JMM principles.  
+
+### Race Condition  
+
+A race condition occurs when the correctness of a program depends on the  
+relative timing of threads.  
+
+```java
+class RaceConditionDemo {
+    int counter = 0;
+}
+
+void main() throws InterruptedException {
+
+    var demo = new RaceConditionDemo();
+
+    println("=== Without Synchronization (Race Condition) ===");
+
+    var threads1 = new ArrayList<Thread>();
+    for (int i = 0; i < 10; i++) {
+        var thread = new Thread(() -> {
+            for (int j = 0; j < 10000; j++) {
+                demo.counter++;
+            }
+        });
+        threads1.add(thread);
+        thread.start();
+    }
+
+    for (var thread : threads1) {
+        thread.join();
+    }
+
+    println("Expected: 100000, Actual: " + demo.counter);
+    println("Lost updates: " + (100000 - demo.counter));
+}
+```
+
+The increment operation reads, modifies, and writes the counter in three  
+steps. Multiple threads can interleave these steps, causing some increments  
+to be lost.  
+
+### Fixing Race Condition with Synchronization  
+
+```java
+class SynchronizedCounter {
+    private int counter = 0;
+
+    synchronized void increment() {
+        counter++;
+    }
+
+    synchronized int get() {
+        return counter;
+    }
+}
+
+void main() throws InterruptedException {
+
+    var counter = new SynchronizedCounter();
+
+    println("=== With Synchronization (No Race Condition) ===");
+
+    var threads = new ArrayList<Thread>();
+    for (int i = 0; i < 10; i++) {
+        var thread = new Thread(() -> {
+            for (int j = 0; j < 10000; j++) {
+                counter.increment();
+            }
+        });
+        threads.add(thread);
+        thread.start();
+    }
+
+    for (var thread : threads) {
+        thread.join();
+    }
+
+    println("Expected: 100000, Actual: " + counter.get());
+}
+```
+
+The `synchronized` keyword ensures that only one thread can execute  
+the increment method at a time, eliminating the race condition.  
+
+### Stale Data  
+
+Stale data occurs when a thread reads a cached value instead of the  
+latest value in main memory.  
+
+```java
+class StaleDataDemo {
+    boolean ready = false;
+    int value = 0;
+}
+
+void main() throws InterruptedException {
+
+    println("=== Stale Data Demo ===");
+
+    var demo = new StaleDataDemo();
+
+    var reader = new Thread(() -> {
+        int spins = 0;
+        while (!demo.ready) {
+            spins++;
+            if (spins > 1000000000) {
+                println("Reader gave up after " + spins + " spins");
+                return;
+            }
+        }
+        println("Reader saw ready=true after " + spins + " spins");
+        println("Value: " + demo.value);
+    });
+
+    var writer = new Thread(() -> {
+        demo.value = 42;
+        demo.ready = true;
+        println("Writer set ready=true and value=42");
+    });
+
+    reader.start();
+    Thread.sleep(100);
+    writer.start();
+
+    writer.join();
+    reader.join(2000);
+
+    if (reader.isAlive()) {
+        println("Reader thread stuck - never saw update!");
+        reader.interrupt();
+    }
+}
+```
+
+Without volatile, the reader thread may cache the value of `ready` and  
+never see the update. This is a visibility problem that can cause the  
+program to hang indefinitely.  
+
+### Fixing Stale Data with Volatile  
+
+```java
+class VolatileFixDemo {
+    volatile boolean ready = false;
+    int value = 0;  // piggybacks on volatile synchronization
+}
+
+void main() throws InterruptedException {
+
+    println("=== Volatile Fix Demo ===");
+
+    var demo = new VolatileFixDemo();
+
+    var reader = new Thread(() -> {
+        int spins = 0;
+        while (!demo.ready) {
+            spins++;
+        }
+        println("Reader saw ready=true after " + spins + " spins");
+        println("Value: " + demo.value);  // guaranteed to see 42
+    });
+
+    var writer = new Thread(() -> {
+        demo.value = 42;
+        demo.ready = true;
+        println("Writer set ready=true and value=42");
+    });
+
+    reader.start();
+    Thread.sleep(100);
+    writer.start();
+
+    writer.join();
+    reader.join();
+}
+```
+
+Making `ready` volatile ensures the reader sees the update. Additionally,  
+due to happens-before rules, when the reader sees `ready=true`, it is  
+guaranteed to see `value=42` as well.  
+
+### Double-Checked Locking  
+
+Double-checked locking is a pattern for lazy initialization that requires  
+careful use of volatile to work correctly.  
+
+```java
+class Singleton {
+    private static volatile Singleton instance;
+
+    private Singleton() {
+        // Expensive initialization
+        println("Singleton instance created");
+    }
+
+    static Singleton getInstance() {
+        if (instance == null) {                   // First check (no locking)
+            synchronized (Singleton.class) {
+                if (instance == null) {           // Second check (with lock)
+                    instance = new Singleton();
+                }
+            }
+        }
+        return instance;
+    }
+}
+
+void main() throws InterruptedException {
+
+    println("=== Double-Checked Locking ===");
+
+    var threads = new ArrayList<Thread>();
+    for (int i = 0; i < 10; i++) {
+        var thread = new Thread(() -> {
+            Singleton s = Singleton.getInstance();
+            println(Thread.currentThread().getName() + " got: " + s);
+        });
+        threads.add(thread);
+        thread.start();
+    }
+
+    for (var thread : threads) {
+        thread.join();
+    }
+}
+```
+
+The volatile keyword is essential here. Without it, threads might see  
+a partially constructed object reference due to instruction reordering  
+during object creation.  
+
+### Initialization Safety  
+
+```java
+class ImmutableValue {
+    private final int value;
+
+    ImmutableValue(int value) {
+        this.value = value;
+    }
+
+    int getValue() {
+        return value;
+    }
+}
+
+class UnsafePublication {
+    ImmutableValue holder;  // NOT safe without volatile or synchronization
+}
+
+class SafePublication {
+    volatile ImmutableValue holder;  // Safe due to volatile
+}
+
+void main() throws InterruptedException {
+
+    println("=== Safe Publication Demo ===");
+
+    var safe = new SafePublication();
+
+    var publisher = new Thread(() -> {
+        safe.holder = new ImmutableValue(42);
+        println("Published value");
+    });
+
+    var reader = new Thread(() -> {
+        ImmutableValue v = null;
+        while ((v = safe.holder) == null) {
+            Thread.onSpinWait();
+        }
+        println("Read value: " + v.getValue());
+    });
+
+    reader.start();
+    Thread.sleep(100);
+    publisher.start();
+
+    publisher.join();
+    reader.join();
+}
+```
+
+Even though ImmutableValue has a final field, unsafe publication (without  
+volatile) could allow a reader to see a partially constructed object.  
+Volatile publication ensures the reader sees the fully constructed object.  
+
+## Best Practices  
+
+Following these guidelines helps write correct and maintainable concurrent  
+code.  
+
+### Prefer Higher-Level Concurrency Utilities  
+
+```java
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.atomic.AtomicLong;
+
+void main() throws InterruptedException {
+
+    println("=== Using Higher-Level Utilities ===");
+
+    // Use ConcurrentHashMap instead of synchronized HashMap
+    var cache = new ConcurrentHashMap<String, String>();
+
+    // Use AtomicLong instead of synchronized counter
+    var requestCount = new AtomicLong(0);
+
+    // Use ExecutorService instead of raw threads
+    ExecutorService executor = Executors.newFixedThreadPool(4);
+
+    for (int i = 0; i < 100; i++) {
+        int id = i;
+        executor.submit(() -> {
+            cache.put("key" + id, "value" + id);
+            requestCount.incrementAndGet();
+        });
+    }
+
+    executor.shutdown();
+    executor.awaitTermination(10, TimeUnit.SECONDS);
+
+    println("Cache size: " + cache.size());
+    println("Request count: " + requestCount.get());
+}
+```
+
+Higher-level utilities like ConcurrentHashMap, AtomicLong, and  
+ExecutorService are thoroughly tested, well-optimized, and less  
+error-prone than hand-rolled synchronization.  
+
+### Minimize Scope of Synchronization  
+
+```java
+class DataProcessor {
+    private final Object lock = new Object();
+    private int processedCount = 0;
+    private List<String> results = new ArrayList<>();
+
+    void process(String data) {
+        // Do expensive computation outside synchronized block
+        String processed = expensiveComputation(data);
+
+        // Only synchronize the critical section
+        synchronized (lock) {
+            results.add(processed);
+            processedCount++;
+        }
+    }
+
+    private String expensiveComputation(String data) {
+        // Simulate expensive work
+        try { Thread.sleep(10); } catch (InterruptedException e) {}
+        return data.toUpperCase();
+    }
+
+    synchronized int getProcessedCount() {
+        return processedCount;
+    }
+}
+
+void main() throws InterruptedException {
+
+    println("=== Minimizing Synchronization Scope ===");
+
+    var processor = new DataProcessor();
+    var threads = new ArrayList<Thread>();
+
+    long start = System.currentTimeMillis();
+
+    for (int i = 0; i < 20; i++) {
+        int id = i;
+        var thread = new Thread(() -> {
+            processor.process("item-" + id);
+        });
+        threads.add(thread);
+        thread.start();
+    }
+
+    for (var thread : threads) {
+        thread.join();
+    }
+
+    long duration = System.currentTimeMillis() - start;
+    println("Processed: " + processor.getProcessedCount());
+    println("Time: " + duration + "ms");
+}
+```
+
+By keeping the synchronized block small, threads can perform expensive  
+computations in parallel. Only the shared state modification needs  
+synchronization.  
+
+### Use Immutable Objects  
+
+```java
+record ImmutableRequest(String id, long timestamp, String payload) {}
+
+class RequestHandler {
+    private volatile ImmutableRequest lastRequest;
+
+    void handle(ImmutableRequest request) {
+        // Safe to share immutable object without synchronization
+        lastRequest = request;
+        process(request);
+    }
+
+    private void process(ImmutableRequest request) {
+        println("Processing: " + request.id() + " at " + request.timestamp());
+    }
+
+    ImmutableRequest getLastRequest() {
+        return lastRequest;  // Safe to return immutable object
+    }
+}
+
+void main() throws InterruptedException {
+
+    println("=== Using Immutable Objects ===");
+
+    var handler = new RequestHandler();
+    var threads = new ArrayList<Thread>();
+
+    for (int i = 0; i < 10; i++) {
+        int id = i;
+        var thread = new Thread(() -> {
+            var request = new ImmutableRequest(
+                "req-" + id, 
+                System.currentTimeMillis(), 
+                "data-" + id
+            );
+            handler.handle(request);
+        });
+        threads.add(thread);
+        thread.start();
+    }
+
+    for (var thread : threads) {
+        thread.join();
+    }
+
+    println("Last request: " + handler.getLastRequest());
+}
+```
+
+Immutable objects (like records) are inherently thread-safe. They can  
+be shared freely between threads without synchronization, simplifying  
+concurrent code and reducing the risk of bugs.  
+
+### Document Thread Safety  
+
+```java
+/**
+ * Thread-safe counter using atomic operations.
+ * <p>
+ * This class is safe for use by multiple threads. All operations
+ * are atomic and visibility is guaranteed.
+ * </p>
+ */
+import java.util.concurrent.atomic.AtomicInteger;
+
+class ThreadSafeCounter {
+    private final AtomicInteger count = new AtomicInteger(0);
+
+    /**
+     * Increments the counter atomically.
+     * Thread-safe: uses CAS operations internally.
+     */
+    public void increment() {
+        count.incrementAndGet();
+    }
+
+    /**
+     * Returns the current count.
+     * Thread-safe: atomic read of volatile field.
+     */
+    public int get() {
+        return count.get();
+    }
+}
+
+void main() {
+
+    println("=== Documenting Thread Safety ===");
+
+    var counter = new ThreadSafeCounter();
+    counter.increment();
+    println("Count: " + counter.get());
+}
+```
+
+Clear documentation about thread safety helps other developers use your  
+code correctly. State whether a class is thread-safe, conditionally  
+thread-safe, or not thread-safe.  
+
+### Decision Guide for Synchronization  
+
+| Scenario                           | Recommended Approach               |
+|------------------------------------|-----------------------------------|
+| Simple flag (one writer)           | volatile                          |
+| Counter with increment             | AtomicInteger/AtomicLong          |
+| Multiple operations must be atomic | synchronized or ReentrantLock     |
+| Read-heavy, rare writes            | ReadWriteLock                     |
+| Producer-consumer                  | BlockingQueue                     |
+| Thread-safe map                    | ConcurrentHashMap                 |
+| Thread-safe list (read-heavy)      | CopyOnWriteArrayList              |
+| Complex state machine              | synchronized with careful design  |
+| High-contention counters           | LongAdder                         |
+
+### Testing Concurrent Code  
+
+```java
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicInteger;
+
+void main() throws InterruptedException {
+
+    println("=== Testing Concurrent Code ===");
+
+    var counter = new AtomicInteger(0);
+    int threadCount = 100;
+    int iterationsPerThread = 1000;
+
+    var startLatch = new CountDownLatch(1);
+    var doneLatch = new CountDownLatch(threadCount);
+
+    ExecutorService executor = Executors.newFixedThreadPool(threadCount);
+
+    for (int i = 0; i < threadCount; i++) {
+        executor.submit(() -> {
+            try {
+                startLatch.await();  // Wait for all threads to be ready
+                for (int j = 0; j < iterationsPerThread; j++) {
+                    counter.incrementAndGet();
+                }
+            } catch (InterruptedException e) {
+                Thread.currentThread().interrupt();
+            } finally {
+                doneLatch.countDown();
+            }
+        });
+    }
+
+    // Start all threads simultaneously
+    startLatch.countDown();
+
+    // Wait for completion
+    doneLatch.await(30, TimeUnit.SECONDS);
+    executor.shutdown();
+
+    int expected = threadCount * iterationsPerThread;
+    int actual = counter.get();
+
+    println("Expected: " + expected);
+    println("Actual: " + actual);
+    println("Test " + (expected == actual ? "PASSED" : "FAILED"));
+}
+```
+
+Use CountDownLatch to synchronize thread starts for maximum concurrency  
+during testing. Run tests many times to increase the chance of detecting  
+race conditions.  
+
+## Conclusion  
+
+The Java Memory Model is a critical foundation for writing correct  
+concurrent programs. Understanding the JMM helps developers:  
+
+- **Avoid subtle bugs**: Race conditions, visibility issues, and ordering  
+  problems can cause intermittent failures that are extremely difficult  
+  to debug. Knowledge of the JMM helps identify and prevent these issues.  
+
+- **Write portable code**: The JMM provides guarantees that hold across  
+  all JVM implementations and hardware platforms. Code that correctly  
+  uses synchronization will work reliably everywhere.  
+
+- **Choose appropriate tools**: Understanding the JMM helps developers  
+  select the right synchronization mechanism for each situation, whether  
+  it's volatile, synchronized, atomic classes, or concurrent collections.  
+
+- **Reason about program behavior**: The happens-before relationship  
+  provides a formal framework for understanding when changes made by  
+  one thread will be visible to another.  
+
+### Key Takeaways  
+
+| Concept                 | Summary                                        |
+|-------------------------|------------------------------------------------|
+| Visibility              | Use volatile or synchronization to ensure      |
+|                         | changes are visible across threads             |
+| Atomicity               | Use synchronized or atomic classes for         |
+|                         | compound operations                            |
+| Happens-Before          | Synchronization creates happens-before         |
+|                         | relationships that guarantee ordering          |
+| Volatile                | Provides visibility and ordering, not          |
+|                         | atomicity for compound operations              |
+| Synchronized            | Provides mutual exclusion, visibility, and     |
+|                         | ordering guarantees                            |
+| Atomic Classes          | Lock-free thread-safe operations using CAS     |
+| Memory Barriers         | Prevent reordering of memory operations        |
+| Immutability            | Eliminates need for synchronization            |
+
+The JMM may seem complex, but its rules exist to enable efficient  
+execution while providing guarantees that programmers can rely on.  
+By following the best practices outlined in this document and using  
+higher-level concurrency utilities when possible, developers can write  
+thread-safe code that performs well and behaves correctly across all  
+platforms.  
diff --git a/modern-java/README.md b/modern-java/README.md
new file mode 100644
index 00000000..99f142ba
--- /dev/null
+++ b/modern-java/README.md
@@ -0,0 +1,39 @@
+# Modern Java
+
+
+```
+The Battle of Thermopylae was fought between an alliance of
+Greek city-states, led by King Leonidas of Sparta, and the Persian Empire of
+Xerxes I over the course of three days, during the second Persian invasion of
+Greece. 
+```
+
+The `thermopylae.txt` file. 
+
+## FileReader 
+
+Always explicitly specify the encoding for `FileReader`. Fixed in Java 11.  
+In previous versions, `FileReader` used platform defined encoding which is  
+error-prone. 
+
+```java
+import java.io.BufferedReader;
+import java.io.FileReader;
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+
+void main() throws IOException {
+
+    var fileName = "thermopylae.txt";
+
+    try (var br = new BufferedReader(new FileReader(fileName,
+            StandardCharsets.UTF_8))) {
+
+        String line;
+        while ((line = br.readLine()) != null) {
+
+            System.out.println(line);
+        }
+    }
+}
+```
diff --git a/modern-java/deprecated.md b/modern-java/deprecated.md
new file mode 100644
index 00000000..a0b14364
--- /dev/null
+++ b/modern-java/deprecated.md
@@ -0,0 +1,89 @@
+# Deprecations
+
+## URI.toURL 
+
+`URI.toURL` instead of `new URL`. 
+
+```java
+import java.net.URL;
+import java.net.URI;
+import java.net.HttpURLConnection;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+
+void main() throws Exception {
+
+    URL url = URI.create("https://webcode.me").toURL();
+
+    HttpURLConnection con = (HttpURLConnection) url.openConnection();
+    con.setConnectTimeout(5000);
+    con.setReadTimeout(5000);
+    con.setRequestMethod("GET");
+
+    con.connect();
+
+    try (InputStream is = con.getInputStream()) {
+
+        byte[] data = is.readAllBytes();
+        String msg = new String(data, StandardCharsets.UTF_8);
+
+        System.out.println(msg);
+    }
+}
+```
+
+## Locale constructors
+
+Locale constructors such as `new Locale("sk", "SK")` are deprecated since Java 19.  
+We use `Locale.of("sk", "SK")` or a builder:  
+
+```java
+Locale persian = new Locale.Builder().setLanguage("fa").setRegion("IR").build();
+```
+
+```java
+import java.text.NumberFormat;
+import java.text.ParseException;
+import java.util.Locale;
+
+void main() {
+
+    // NumberFormat nf = NumberFormat.getInstance(new Locale("sk", "SK"));
+    NumberFormat nf = NumberFormat.getInstance(Locale.of("sk", "SK"));
+    nf.setMaximumFractionDigits(3);
+
+    try {
+        Number num = nf.parse("150000,456");
+        System.out.println(num.doubleValue());
+
+    } catch (ParseException e) {
+        e.printStackTrace(); // printStackTrace used only for debuggin/testing, not in production
+    }
+}
+```
+
+## new Integer
+
+'Integer(int)' is deprecated since version 9 and marked for removal.  
+
+We should either use `Integer.valueOf` or use autoboxing.  
+
+```java
+void main() {
+
+    Integer a = new Integer(5); 
+    Integer b = new Integer(5); 
+
+    System.out.println(a == b);
+    System.out.println(a.equals(b));
+    System.out.println(a.compareTo(b));
+
+    Integer c = 155;
+    Integer d = 155;
+
+    System.out.println(c == d);
+    System.out.println(c.equals(d));
+    System.out.println(c.compareTo(d));
+}
+```
+
diff --git a/modules.md b/modules.md
new file mode 100644
index 00000000..2a8a26b3
--- /dev/null
+++ b/modules.md
@@ -0,0 +1,1519 @@
+# Java Modules
+
+Java Modules, introduced in Java 9 as part of the Java Platform Module System  
+(JPMS), represent a fundamental shift in how Java applications are structured  
+and organized. A module is a named, self-describing collection of code and data  
+that explicitly declares its dependencies and the packages it exports to other  
+modules.  
+
+Before Java 9, the JDK was a monolithic entity where all classes were accessible  
+to any application, regardless of whether they were intended for public use. This  
+led to several problems: large runtime footprints, security vulnerabilities from  
+accessing internal APIs, and difficulties in maintaining backward compatibility.  
+The classpath-based system also suffered from "JAR hell"—conflicts arising from  
+multiple versions of the same library on the classpath.  
+
+JPMS addresses these issues by introducing strong encapsulation and reliable  
+configuration. Modules explicitly declare which packages they export (making them  
+accessible to other modules) and which modules they depend on. This enables the  
+Java runtime to verify that all dependencies are satisfied before running an  
+application, preventing runtime errors from missing classes.  
+
+The modular system also enables the creation of custom runtime images using the  
+`jlink` tool, containing only the modules required by an application. This can  
+dramatically reduce the size of deployed applications—from hundreds of megabytes  
+to just a few dozen, making Java more suitable for containerized deployments and  
+microservices architectures.  
+
+## Key Concepts  
+
+- **Module**: A named, self-describing collection of packages and resources  
+- **Module Descriptor**: The `module-info.java` file declaring module metadata  
+- **Exports**: Packages that other modules can access  
+- **Requires**: Dependencies on other modules  
+- **Opens**: Packages available for deep reflection at runtime  
+- **Provides/Uses**: Service provider and consumer declarations  
+- **Readability**: The relationship between a module and its dependencies  
+- **Accessibility**: Whether a type is accessible to code in another module  
+- **Strong Encapsulation**: Internal APIs hidden from other modules by default  
+- **Reliable Configuration**: Dependencies verified at compile and runtime  
+
+## Module Types  
+
+| Type            | Description                                    | Use Case                   |
+|-----------------|------------------------------------------------|----------------------------|
+| Named Module    | Has module-info.java with explicit name        | New modular applications   |
+| Automatic Module| JAR on module path without module-info.java    | Legacy library migration   |
+| Unnamed Module  | Code on classpath (no module-info.java)        | Legacy applications        |
+
+## JDK Modules  
+
+The JDK itself is organized into approximately 70 modules. Every module  
+implicitly depends on `java.base`, which contains fundamental classes like  
+`java.lang`, `java.util`, and `java.io`.  
+
+| Module          | Description                                              |
+|-----------------|----------------------------------------------------------|
+| `java.base`     | Fundamental classes (always available)                   |
+| `java.sql`      | JDBC API for database access                             |
+| `java.xml`      | XML processing APIs                                      |
+| `java.logging`  | Java Logging API                                         |
+| `java.desktop`  | AWT and Swing UI libraries                               |
+| `java.net.http` | HTTP Client API                                          |
+| `java.compiler` | Java Compiler API                                        |
+| `jdk.httpserver`| Simple HTTP server for testing                           |
+
+
+## Basic module declaration  
+
+A module is declared using the `module-info.java` file placed at the root of  
+the module's source directory.  
+
+```java
+// module-info.java
+module com.example.greeting {
+    // This is the simplest possible module declaration
+    // It implicitly requires java.base
+}
+```
+
+```java
+// com/example/greeting/Greeter.java
+package com.example.greeting;
+
+public class Greeter {
+    public String greet(String name) {
+        return "Hello, " + name + "!";
+    }
+}
+```
+
+The module declaration establishes a namespace and encapsulation boundary for  
+the code. Without any `exports` directive, all packages in the module are  
+hidden from other modules. The module name typically follows reverse DNS  
+naming conventions, similar to package names.  
+
+
+## Exporting packages  
+
+The `exports` directive makes a package accessible to other modules.  
+
+```java
+// module-info.java
+module com.example.math {
+    exports com.example.math.operations;
+}
+```
+
+```java
+// com/example/math/operations/Calculator.java
+package com.example.math.operations;
+
+public class Calculator {
+    public int add(int a, int b) {
+        return a + b;
+    }
+
+    public int multiply(int a, int b) {
+        return a * b;
+    }
+}
+```
+
+```java
+// com/example/math/internal/MathHelper.java
+package com.example.math.internal;
+
+// This class is NOT accessible outside the module
+class MathHelper {
+    static int square(int n) {
+        return n * n;
+    }
+}
+```
+
+Only types in exported packages are accessible to other modules. The  
+`com.example.math.internal` package remains encapsulated and cannot be  
+accessed even if another module tries to import it. This enforces a clear  
+public API boundary.  
+
+
+## Requiring dependencies  
+
+The `requires` directive declares a dependency on another module.  
+
+```java
+// module-info.java for com.example.app
+module com.example.app {
+    requires com.example.math;
+}
+```
+
+```java
+// com/example/app/Main.java
+package com.example.app;
+
+import com.example.math.operations.Calculator;
+
+public class Main {
+    public static void main(String[] args) {
+        var calc = new Calculator();
+        System.out.println("5 + 3 = " + calc.add(5, 3));
+        System.out.println("5 * 3 = " + calc.multiply(5, 3));
+    }
+}
+```
+
+The `requires` directive establishes a readability relationship—code in  
+`com.example.app` can read (access exported types from) `com.example.math`.  
+If the required module is not present at compile or runtime, an error occurs.  
+This provides reliable configuration, catching missing dependencies early.  
+
+
+## Transitive dependencies  
+
+The `requires transitive` directive passes readability to dependent modules.  
+
+```java
+// module-info.java for com.example.core
+module com.example.core {
+    requires transitive com.example.logging;
+    exports com.example.core;
+}
+```
+
+```java
+// module-info.java for com.example.app
+module com.example.app {
+    requires com.example.core;
+    // Implicitly can read com.example.logging due to 'requires transitive'
+}
+```
+
+When module A requires transitive module B, any module that requires A can  
+also read B. This is useful when a module's public API exposes types from  
+another module. Without `transitive`, clients would need to explicitly require  
+both modules, leading to verbose and error-prone declarations.  
+
+
+## Qualified exports  
+
+The `exports ... to` directive restricts package access to specific modules.  
+
+```java
+// module-info.java
+module com.example.framework {
+    exports com.example.framework.api;
+    exports com.example.framework.internal to com.example.framework.impl;
+}
+```
+
+Qualified exports allow fine-grained access control. The internal package  
+is only accessible to the specified implementation module, not to any other  
+module. This pattern is common in frameworks where internal APIs need to be  
+shared between closely related modules while remaining hidden from users.  
+
+
+## Opening packages for reflection  
+
+The `opens` directive allows runtime reflective access to a package.  
+
+```java
+// module-info.java
+module com.example.model {
+    exports com.example.model.dto;
+    opens com.example.model.entity to com.example.orm;
+}
+```
+
+```java
+// com/example/model/entity/User.java
+package com.example.model.entity;
+
+public class User {
+    private String name;
+    private int age;
+
+    public User() {}
+
+    public User(String name, int age) {
+        this.name = name;
+        this.age = age;
+    }
+
+    // Getters and setters
+    public String getName() { return name; }
+    public void setName(String name) { this.name = name; }
+    public int getAge() { return age; }
+    public void setAge(int age) { this.age = age; }
+}
+```
+
+The `opens` directive allows frameworks like Hibernate or Jackson to access  
+private fields via reflection. Unlike `exports`, which controls compile-time  
+access, `opens` specifically enables deep reflection at runtime. You can use  
+`opens ... to` for qualified access or just `opens` for universal access.  
+
+
+## Open modules  
+
+An `open module` allows all packages to be reflectively accessed.  
+
+```java
+// module-info.java
+open module com.example.webapp {
+    requires com.example.framework;
+    exports com.example.webapp.controllers;
+}
+```
+
+Open modules simplify migration of applications that heavily use reflection,  
+such as Spring Boot or Jakarta EE applications. All packages are open for  
+deep reflection while still requiring explicit `exports` for compile-time  
+access. This provides a balance between encapsulation and framework compatibility.  
+
+
+## Service provider interface  
+
+The `provides ... with` directive declares that a module provides a service  
+implementation.  
+
+```java
+// module-info.java for service API module
+module com.example.messaging.api {
+    exports com.example.messaging;
+}
+```
+
+```java
+// com/example/messaging/MessageService.java
+package com.example.messaging;
+
+public interface MessageService {
+    void send(String message);
+}
+```
+
+```java
+// module-info.java for service provider module
+module com.example.messaging.email {
+    requires com.example.messaging.api;
+    provides com.example.messaging.MessageService
+        with com.example.messaging.email.EmailService;
+}
+```
+
+```java
+// com/example/messaging/email/EmailService.java
+package com.example.messaging.email;
+
+import com.example.messaging.MessageService;
+
+public class EmailService implements MessageService {
+    @Override
+    public void send(String message) {
+        System.out.println("Sending email: " + message);
+    }
+}
+```
+
+Services enable loose coupling between modules. The API module defines the  
+interface, and provider modules supply implementations without the consumer  
+needing compile-time knowledge of specific implementations. This is the  
+foundation for plugin architectures.  
+
+
+## Service consumer  
+
+The `uses` directive declares that a module consumes a service.  
+
+```java
+// module-info.java for service consumer module
+module com.example.app {
+    requires com.example.messaging.api;
+    uses com.example.messaging.MessageService;
+}
+```
+
+```java
+// com/example/app/Application.java
+package com.example.app;
+
+import com.example.messaging.MessageService;
+import java.util.ServiceLoader;
+
+public class Application {
+    public static void main(String[] args) {
+        ServiceLoader<MessageService> loader = 
+            ServiceLoader.load(MessageService.class);
+
+        for (MessageService service : loader) {
+            service.send("Hello from modular Java!");
+        }
+    }
+}
+```
+
+The `ServiceLoader` discovers and instantiates all available implementations  
+at runtime. Multiple providers can coexist, and new implementations can be  
+added by simply placing the provider module on the module path. This enables  
+runtime extensibility without recompilation.  
+
+
+## Static dependencies  
+
+The `requires static` directive declares an optional compile-time dependency.  
+
+```java
+// module-info.java
+module com.example.app {
+    requires static com.example.annotations;
+    requires static org.slf4j;
+}
+```
+
+Static dependencies are required at compile time but optional at runtime.  
+This is useful for annotation processors that are only needed during  
+compilation, or for logging facades where the implementation might not always  
+be present. If the module is absent at runtime, no error occurs unless code  
+actually attempts to use it.  
+
+
+## Listing module dependencies  
+
+Use the `java` command with `--describe-module` to view module information.  
+
+```bash
+# Describe a JDK module
+java --describe-module java.sql
+
+# Output example:
+# java.sql jar:file:///path/to/jdk/jmods/java.sql.jmod!/module-info.class
+# exports java.sql
+# exports javax.sql
+# requires java.base mandated
+# requires java.xml transitive
+# requires java.logging transitive
+# uses java.sql.Driver
+```
+
+The `--describe-module` (or `-d`) option displays the module's exports,  
+requires, uses, and provides directives. This is invaluable for understanding  
+module dependencies and troubleshooting configuration issues. You can also  
+use `--list-modules` to see all available modules.  
+
+
+## Compiling modular code  
+
+Modular applications are compiled using the `--module-source-path` option.  
+
+```bash
+# Project structure:
+# src/
+#   com.example.greeting/
+#     module-info.java
+#     com/example/greeting/Greeter.java
+#   com.example.app/
+#     module-info.java
+#     com/example/app/Main.java
+
+# Compile specific modules (recommended)
+javac -d out --module-source-path src -m com.example.greeting,com.example.app
+
+# Or compile all modules using find (for small projects)
+javac -d out --module-source-path src @sources.txt
+# where sources.txt contains: find src -name "*.java" > sources.txt
+```
+
+The `--module-source-path` option specifies the root directory containing  
+module source code. Each module must be in a directory matching its module  
+name. The `-d` option specifies the output directory for compiled classes.  
+The compiler validates all module dependencies during compilation.  
+
+
+## Running modular applications  
+
+Modular applications run using the `--module-path` and `--module` options.  
+
+```bash
+# Run a modular application
+java --module-path out --module com.example.app/com.example.app.Main
+
+# Or use short options
+java -p out -m com.example.app/com.example.app.Main
+```
+
+The `--module-path` (or `-p`) specifies where to find compiled modules.  
+The `--module` (or `-m`) specifies the module and main class to run in the  
+format `module/mainclass`. The module system verifies all dependencies are  
+satisfied before starting execution.  
+
+
+## Creating modular JARs  
+
+Modular JARs include the `module-info.class` at the JAR root.  
+
+```bash
+# Create a modular JAR
+jar --create --file greeting.jar \
+    --module-version=1.0 \
+    -C out/com.example.greeting .
+
+# Create an executable modular JAR
+jar --create --file app.jar \
+    --main-class=com.example.app.Main \
+    --module-version=1.0 \
+    -C out/com.example.app .
+```
+
+Modular JARs are standard JAR files with a `module-info.class` file. The  
+`--module-version` option embeds version information in the module descriptor.  
+The `--main-class` option sets the entry point, allowing the JAR to be run  
+with just `-m module-name` without specifying the main class.  
+
+
+## Multi-release JARs  
+
+Multi-release JARs support different code for different Java versions.  
+
+```
+# JAR structure:
+mymodule.jar
+├── module-info.class           (for Java 9+)
+├── META-INF/
+│   ├── MANIFEST.MF
+│   └── versions/
+│       ├── 11/
+│       │   └── com/example/Helper.class
+│       └── 17/
+│           └── com/example/Helper.class
+└── com/example/
+    ├── Main.class
+    └── Helper.class             (base version for Java 8)
+```
+
+Multi-release JARs allow a single JAR to contain version-specific code. The  
+JVM automatically selects the appropriate classes based on the runtime version.  
+This enables libraries to use modern APIs when available while maintaining  
+compatibility with older Java versions.  
+
+
+## Automatic modules  
+
+JARs without module-info.java become automatic modules on the module path.  
+
+```java
+// module-info.java
+module com.example.app {
+    // Automatic module name is derived from JAR filename
+    // guava-31.1-jre.jar becomes guava
+    requires guava;
+}
+```
+
+```bash
+# Run with automatic module
+java --module-path libs:out \
+     --module com.example.app/com.example.app.Main
+```
+
+Automatic modules enable gradual migration by allowing non-modular JARs to  
+participate in the module system. The module name is derived from the JAR  
+filename (or from `Automatic-Module-Name` manifest attribute). Automatic  
+modules export all packages and can read all other modules.  
+
+
+## Automatic-Module-Name manifest entry  
+
+Library maintainers can declare a stable automatic module name.  
+
+```
+# META-INF/MANIFEST.MF
+Manifest-Version: 1.0
+Automatic-Module-Name: com.example.library
+```
+
+```bash
+# Build JAR with Automatic-Module-Name
+jar --create --file library.jar \
+    --manifest=MANIFEST.MF \
+    -C classes .
+```
+
+The `Automatic-Module-Name` attribute provides a stable module name for  
+non-modular JARs. This is important for library authors who want to reserve  
+their module name before fully modularizing. It ensures dependent modules  
+won't break when the library later adds a real module-info.java.  
+
+
+## Unnamed module  
+
+Code on the classpath belongs to the unnamed module.  
+
+```bash
+# Running with classpath (unnamed module)
+java -cp out:libs/* com.example.app.Main
+
+# Mixing classpath and module path
+java --module-path mods \
+     --classpath libs/* \
+     --add-modules com.example.api \
+     -m com.example.app/com.example.app.Main
+```
+
+The unnamed module can read all named modules but named modules cannot  
+require the unnamed module. This ensures a clean migration path—modular code  
+cannot depend on non-modular code, encouraging bottom-up modularization of  
+dependencies before applications.  
+
+
+## Adding modules at runtime  
+
+The `--add-modules` option adds modules to the root set.  
+
+```bash
+# Add specific modules
+java --module-path libs:out \
+     --add-modules com.example.logging \
+     -m com.example.app/com.example.app.Main
+
+# Add all automatic modules
+java --module-path libs:out \
+     --add-modules ALL-MODULE-PATH \
+     -m com.example.app/com.example.app.Main
+```
+
+By default, only the root module and its transitive dependencies are  
+resolved. `--add-modules` explicitly includes additional modules that might  
+not be directly required. `ALL-MODULE-PATH` adds all modules found on the  
+module path, useful during migration.  
+
+
+## Adding exports at runtime  
+
+The `--add-exports` option opens internal APIs at runtime.  
+
+```bash
+# Export internal package to specific module
+java --module-path out \
+     --add-exports com.example.core/com.example.core.internal=com.example.app \
+     -m com.example.app/com.example.app.Main
+
+# Export to all unnamed modules
+java --add-exports java.base/sun.nio.ch=ALL-UNNAMED \
+     -cp out com.example.Main
+```
+
+`--add-exports` is a workaround for accessing non-exported packages. This is  
+often needed during migration when code depends on internal APIs. The format  
+is `module/package=target-module`. Use sparingly and work toward removing  
+these dependencies as they may break in future Java versions.  
+
+
+## Adding opens at runtime  
+
+The `--add-opens` option enables deep reflection at runtime.  
+
+```bash
+# Open package for reflection
+java --module-path out \
+     --add-opens com.example.model/com.example.model.entity=com.example.orm \
+     -m com.example.app/com.example.app.Main
+
+# Open for all unnamed modules (common for frameworks on classpath)
+java --add-opens java.base/java.lang=ALL-UNNAMED \
+     -cp libs/*:out com.example.Main
+```
+
+`--add-opens` is necessary when frameworks need to reflectively access  
+private fields or methods in packages that aren't opened. This is commonly  
+needed for serialization frameworks, dependency injection, and ORM tools.  
+Like `--add-exports`, this should be considered a temporary migration aid.  
+
+
+## Reading modules programmatically  
+
+The `ModuleLayer` and `Module` APIs provide runtime module introspection.  
+
+```java
+void main() {
+
+    // Get the boot layer (contains all platform modules)
+    var bootLayer = ModuleLayer.boot();
+
+    // List all modules in the boot layer
+    println("Modules in boot layer:");
+    bootLayer.modules().stream()
+        .map(Module::getName)
+        .sorted()
+        .limit(10)
+        .forEach(name -> println("  " + name));
+
+    // Get information about a specific module
+    var sqlModule = bootLayer.findModule("java.sql");
+    sqlModule.ifPresent(m -> {
+        println("\njava.sql module:");
+        println("  Packages: " + m.getPackages());
+        println("  Descriptor: " + m.getDescriptor());
+    });
+}
+```
+
+The `ModuleLayer` represents a resolved set of modules. The boot layer is  
+created by the JVM and contains platform modules plus any modules resolved  
+from the module path. Applications can inspect module metadata at runtime,  
+useful for debugging or building module-aware frameworks.  
+
+
+## Module descriptor API  
+
+The `ModuleDescriptor` class provides compile-time module metadata.  
+
+```java
+void main() {
+
+    var descriptor = ModuleLayer.boot()
+        .findModule("java.sql")
+        .map(Module::getDescriptor)
+        .orElseThrow();
+
+    println("Module: " + descriptor.name());
+    println("Version: " + descriptor.version().orElse(null));
+
+    println("\nExports:");
+    descriptor.exports().forEach(e ->
+        println("  " + e.source() + 
+            (e.isQualified() ? " to " + e.targets() : "")));
+
+    println("\nRequires:");
+    descriptor.requires().forEach(r ->
+        println("  " + r.name() + 
+            (r.modifiers().isEmpty() ? "" : " " + r.modifiers())));
+
+    println("\nUses:");
+    descriptor.uses().forEach(u -> println("  " + u));
+}
+```
+
+The `ModuleDescriptor` API provides programmatic access to all information  
+in a module-info.java file. This enables tools to analyze module structure,  
+verify dependencies, or generate documentation without parsing source code.  
+
+
+## Checking module readability  
+
+Verify if one module can read another at runtime.  
+
+```java
+void main() {
+
+    var bootLayer = ModuleLayer.boot();
+
+    var sqlModule = bootLayer.findModule("java.sql").orElseThrow();
+    var loggingModule = bootLayer.findModule("java.logging").orElseThrow();
+    var baseModule = bootLayer.findModule("java.base").orElseThrow();
+
+    println("java.sql reads java.logging: " + sqlModule.canRead(loggingModule));
+    println("java.sql reads java.base: " + sqlModule.canRead(baseModule));
+
+    // Check if a package is exported
+    println("\njava.sql exports javax.sql: " + 
+        sqlModule.isExported("javax.sql"));
+    println("java.sql exports sun.* (internal): " + 
+        sqlModule.isExported("com.sun.rowset.internal"));
+}
+```
+
+The `canRead` method checks if a readability relationship exists between  
+modules. The `isExported` method checks if a package is accessible to other  
+modules. These APIs are useful for debugging module configuration issues and  
+building tools that analyze module graphs.  
+
+
+## Custom module layers  
+
+Create isolated module configurations using ModuleLayer.  
+
+```java
+import java.lang.module.*;
+import java.nio.file.Path;
+
+void main() throws Exception {
+
+    // Find modules from a path
+    var finder = ModuleFinder.of(Path.of("plugins"));
+
+    // Create a configuration for the new layer
+    var bootLayer = ModuleLayer.boot();
+    var cf = bootLayer.configuration().resolve(
+        finder,
+        ModuleFinder.of(),
+        Set.of("com.example.plugin")
+    );
+
+    // Create the layer with a new class loader
+    var layer = bootLayer.defineModulesWithOneLoader(
+        cf,
+        ClassLoader.getSystemClassLoader()
+    );
+
+    // Find and use a class from the plugin module
+    var pluginClass = layer.findLoader("com.example.plugin")
+        .loadClass("com.example.plugin.Plugin");
+
+    println("Loaded plugin: " + pluginClass.getName());
+}
+```
+
+Custom module layers enable plugin systems and application isolation. Each  
+layer can have its own version of modules, allowing multiple versions of the  
+same library to coexist. This is particularly useful for application servers  
+hosting multiple applications.  
+
+
+## ServiceLoader with modules  
+
+ServiceLoader integrates seamlessly with the module system.  
+
+```java
+// module-info.java for API
+module com.example.plugin.api {
+    exports com.example.plugin;
+}
+```
+
+```java
+// com/example/plugin/Plugin.java
+package com.example.plugin;
+
+public interface Plugin {
+    String getName();
+    void execute();
+}
+```
+
+```java
+// module-info.java for implementation
+module com.example.plugin.hello {
+    requires com.example.plugin.api;
+    provides com.example.plugin.Plugin
+        with com.example.plugin.hello.HelloPlugin;
+}
+```
+
+```java
+// com/example/plugin/hello/HelloPlugin.java
+package com.example.plugin.hello;
+
+import com.example.plugin.Plugin;
+
+public class HelloPlugin implements Plugin {
+    @Override
+    public String getName() {
+        return "Hello Plugin";
+    }
+
+    @Override
+    public void execute() {
+        System.out.println("Hello from plugin!");
+    }
+}
+```
+
+```java
+// Application using plugins
+void main() {
+
+    var plugins = ServiceLoader.load(Plugin.class);
+
+    println("Available plugins:");
+    for (var plugin : plugins) {
+        println("  - " + plugin.getName());
+        plugin.execute();
+    }
+}
+```
+
+The `provides` and `uses` directives make service relationships explicit  
+in module descriptors. This allows the module system to verify at launch time  
+that required services are available, preventing runtime service discovery  
+failures.  
+
+
+## Resource encapsulation  
+
+Resources in modules follow the same encapsulation rules as packages.  
+
+```java
+void main() throws Exception {
+
+    // Access resource from own module
+    try (var stream = getClass().getResourceAsStream("/config.properties")) {
+        if (stream != null) {
+            var props = new java.util.Properties();
+            props.load(stream);
+            println("Config: " + props);
+        }
+    }
+
+    // Access resource from another module (must be in open or exported package)
+    var module = ModuleLayer.boot().findModule("java.base").orElseThrow();
+    try (var stream = module.getResourceAsStream("java/lang/Object.class")) {
+        if (stream != null) {
+            println("Object.class size: " + stream.readAllBytes().length);
+        }
+    }
+}
+```
+
+Resources in a module package are encapsulated along with the package code.  
+Resources in the module root or in open/exported packages are accessible.  
+For other packages, use `Module.getResourceAsStream` with the fully qualified  
+resource name including the package path.  
+
+
+## Patching modules  
+
+The `--patch-module` option adds or replaces classes in a module.  
+
+```bash
+# Patch a module with additional classes
+java --module-path mods \
+     --patch-module com.example.app=patches/com.example.app \
+     -m com.example.app/com.example.app.Main
+
+# Patch a JDK module for testing
+java --patch-module java.base=patches/java.base \
+     --add-exports java.base/jdk.internal.misc=ALL-UNNAMED \
+     -cp test TestInternals
+```
+
+Module patching is useful for testing, debugging, or temporarily fixing bugs  
+without rebuilding modules. The patched classes are loaded instead of the  
+original classes. This is primarily a development and testing tool and should  
+not be used in production deployments.  
+
+
+## jdeps dependency analysis  
+
+The `jdeps` tool analyzes class dependencies and module requirements.  
+
+```bash
+# Analyze dependencies of a JAR
+jdeps --module-path libs myapp.jar
+
+# Generate module-info.java
+jdeps --generate-module-info out --module-path libs myapp.jar
+
+# Check for JDK internal API usage
+jdeps --jdk-internals myapp.jar
+
+# Show package-level dependencies
+jdeps -verbose:package myapp.jar
+
+# Analyze in dot format for visualization
+jdeps --dot-output deps myapp.jar
+```
+
+The `jdeps` tool is essential for migration planning. It identifies  
+dependencies on JDK internal APIs (which are now encapsulated) and helps  
+generate initial module-info.java files. The `--jdk-internals` option  
+specifically highlights code that will break under strict encapsulation.  
+
+
+## jlink custom runtime image  
+
+The `jlink` tool creates minimal runtime images containing only required  
+modules.  
+
+```bash
+# Create custom runtime with only needed modules
+jlink --module-path $JAVA_HOME/jmods:out \
+      --add-modules com.example.app \
+      --output custom-runtime \
+      --strip-debug \
+      --compress zip-6 \
+      --no-header-files \
+      --no-man-pages
+
+# Run application with custom runtime
+./custom-runtime/bin/java -m com.example.app/com.example.app.Main
+```
+
+Custom runtime images can be dramatically smaller than the full JDK. A simple  
+application might only need `java.base`, reducing the image from ~300MB to  
+~30MB. This is ideal for containerized deployments where image size impacts  
+startup time and resource usage.  
+
+
+## jlink launcher scripts  
+
+Create native launchers for modular applications.  
+
+```bash
+# Create runtime with launcher
+jlink --module-path $JAVA_HOME/jmods:out \
+      --add-modules com.example.app \
+      --output myapp \
+      --launcher myapp=com.example.app/com.example.app.Main
+
+# Run using the launcher
+./myapp/bin/myapp
+```
+
+The `--launcher` option creates a platform-specific script (or executable)  
+that runs the application without requiring users to know the module and  
+class names. This provides a more user-friendly deployment experience.  
+
+
+## Encapsulation and reflection  
+
+Strong encapsulation affects reflective access to module internals.  
+
+```java
+import java.lang.reflect.*;
+
+void main() throws Exception {
+
+    // This works - String is in an exported package
+    var stringClass = String.class;
+    var valueField = stringClass.getDeclaredField("value");
+    println("String.value field: " + valueField.getType());
+
+    // This would fail without --add-opens
+    try {
+        valueField.setAccessible(true);  // Requires deep reflection
+        println("Got accessible (module is open)");
+    } catch (InaccessibleObjectException e) {
+        println("Cannot access: " + e.getMessage());
+        println("Use: --add-opens java.base/java.lang=ALL-UNNAMED");
+    }
+}
+```
+
+The `setAccessible(true)` call requires deep reflective access. In the module  
+system, this only succeeds if the target package is opened (via `opens`  
+directive or `--add-opens`). This protects internal implementation details  
+from being modified by malicious or buggy code.  
+
+
+## Module resolution  
+
+The module system resolves dependencies in a specific order.  
+
+```
+Resolution process:
+1. Root modules (specified with -m or --add-modules)
+2. Add required modules transitively
+3. Add service providers for used services
+4. Verify no split packages (same package in multiple modules)
+5. Check for cyclic dependencies (not allowed)
+6. Create readable graph
+```
+
+```bash
+# Show module resolution
+java --module-path mods --show-module-resolution -m com.example.app/com.example.app.Main
+```
+
+Module resolution is deterministic and happens at startup. The  
+`--show-module-resolution` option displays the resolution process, helpful  
+for debugging complex module configurations. Any resolution failure results  
+in an error before the application starts.  
+
+
+## Split package handling  
+
+Split packages (same package in multiple modules) are prohibited.  
+
+```java
+// This is NOT allowed:
+// Module A contains: com.example.utils.StringUtils
+// Module B contains: com.example.utils.NumberUtils
+// Both export com.example.utils -> SPLIT PACKAGE ERROR
+```
+
+```bash
+# Resolution error example:
+# Error: Package com.example.utils in both moduleA and moduleB
+
+# Workaround: Merge into single module or rename packages
+```
+
+Split packages occur when the same package appears in multiple modules. This  
+was common with the classpath where JARs could contribute classes to the same  
+package. The module system requires each package to belong to exactly one  
+module. Migration may require refactoring packages.  
+
+
+## Illegal access warnings  
+
+The JVM warns about illegal reflective access during migration.  
+
+```bash
+# Java 9-15: Warning by default, access permitted
+# Java 16: Warning by default, access permitted
+# Java 17+: Strong encapsulation, access denied by default
+
+# Show all illegal access warnings
+java --illegal-access=warn ...
+
+# Deny all illegal access (default in Java 17+)
+java --illegal-access=deny ...
+
+# Permit illegal access with warnings (deprecated)
+java --illegal-access=permit ...
+```
+
+These warnings help identify code that needs migration. The progression from  
+warnings to denial gives developers time to update their code. Modern Java  
+versions require explicit `--add-opens` flags for any deep reflection into  
+JDK internals.  
+
+
+## Maven module configuration  
+
+Configure Maven for modular builds.  
+
+```xml
+<!-- pom.xml -->
+<project>
+    <modelVersion>4.0.0</modelVersion>
+    <groupId>com.example</groupId>
+    <artifactId>mymodule</artifactId>
+    <version>1.0.0</version>
+
+    <properties>
+        <maven.compiler.source>21</maven.compiler.source>
+        <maven.compiler.target>21</maven.compiler.target>
+    </properties>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <version>3.11.0</version>
+            </plugin>
+        </plugins>
+    </build>
+</project>
+```
+
+```
+# Project structure:
+src/
+  main/
+    java/
+      module-info.java
+      com/example/mymodule/
+        Main.java
+```
+
+Maven automatically detects `module-info.java` and compiles in module mode.  
+The module descriptor should be placed at `src/main/java/module-info.java`.  
+Maven handles the module path configuration automatically during compilation  
+and testing.  
+
+
+## Gradle module configuration  
+
+Configure Gradle for modular builds.  
+
+```groovy
+// build.gradle
+plugins {
+    id 'java'
+    id 'application'
+}
+
+java {
+    modularity.inferModulePath = true
+    sourceCompatibility = JavaVersion.VERSION_21
+    targetCompatibility = JavaVersion.VERSION_21
+}
+
+application {
+    mainModule = 'com.example.app'
+    mainClass = 'com.example.app.Main'
+}
+
+tasks.withType(JavaCompile) {
+    options.encoding = 'UTF-8'
+}
+```
+
+```
+# Project structure:
+src/
+  main/
+    java/
+      module-info.java
+      com/example/app/
+        Main.java
+```
+
+Gradle 6.4+ supports JPMS with automatic module path inference. The  
+`inferModulePath` option automatically places modular JARs on the module path  
+and non-modular JARs on the classpath. The `application` plugin configuration  
+specifies the module and main class.  
+
+
+## Testing modular code  
+
+Configure testing frameworks for modular applications.  
+
+```java
+// src/main/java/module-info.java
+module com.example.calculator {
+    exports com.example.calculator;
+}
+```
+
+```java
+// src/test/java/module-info.java
+open module com.example.calculator.test {
+    requires com.example.calculator;
+    requires org.junit.jupiter.api;
+}
+```
+
+```java
+// src/test/java/com/example/calculator/test/CalculatorTest.java
+package com.example.calculator.test;
+
+import com.example.calculator.Calculator;
+import org.junit.jupiter.api.Test;
+import static org.junit.jupiter.api.Assertions.*;
+
+class CalculatorTest {
+    @Test
+    void testAdd() {
+        var calc = new Calculator();
+        assertEquals(5, calc.add(2, 3));
+    }
+}
+```
+
+Test modules typically require the module under test and testing frameworks.  
+The `open` modifier allows test frameworks to reflectively access test  
+classes. Some build tools use `--add-reads` and `--add-opens` instead of  
+separate test modules.  
+
+
+## Handling legacy libraries  
+
+Strategies for using non-modular libraries in modular applications.  
+
+```java
+// module-info.java
+module com.example.app {
+    // Library with Automatic-Module-Name in manifest
+    requires org.apache.commons.lang3;
+
+    // Library without - name derived from filename
+    requires gson;  // from gson-2.10.jar
+}
+```
+
+```bash
+# If module name conflicts or missing:
+# 1. Check for Automatic-Module-Name in JAR manifest
+unzip -p gson-2.10.jar META-INF/MANIFEST.MF | grep Automatic
+
+# 2. Use --add-modules for runtime-only modules
+java --module-path libs:out \
+     --add-modules ALL-MODULE-PATH \
+     -m com.example.app/com.example.app.Main
+```
+
+When using legacy libraries, check if they define `Automatic-Module-Name` in  
+their manifest. If not, the module name is derived from the JAR filename  
+after removing version numbers and replacing hyphens with dots. Consider  
+reporting issues to library maintainers encouraging modularization.  
+
+
+## Migration strategy bottom-up  
+
+Migrate applications from classpath to module path incrementally.  
+
+```
+Bottom-up migration approach:
+1. Analyze dependencies with jdeps
+2. Wait for/request library modularization
+3. Modularize lowest-level (leaf) modules first
+4. Work up the dependency tree
+5. Modularize application last
+
+Advantages:
+- Clean dependency graph
+- Each step is independently testable
+- Libraries become reusable modules
+```
+
+```bash
+# Step 1: Analyze with jdeps
+jdeps --jdk-internals myapp.jar
+
+# Step 2: Check library status
+jdeps --module-path libs --check libs/dependency.jar
+
+# Step 3: Start with leaf dependencies
+# (those with no dependencies on your other code)
+```
+
+Bottom-up migration is the recommended approach. It ensures each module can  
+properly declare its dependencies on already-modularized code. This approach  
+may be slow if waiting for third-party libraries but produces the cleanest  
+module architecture.  
+
+
+## Migration strategy top-down  
+
+Migrate the application module first, using automatic modules for  
+dependencies.  
+
+```java
+// module-info.java for application
+module com.example.app {
+    // Automatic modules from classpath JARs
+    requires commons.lang3;
+    requires guava;
+    requires slf4j.api;
+
+    // Your modularized code
+    requires com.example.core;
+
+    exports com.example.app;
+}
+```
+
+```bash
+# Run with mix of modules and classpath
+java --module-path mods:libs \
+     -m com.example.app/com.example.app.Main
+```
+
+Top-down migration enables faster adoption of the module system for your  
+application code. Dependencies become automatic modules, which export  
+everything and can read all other modules. This approach sacrifices some  
+encapsulation benefits but allows immediate modularization.  
+
+
+## Avoiding common pitfalls  
+
+Common mistakes when adopting the module system and how to avoid them.  
+
+```java
+// PITFALL 1: Accessing internal APIs
+// Old code using sun.misc.Unsafe
+// Solution: Use VarHandle or --add-opens as temporary fix
+
+// PITFALL 2: Forgetting to export packages
+// module-info.java
+module com.example.api {
+    // WRONG: Package not exported, clients can't use it
+    // exports com.example.api;  // Uncomment this!
+}
+
+// PITFALL 3: Cyclic dependencies
+// Module A requires Module B
+// Module B requires Module A  // NOT ALLOWED
+// Solution: Extract shared code to Module C
+
+// PITFALL 4: Split packages
+// Same package in multiple modules
+// Solution: Rename packages or merge modules
+```
+
+Most pitfalls can be avoided by running `jdeps` early to identify issues.  
+Start with `--illegal-access=warn` to see potential problems. Design modules  
+around clear API boundaries rather than trying to modularize existing package  
+structures that may have circular dependencies.  
+
+
+## Module best practices  
+
+Guidelines for effective module design.  
+
+```java
+// Best Practice 1: Export API packages only
+module com.example.service {
+    exports com.example.service.api;          // Public API
+    // Internal packages not exported:
+    // com.example.service.internal
+    // com.example.service.impl
+}
+
+// Best Practice 2: Minimize dependencies
+module com.example.core {
+    requires transitive com.example.model;    // Part of API
+    requires com.example.logging;             // Implementation detail
+}
+
+// Best Practice 3: Use services for extensibility
+module com.example.framework {
+    exports com.example.framework.spi;
+    uses com.example.framework.spi.Extension;
+}
+
+// Best Practice 4: Open specific packages, not entire module
+module com.example.entity {
+    exports com.example.entity;
+    opens com.example.entity to com.fasterxml.jackson.databind;
+}
+```
+
+Design modules around stable APIs rather than implementation details. Keep  
+modules focused—a module should have a single clear purpose. Use qualified  
+exports and opens to limit access to specific trusted modules rather than  
+exposing internals to everyone.  
+
+
+## Module versioning  
+
+Modules can include version information for documentation and tooling.  
+
+```java
+// Specify version when creating JAR
+// jar --create --file mylib.jar --module-version=2.1.0 -C classes .
+```
+
+```java
+void main() {
+
+    ModuleLayer.boot().modules().stream()
+        .filter(m -> m.getName().startsWith("java."))
+        .limit(5)
+        .forEach(m -> {
+            var version = m.getDescriptor()
+                .version()
+                .map(v -> v.toString())
+                .orElse("(no version)");
+            println(m.getName() + ": " + version);
+        });
+}
+```
+
+Module versions are optional and for informational purposes—they don't  
+affect resolution. The JPMS does not support multiple versions of the same  
+module in a single layer. For versioning requirements, use build tools like  
+Maven or Gradle that handle version resolution before creating the module  
+path.  
+
+
+## Comparing modules with OSGi  
+
+Differences between JPMS and OSGi module systems.  
+
+```
+Feature          | JPMS                    | OSGi
+-----------------|-------------------------|---------------------------
+Scope            | Platform-level          | Application framework
+Versioning       | Single version per layer| Multiple versions supported
+Dynamic updates  | Not supported           | Hot deployment supported
+Service registry | ServiceLoader           | OSGi Service Registry
+Encapsulation    | Compile & runtime       | Runtime only
+Integration      | Built into JVM          | Requires OSGi container
+Complexity       | Simpler                 | More powerful, complex
+```
+
+JPMS and OSGi solve different problems. JPMS provides platform-level  
+modularity with strong compile-time checking. OSGi offers more dynamic  
+capabilities including runtime updates and multiple versions. Many  
+applications may benefit from using both—JPMS for platform structure and  
+OSGi for dynamic plugin management.  
+
+
+## Performance implications  
+
+Module system impact on application performance.  
+
+```java
+void main() {
+
+    // Module resolution happens at startup
+    // - Single resolution, cached for JVM lifetime
+    // - May slightly increase startup time
+    // - No runtime overhead for module checks
+
+    // Benefits:
+    // - Smaller runtime images (faster startup, less memory)
+    // - Class loading optimizations
+    // - Ahead-of-time compilation benefits (GraalVM)
+
+    // Measure startup time
+    var start = ProcessHandle.current().info().startInstant();
+    var now = java.time.Instant.now();
+    start.ifPresent(s -> 
+        println("Startup time: " + 
+            java.time.Duration.between(s, now).toMillis() + "ms"));
+}
+```
+
+The module system adds minimal overhead. Resolution happens once at startup  
+and results are cached. The main performance benefits come from custom  
+runtime images—smaller images load faster and use less memory. The explicit  
+dependency graph also enables better class loading optimizations.  
+
+
+## Module annotations  
+
+Use annotations for module-level metadata.  
+
+```java
+// module-info.java
+@Deprecated(since = "2.0", forRemoval = true)
+module com.example.legacy {
+    exports com.example.legacy;
+}
+```
+
+```java
+void main() {
+
+    var module = ModuleLayer.boot()
+        .findModule("java.rmi")
+        .orElseThrow();
+
+    // Check for deprecation
+    if (module.isAnnotationPresent(Deprecated.class)) {
+        var deprecated = module.getAnnotation(Deprecated.class);
+        println(module.getName() + " is deprecated");
+        println("  Since: " + deprecated.since());
+        println("  For removal: " + deprecated.forRemoval());
+    }
+}
+```
+
+Modules can be annotated with `@Deprecated` to signal they will be removed  
+in future versions. This annotation appears in documentation and generates  
+warnings when the module is used. Other annotations may be used by frameworks  
+or tools but have no effect on the module system itself.  
+
+
+## Conclusion  
+
+The Java Platform Module System represents a significant evolution in Java's  
+architecture. By introducing strong encapsulation and explicit dependencies,  
+JPMS enables:  
+
+- **Better maintainability**: Clear module boundaries make codebases easier  
+  to understand and modify  
+- **Improved security**: Internal APIs are hidden by default, reducing attack  
+  surface  
+- **Smaller deployments**: Custom runtime images contain only required modules  
+- **Reliable configuration**: Dependency issues are caught at startup rather  
+  than causing runtime errors  
+- **Scalable development**: Large applications can be decomposed into  
+  well-defined modules with explicit interfaces  
+
+While migration requires effort, especially for applications using internal  
+APIs or reflection-heavy frameworks, the long-term benefits justify the  
+investment. Start with `jdeps` analysis, modularize incrementally, and design  
+new code with modularity in mind.  
+
+The module system works best when combined with good software engineering  
+practices: clear API boundaries, minimal dependencies, and separation of  
+concerns. Embrace modules as a tool for better software design, not just a  
+JVM feature to adopt.  
diff --git a/net/README.md b/net/README.md
new file mode 100644
index 00000000..d71eb126
--- /dev/null
+++ b/net/README.md
@@ -0,0 +1 @@
+# Java NET
diff --git a/net/downloadimage/DownloadImage.java b/net/downloadimage/DownloadImage.java
deleted file mode 100644
index a6613736..00000000
--- a/net/downloadimage/DownloadImage.java
+++ /dev/null
@@ -1,28 +0,0 @@
-package com.zetcode;
-
-import java.io.FileOutputStream;
-import java.io.IOException;
-import java.net.URL;
-
-public class DownloadImage {
-
-    public static void main(String[] args) throws IOException {
-
-        var imageUrl = "http://webcode.me/favicon.ico";
-        var destinationFile = "favicon.ico";
-
-        var url = new URL(imageUrl);
-
-        try (var is = url.openStream();
-             var fos = new FileOutputStream(destinationFile)) {
-
-            byte[] buf = new byte[1024];
-            int noOfBytes;
-
-            while ((noOfBytes = is.read(buf)) != -1) {
-
-                fos.write(buf, 0, noOfBytes);
-            }
-        }
-    }
-}
diff --git a/net/downloadimage/DownloadImageFiles.java b/net/downloadimage/DownloadImageFiles.java
deleted file mode 100644
index f7c93e16..00000000
--- a/net/downloadimage/DownloadImageFiles.java
+++ /dev/null
@@ -1,20 +0,0 @@
-package com.zetcode;
-
-import java.io.IOException;
-import java.io.InputStream;
-import java.net.URL;
-import java.nio.file.Files;
-import java.nio.file.Paths;
-
-public class DownloadImageFiles {
-
-    public static void main(String[] args) throws IOException {
-
-        var urlFile = "http://httpbin.org/image/jpeg";
-
-        try(InputStream in = new URL(urlFile).openStream()){
-
-            Files.copy(in, Paths.get("jackal.jpg"));
-        }
-    }
-}
diff --git a/net/uri.md b/net/uri.md
new file mode 100644
index 00000000..bb1bc5cc
--- /dev/null
+++ b/net/uri.md
@@ -0,0 +1,166 @@
+# URI/URL
+
+The `java.net.URI` is old-school code. The `HttpClient` is the modern solution.  
+
+
+## openStream
+
+```java
+import java.net.URL;
+import java.net.URI;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+
+void main() throws Exception {
+
+    URL url = URI.create("https://webcode.me").toURL();
+
+    try (InputStream is = url.openStream()) {
+
+        byte[] data = is.readAllBytes();
+        String msg = new String(data, StandardCharsets.UTF_8);
+
+        System.out.println(msg);
+    }
+}
+```
+
+## HttpURLConnection
+
+Set timeouts.  
+
+```java
+import java.net.URL;
+import java.net.URI;
+import java.net.HttpURLConnection;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+
+void main() throws Exception {
+
+    URL url = URI.create("https://webcode.me").toURL();
+
+    HttpURLConnection con = (HttpURLConnection) url.openConnection();
+    con.setConnectTimeout(5000);
+    con.setReadTimeout(5000);
+    con.setRequestMethod("GET");
+
+    con.connect();
+
+    try (InputStream is = con.getInputStream()) {
+
+        byte[] data = is.readAllBytes();
+        String msg = new String(data, StandardCharsets.UTF_8);
+
+        System.out.println(msg);
+    }
+}
+```
+
+## HEAD request
+
+```java
+import java.net.URL;
+import java.net.URI;
+import java.net.HttpURLConnection;
+import java.util.List;
+import java.util.Map;
+
+void main() throws Exception {
+
+    URL url = URI.create("https://webcode.me").toURL();
+
+    HttpURLConnection con = (HttpURLConnection) url.openConnection();
+    con.setRequestMethod("HEAD");
+    con.connect();
+
+    Map<String, List<String>> fields = con.getHeaderFields();
+
+    fields.forEach((k, vals) -> {
+
+        System.out.println(k);
+
+        for (var e: vals) {
+            System.out.println(e);
+        }
+
+        System.out.println();
+    });
+}
+```
+
+## Download image
+
+```java
+import java.io.FileOutputStream;
+import java.io.IOException;
+import java.net.URI;
+
+void main(String[] args) throws IOException {
+
+    var imageUrl = "https://something.com/favicon.ico";
+    var destinationFile = "favicon.ico";
+
+    var url = URI.create(imageUrl).toURL();
+
+    try (var is = url.openStream();
+            var fos = new FileOutputStream(destinationFile)) {
+
+        byte[] buf = new byte[1024];
+        int noOfBytes;
+
+        while ((noOfBytes = is.read(buf)) != -1) {
+
+            fos.write(buf, 0, noOfBytes);
+        }
+    }
+}
+```
+
+---
+
+```java
+import java.io.IOException;
+import java.io.InputStream;
+import java.net.URI;
+import java.nio.file.Files;
+import java.nio.file.Paths;
+
+void main(String[] args) throws IOException {
+
+    var urlFile = "http://httpbin.org/image/jpeg";
+
+    try (InputStream in = URI.create(urlFile).toURL().openStream()) {
+
+        Files.copy(in, Paths.get("jackal.jpg"));
+    }
+}
+```
+
+## InputStreamReader
+
+```java
+import java.net.URL;
+import java.net.URI;
+import java.io.IOException;
+import java.io.InputStreamReader;
+import java.io.BufferedReader;
+import java.nio.charset.StandardCharsets;
+
+void main() throws IOException {
+
+    URL url = URI.create("https://webcode.me").toURL();
+
+    try (var isr = new InputStreamReader(url.openStream(), StandardCharsets.UTF_8);
+            var br = new BufferedReader(isr)) {
+
+        String line;
+        while ((line = br.readLine()) != null) {
+
+            System.out.println(line);
+        }
+    }
+}
+```
+
+
diff --git a/nio-async.md b/nio-async.md
new file mode 100644
index 00000000..8b137891
--- /dev/null
+++ b/nio-async.md
@@ -0,0 +1 @@
+
diff --git a/optional.md b/optional.md
new file mode 100644
index 00000000..d6ba8787
--- /dev/null
+++ b/optional.md
@@ -0,0 +1,252 @@
+# Optional 
+
+`Optional` is a container object introduced which is used to represent a value  
+that may or may not be present. An `Optional` object can either contain a  
+non-null value (in which case it is considered present), or it can contain no  
+value at all (in which case it is considered empty).  
+
+The advantages of `Optional`:
+
+- *Null Safety*: Optional forces you to handle the case where the value is  
+  absent, reducing the risk of `NullPointerException`. It provides a clear and  
+  explicit way to signal that a method might not always return a value.  
+
+- *Improved Code Readability*: Optional can help in writing a neat code without   
+  using too many null checks. By using `Optional`, we can specify alternate  
+  values to return or alternate code to run. This makes the code more readable  
+  because the facts which were hidden are now visible to the developer.  
+
+- *Fluent Functional Programming Style*: We can use the `Optional` class to wrap  
+  our data and avoid the classical null checks and some of the try-catch  
+  blocks3. As a result, we’ll be able to chain method calls and have more  
+  fluent, functional code.  
+
+- *API Design*: Optional helps to create clear and robust APIs. It makes it  
+  explicit to the API user that a returned value can be null, and forces them to  
+  handle that case.  
+
+
+
+## Example 
+
+```java
+import java.util.Arrays;
+import java.util.Optional;
+import java.util.Random;
+
+void main() {
+
+    var words = Arrays.asList("rock", null, "mountain",
+            null, "falcon", "sky");
+
+    for (int i = 0; i < 5; i++) {
+
+        Optional<String> word = Optional.ofNullable(words.get(
+                new Random().nextInt(words.size())));
+        word.ifPresent(System.out::println);
+    }
+}
+```
+
+---
+
+
+```java
+import java.util.Optional;
+
+void main() {
+
+    if (getNullMessage().isPresent()) {
+        System.out.println(getNullMessage().get());
+    } else {
+        System.out.println("n/a");
+    }
+
+    if (getEmptyMessage().isPresent()) {
+        System.out.println(getEmptyMessage().get());
+    } else {
+        System.out.println("n/a");
+    }
+
+    if (getCustomMessage().isPresent()) {
+        System.out.println(getCustomMessage().get());
+    } else {
+        System.out.println("n/a");
+    }
+}
+
+Optional<String> getNullMessage() {
+    return Optional.ofNullable(null);
+}
+
+Optional<String> getEmptyMessage() {
+    return Optional.empty();
+}
+
+Optional<String> getCustomMessage() {
+    return Optional.of("Hello there!");
+}
+```
+
+## flatMap
+
+If the result is already an `Optional` `flatMap` does not wrap it within an
+additional `Optional`.
+
+```java
+import java.util.Arrays;
+import java.util.Optional;
+import java.util.function.Function;
+
+void main() {
+
+    Function<String, Optional<String>> upperCase = s -> Optional.of(s.toUpperCase());
+
+    var words = Arrays.asList("rock", null, "mountain",
+            null, "falcon", "sky");
+
+    for (int i = 0; i < 5; i++) {
+
+        Optional<String> word = Optional.ofNullable(words.get(i));
+
+        var res = word.flatMap(upperCase);
+        res.ifPresent(System.out::println);
+    }
+}
+```
+
+## isEmpty
+
+```java
+import java.util.Arrays;
+import java.util.Optional;
+
+void main() {
+
+    var words = Arrays.asList("rock", null, "mountain",
+            null, "falcon", "sky");
+
+    for (int i = 0; i < 5; i++) {
+
+        Optional<String> word = Optional.ofNullable(words.get(i));
+
+        if (word.isEmpty()) {
+
+            System.out.println("n/a");
+        }
+
+        word.ifPresent(System.out::println);
+    }
+}
+```
+
+## orElse
+
+```java
+import java.util.Optional;
+
+void main() {
+
+    Optional<String> word1 = Optional.of("sky");
+    Optional<String> word2 = Optional.empty();
+
+    System.out.println(word1.orElse("n/a"));
+    System.out.println(word2.orElse("n/a"));
+}
+```
+
+
+## ifPresentOrElse
+
+```java
+import java.util.Arrays;
+import java.util.Optional;
+
+void main() {
+
+    var words = Arrays.asList("rock", null, "mountain",
+            null, "falcon", "sky");
+
+    for (String val : words) {
+
+        Optional<String> word = Optional.ofNullable(val);
+
+        word.ifPresentOrElse(System.out::println,
+                () -> System.out.println("Invalid value"));
+    }
+}
+```
+
+## ifPresent & get
+
+```java
+import java.util.Arrays;
+import java.util.Optional;
+
+void main() {
+
+    var words = Arrays.asList("rock", null, "mountain",
+            null, "falcon", "sky");
+
+    for (String s : words) {
+
+        Optional<String> word = Optional.ofNullable(s);
+
+        if (word.isPresent()) {
+
+            System.out.println(word.get());
+        } else {
+
+            System.out.println("Invalid value");
+        }
+    }
+}
+```
+
+```java
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;    
+import java.util.Optional;    
+
+void main() {
+
+    List<String> words = new ArrayList<>();
+    words.add("sky"); 
+    words.add(null); 
+    words.add("rock"); 
+    words.add("atom"); 
+
+    var res4 = getRandomElement(words);
+    res4.ifPresentOrElse((e) -> {System.out.println(e.toUpperCase());}, () -> {System.out.println("N/A");});
+}
+
+
+
+public <T> Optional<T> getRandomElement(List<T> list) {
+    Collections.shuffle(list);
+    return Optional.ofNullable(list.get(0));
+}
+```
+
+```java
+import java.util.Optional;
+import java.util.function.Function;
+
+// if the result is already an Optional flatMap
+// does not wrap it within an additional Optional
+
+void main() {
+
+    Function<String, Optional<String>> upperCase = s -> (s == null) ? Optional.empty() : Optional.of(s.toUpperCase());
+
+    Optional<String> word = Optional.of("falcon");
+
+    Optional<Optional<String>> opt1 = word.map(upperCase);
+    Optional<String> opt2 = word.flatMap(upperCase);
+
+    opt1.ifPresent(s -> s.ifPresent(System.out::println));
+    opt2.ifPresentOrElse(System.out::println,
+            () -> System.out.println("Invalid value"));
+}
+```
diff --git a/optional/OptionalFlatMap.java b/optional/OptionalFlatMap.java
deleted file mode 100644
index f905fc98..00000000
--- a/optional/OptionalFlatMap.java
+++ /dev/null
@@ -1,27 +0,0 @@
-package com.zetcode;
-
-import java.util.Arrays;
-import java.util.Optional;
-import java.util.function.Function;
-
-// if the result is already an Optional flatMap
-// does not wrap it within an additional Optional
-
-public class OptionalFlatMap {
-
-    public static void main(String[] args) {
-
-        Function<String, Optional<String>> upperCase = s -> Optional.of(s.toUpperCase());
-
-        var words = Arrays.asList("rock", null, "mountain",
-                null, "falcon", "sky");
-
-        for (int i = 0; i < 5; i++) {
-
-            Optional<String> word = Optional.ofNullable(words.get(i));
-
-            var res = word.flatMap(upperCase);
-            res.ifPresent(System.out::println);
-        }
-    }
-}
diff --git a/optional/OptionalIfEmpty.java b/optional/OptionalIfEmpty.java
deleted file mode 100644
index 9a1a6147..00000000
--- a/optional/OptionalIfEmpty.java
+++ /dev/null
@@ -1,25 +0,0 @@
-package com.zetcode;
-
-import java.util.Arrays;
-import java.util.Optional;
-
-public class OptionalIfEmpty {
-
-    public static void main(String[] args) {
-
-        var words = Arrays.asList("rock", null, "mountain",
-                null, "falcon", "sky");
-
-        for (int i = 0; i < 5; i++) {
-
-            Optional<String> word = Optional.ofNullable(words.get(i));
-
-            if (word.isEmpty()) {
-
-                System.out.println("n/a");
-            }
-
-            word.ifPresent(System.out::println);
-        }
-    }
-}
diff --git a/optional/OptionalIfPresentOrElse.java b/optional/OptionalIfPresentOrElse.java
deleted file mode 100644
index 6f0443f9..00000000
--- a/optional/OptionalIfPresentOrElse.java
+++ /dev/null
@@ -1,21 +0,0 @@
-package com.zetcode;
-
-import java.util.Arrays;
-import java.util.Optional;
-
-public class OptionalIfPresentOrElse {
-
-    public static void main(String[] args) {
-
-        var words = Arrays.asList("rock", null, "mountain",
-                null, "falcon", "sky");
-
-        for (String val : words) {
-
-            Optional<String> word = Optional.ofNullable(val);
-
-            word.ifPresentOrElse(System.out::println,
-                    () -> System.out.println("Invalid value"));
-        }
-    }
-}
diff --git a/optional/OptionalIsPresentGet.java b/optional/OptionalIsPresentGet.java
deleted file mode 100644
index b0579a45..00000000
--- a/optional/OptionalIsPresentGet.java
+++ /dev/null
@@ -1,26 +0,0 @@
-package com.zetcode;
-
-import java.util.Arrays;
-import java.util.Optional;
-
-public class OptionalIsPresentGet {
-
-    public static void main(String[] args) {
-
-        var words = Arrays.asList("rock", null, "mountain",
-                null, "falcon", "sky");
-
-        for (String s : words) {
-
-            Optional<String> word = Optional.ofNullable(s);
-
-            if (word.isPresent()) {
-
-                System.out.println(word.get());
-            } else {
-
-                System.out.println("Invalid value");
-            }
-        }
-    }
-}
diff --git a/optional/OptionalMapOf.java b/optional/OptionalMapOf.java
deleted file mode 100644
index 52042377..00000000
--- a/optional/OptionalMapOf.java
+++ /dev/null
@@ -1,25 +0,0 @@
-package com.zetcode;
-
-import java.util.Optional;
-import java.util.function.Function;
-
-// if the result is already an Optional flatMap
-// does not wrap it within an additional Optional
-
-public class OptionalMapOf {
-
-    public static void main(String[] args) {
-
-        Function<String, Optional<String>> upperCase
-                = s -> (s == null) ? Optional.empty() : Optional.of(s.toUpperCase());
-
-        Optional<String> word = Optional.of("falcon");
-
-        Optional<Optional<String>> opt1 = word.map(upperCase);
-        Optional<String> opt2 = word.flatMap(upperCase);
-
-        opt1.ifPresent(s -> s.ifPresent(System.out::println));
-        opt2.ifPresentOrElse(System.out::println,
-                () -> System.out.println("Invalid value"));
-    }
-}
diff --git a/optional/OptionalOrElse.java b/optional/OptionalOrElse.java
deleted file mode 100644
index d6966d3b..00000000
--- a/optional/OptionalOrElse.java
+++ /dev/null
@@ -1,15 +0,0 @@
-package com.zetcode;
-
-import java.util.Optional;
-
-public class OptionalOrElse {
-
-    public static void main(String[] args) {
-
-        Optional<String> word1 = Optional.of("sky");
-        Optional<String> word2 = Optional.empty();
-
-        System.out.println(word1.orElse("n/a"));
-        System.out.println(word2.orElse("n/a"));
-    }
-}
diff --git a/optional/OptionalSimple.java b/optional/OptionalSimple.java
deleted file mode 100644
index ab51e7ec..00000000
--- a/optional/OptionalSimple.java
+++ /dev/null
@@ -1,21 +0,0 @@
-package com.zetcode;
-
-import java.util.Arrays;
-import java.util.Optional;
-import java.util.Random;
-
-public class OptionalSimple {
-
-    public static void main(String[] args) {
-
-        var words = Arrays.asList("rock", null, "mountain",
-                null, "falcon", "sky");
-
-        for (int i = 0; i < 5; i++) {
-
-            Optional<String> word = Optional.ofNullable(words.get(
-                    new Random().nextInt(words.size())));
-            word.ifPresent(System.out::println);
-        }
-    }
-}
diff --git a/optional/OptionalsEx.java b/optional/OptionalsEx.java
deleted file mode 100644
index 78163cfd..00000000
--- a/optional/OptionalsEx.java
+++ /dev/null
@@ -1,39 +0,0 @@
-package com.zetcode;
-
-import java.util.Optional;
-
-public class OptionalsEx {
-
-    public static void main(String[] args) {
-
-        if (getNullMessage().isPresent()) {
-            System.out.println(getNullMessage().get());
-        } else {
-            System.out.println("n/a");
-        }
-
-        if (getEmptyMessage().isPresent()) {
-            System.out.println(getEmptyMessage().get());
-        } else {
-            System.out.println("n/a");
-        }
-
-        if (getCustomMessage().isPresent()) {
-            System.out.println(getCustomMessage().get());
-        } else {
-            System.out.println("n/a");
-        }
-    }
-    private static Optional<String> getNullMessage() {
-        return Optional.ofNullable(null);
-    }
-
-    private static Optional<String> getEmptyMessage() {
-        return Optional.empty();
-    }
-
-    private static Optional<String> getCustomMessage() {
-        return Optional.of("Hello there!");
-    }
-}
-
diff --git a/pitfalls.md b/pitfalls.md
new file mode 100644
index 00000000..e69de29b
diff --git a/pitfalls/Associativity.java b/pitfalls/Associativity.java
index b81d3d06..ff7be01e 100644
--- a/pitfalls/Associativity.java
+++ b/pitfalls/Associativity.java
@@ -1,19 +1,15 @@
-package com.zetcode;
+void main() {
 
-public class Associativity {
+    // left-to-right associativity
+    int val = 9 / 3 * 3;
 
-    public static void main(String[] args) {
+    IO.println(val);
 
-        // left-to-right associativity
-        int val = 9 / 3 * 3;
+    int val2 = 0;
 
-        System.out.println(val);
+    // right-to-left associativity
+    val2 *= 3 + 1;
 
-        int val2 = 0;
-
-        // right-to-left associativity
-        val2 *= 3 + 1;
-
-        System.out.println(val2);
-    }
+    IO.println(val2);
 }
+
diff --git a/pitfalls/IncrementOperator.java b/pitfalls/IncrementOperator.java
index 15bc30f3..aeb71ae7 100644
--- a/pitfalls/IncrementOperator.java
+++ b/pitfalls/IncrementOperator.java
@@ -1,20 +1,15 @@
-package com.zetcode;
-
 // there is a subtle difference between the 
 // prefix and suffix increment operators
 
-public class IncrementOperator {
-
-    public static void main(String[] args) {
+void main() {
 
-        int num = 0;
+    int num = 0;
 
-        num = num++;
+    num = num++;
 
-        System.out.println(num);
+    IO.println(num);
 
-        num = ++num;
-        
-        System.out.println(num);
-    }
+    num = ++num;
+    
+    IO.println(num);
 }
diff --git a/pitfalls/IntegerEqual.java b/pitfalls/IntegerEqual.java
index d6ba8f07..c4c045d4 100644
--- a/pitfalls/IntegerEqual.java
+++ b/pitfalls/IntegerEqual.java
@@ -1,20 +1,16 @@
-package com.zetcode;
-
 // The == operator compares object references and equals()
 // object values. Java internally caches integers 
 // from -128 to +127, so comparing them with == 'works'.
 // we should use equals
 
-public class IntegerEqual {
-
-    public static void main(String[] args) {
+void main() {
 
-        Integer a = 127;
-        Integer b = 127;
-        Integer c = 128;
-        Integer d = 128;
+    Integer a = 127;
+    Integer b = 127;
+    Integer c = 128;
+    Integer d = 128;
 
-        System.out.println(a == b);
-        System.out.println(c == d);
-    }
+    IO.println(a == b);
+    IO.println(c == d);
 }
+
diff --git a/pitfalls/Promotion.java b/pitfalls/Promotion.java
new file mode 100644
index 00000000..775bd722
--- /dev/null
+++ b/pitfalls/Promotion.java
@@ -0,0 +1,10 @@
+void main() {
+
+  byte x = 10;
+  byte y = 20;
+
+  var res = (Object) (x + y);
+
+  IO.println(res);
+  IO.println(res.getClass().getName());
+}
diff --git a/pitfalls/StringEqual.java b/pitfalls/StringEqual.java
index 2f571a91..a9392d58 100644
--- a/pitfalls/StringEqual.java
+++ b/pitfalls/StringEqual.java
@@ -1,22 +1,14 @@
-package com.zetcode;
-
-import java.util.Arrays;
-
 // the program throws a NullPointerException
 // we should swap the sides: "rock".equals(word)
+void main() {
 
-public class StringEqual {
-
-    public static void main(String[] args) {
-
-        var words = Arrays.asList("wood", "forest", "falcon", null, "sky", "rock");
+    var words = Arrays.asList("wood", "forest", "falcon", null, "sky", "rock");
 
-        for (var word : words) {
+    for (var word : words) {
 
-            if (word.equals("rock")) {
+        if (word.equals("rock")) {
 
-                System.out.println("The list contains rock");
-            }
+            System.out.println("The list contains rock");
         }
     }
 }
diff --git a/resteasy/uploadfile/pom.xml b/resteasy/uploadfile/pom.xml
index 641cd8c7..18b54b64 100644
--- a/resteasy/uploadfile/pom.xml
+++ b/resteasy/uploadfile/pom.xml
@@ -31,7 +31,7 @@
         <dependency>
             <groupId>org.jboss.resteasy</groupId>
             <artifactId>resteasy-multipart-provider</artifactId>
-            <version>4.2.0.Final</version>
+            <version>4.7.8.Final</version>
         </dependency>
 
         <dependency>
diff --git a/secure-coding.md b/secure-coding.md
new file mode 100644
index 00000000..8b137891
--- /dev/null
+++ b/secure-coding.md
@@ -0,0 +1 @@
+
diff --git a/strings/BytesToString.java b/strings/BytesToString.java
deleted file mode 100644
index 3cd3381e..00000000
--- a/strings/BytesToString.java
+++ /dev/null
@@ -1,16 +0,0 @@
-package com.zetcode;
-
-import java.util.Base64;
-
-public class BytesToString {
-
-    public static void main(String[] args) {
-
-        byte[] data = {(byte) 0x47, (byte) 0x6f, (byte) 0x6c, (byte) 0x64,
-                (byte) 0x65, (byte) 0x6e, (byte) 0x20, (byte) 0x65,
-                (byte) 0x61, (byte) 0x67, (byte) 0x6c, (byte) 0x65};
-
-        var text = new String(data);
-        System.out.println(text);
-    }
-}
diff --git a/strings/FormatFlags.java b/strings/FormatFlags.java
deleted file mode 100644
index 0330704a..00000000
--- a/strings/FormatFlags.java
+++ /dev/null
@@ -1,14 +0,0 @@
-package com.zetcode;
-
-public class FormatFlags {
-
-    public static void main(String[] args) {
-        
-        System.out.format("%+d%n", 553);
-        System.out.format("%010d%n", 553);
-        System.out.format("%10d%n", 553);
-        System.out.format("%-10d%n", 553);
-        System.out.format("%d%n", -553);
-        System.out.format("%(d%n", -553); 
-    }
-}
diff --git a/strings/FormatNumbers.java b/strings/FormatNumbers.java
deleted file mode 100644
index 3874cd74..00000000
--- a/strings/FormatNumbers.java
+++ /dev/null
@@ -1,13 +0,0 @@
-package com.zetcode;
-
-public class FormatNumbers {
-
-    public static void main(String[] args) {
-        
-        System.out.format("%d%n", 12263);
-        System.out.format("%o%n", 12263);
-        System.out.format("%x%n", 12263);
-        System.out.format("%e%n", 0.03452342263);
-        System.out.format("%d%%%n", 45);    
-    }
-}
diff --git a/strings/MultilineString.java b/strings/MultilineString.java
deleted file mode 100644
index af92e3f6..00000000
--- a/strings/MultilineString.java
+++ /dev/null
@@ -1,15 +0,0 @@
-package com.zetcode;
-
-public class MultilineString {
-
-    static String lyrics = "I cheated myself\n" +
-"like I knew I would\n" +
-"I told ya, I was trouble\n" +
-"you know that I'm no good";
-    
-    
-    public static void main(String[] args) {
-        
-        System.out.println(lyrics);
-    }
-}
diff --git a/strings/PatternSplitEx.java b/strings/PatternSplitEx.java
deleted file mode 100644
index a76e6ecd..00000000
--- a/strings/PatternSplitEx.java
+++ /dev/null
@@ -1,18 +0,0 @@
-package com.zetcode;
-
-import java.util.regex.Pattern;
-import java.util.stream.Collectors;
-
-public class PatternSplitEx {
-
-    public static void main(String[] args) {
-
-        var phoneNumber = "202-555-0154";
-
-        var output = Pattern.compile("-")
-                .splitAsStream(phoneNumber)
-                .collect(Collectors.toList());
-
-        output.forEach(System.out::println);
-    }
-}
diff --git a/strings/Pyramid.java b/strings/Pyramid.java
deleted file mode 100644
index 91f88b7f..00000000
--- a/strings/Pyramid.java
+++ /dev/null
@@ -1,17 +0,0 @@
-package com.zetcode;
-
-public class Pyramid {
-
-    public static void main(String[] args) {
-
-        String val = "0";
-        String empty = " ";
-
-        int len = 30;
-
-        for (int i = 1; i < len; i += 2) {
-
-            System.out.printf("%s%s%n", empty.repeat(len-i / 2), val.repeat(i));
-        }
-    }
-}
diff --git a/strings/README.md b/strings/README.md
new file mode 100644
index 00000000..02fb3d71
--- /dev/null
+++ b/strings/README.md
@@ -0,0 +1,243 @@
+# Strings 
+
+## Text blocks
+
+```java
+void main() {
+
+    String name = "John Doe";
+    int age = 34;
+    String occupation = "gardener";
+
+    var msg = """
+            %s is %d years old
+            he is an %s
+            """.formatted(name, age, occupation);
+
+    System.out.println(msg);
+
+}
+```
+
+## Pyramid
+
+```java
+void main() {
+
+    String val = "0";
+    String empty = " ";
+
+    int len = 30;
+
+    for (int i = 1; i < len; i += 2) {
+
+        System.out.printf("%s%s%n", empty.repeat(len - i / 2), val.repeat(i));
+    }
+}
+```
+
+```bash
+$ java Main.java
+
+                              0
+                             000
+                            00000
+                           0000000
+                          000000000
+                         00000000000
+                        0000000000000
+                       000000000000000
+                      00000000000000000
+                     0000000000000000000
+                    000000000000000000000
+                   00000000000000000000000
+                  0000000000000000000000000
+                 000000000000000000000000000
+                00000000000000000000000000000
+```
+
+## Multi-line strings
+
+They can be expressed with text blocks, which were standardized in Java 15. 
+
+```java
+String lyrics = "I cheated myself\n" +
+        "like I knew I would\n" +
+        "I told ya, I was trouble\n" +
+        "you know that I'm no good";
+
+String lyrics2 = """
+        I cheated myself
+        like I knew I would
+        I told ya, I was trouble
+        you know that I'm no good""";
+
+void main() {
+
+    System.out.println(lyrics);
+    System.out.println("--------------------------");
+    System.out.println(lyrics2);
+}
+```
+
+## Blank
+
+The string is blank if it is empty or contains only white space. 
+
+```java
+import java.util.List;
+
+void main() {
+
+    var data = List.of("sky", "\n\n", "  ", "blue", "\t\t", "", "sky");
+
+    for (int i = 0; i < data.size(); i++) {
+
+        var e = data.get(i);
+
+        if (e.isBlank()) {
+            System.out.printf("element with index %d is blank%n", i);
+        } else {
+
+            System.out.println(data.get(i));
+        }
+    }
+}
+```
+
+## Upper & lower 
+
+```java
+void main() {
+
+    var word1 = "Cherry";
+
+    var u_word1 = word1.toUpperCase();
+    var l_word1 = u_word1.toLowerCase();
+
+    System.out.println(u_word1);
+    System.out.println(l_word1);
+
+    var word2 = "Čerešňa";
+
+    var u_word2 = word2.toUpperCase();
+    var l_word2 = u_word2.toLowerCase();
+
+    System.out.println(u_word2);
+    System.out.println(l_word2);
+}
+```
+
+## Format numbers 
+
+```java
+void main() {
+
+    System.out.format("%d%n", 12263);
+    System.out.format("%o%n", 12263);
+    System.out.format("%x%n", 12263);
+    System.out.format("%e%n", 0.03452342263);
+    System.out.format("%d%%%n", 45);   
+}
+```
+
+## Pattern split 
+
+```java
+import java.util.regex.Pattern;
+import java.util.stream.Collectors;
+
+void main() {
+
+    var phoneNumber = "202-555-0154";
+
+    var output = Pattern.compile("-")
+            .splitAsStream(phoneNumber)
+            .collect(Collectors.toList());
+
+    output.forEach(System.out::println);
+}
+```
+
+---
+
+```java
+import java.util.Arrays;
+
+void main() {
+
+    var input = " wood, falcon\t, sky, forest\n";
+    var output = input.trim().split("\\s*,\\s*");
+
+    Arrays.stream(output).forEach(System.out::println);
+}
+```
+
+## Split by dot 
+
+```java
+import java.util.Arrays;
+import java.util.regex.Pattern;
+
+void main() {
+
+    var address = "127.0.0.1";
+
+    // String[] output = address.split("\\.");
+    String[] output = address.split(Pattern.quote("."));
+
+    Arrays.stream(output).forEach(part -> System.out.println(part));
+}
+```
+
+## Format flags
+
+```java
+void main() {
+
+    System.out.format("%+d%n", 553);
+    System.out.format("%010d%n", 553);
+    System.out.format("%10d%n", 553);
+    System.out.format("%-10d%n", 553);
+    System.out.format("%d%n", -553);
+    System.out.format("%(d%n", -553); 
+}
+```
+
+## Bytes and strings
+
+```java
+import java.nio.charset.StandardCharsets;
+import java.util.Base64;
+
+void main() {
+
+
+    byte[] data = { (byte) 0xc4, (byte) 0x8d, (byte) 0x65, (byte) 0x72,
+            (byte) 0x65, (byte) 0xc5, (byte) 0xa1, (byte) 0xc5, (byte) 0x88, (byte) 0x61 };
+
+    var text = new String(data, StandardCharsets.UTF_8);
+    System.out.println(text);
+
+
+    String str = "čerešňa";
+    byte[] bytes = str.getBytes(StandardCharsets.UTF_8);
+    var hexString = new StringBuilder();
+
+    for (byte b : bytes) {
+
+        String hex = Integer.toHexString(0xff & b);
+        
+        if (hex.length() == 1) {
+            hexString.append('0');
+        }
+
+        hexString.append(STR."0x\{hex}, ");
+    }
+
+    int len = hexString.length();
+    hexString.delete(len-2, len-1); // delete last space and comma
+
+    System.out.println(hexString.toString());
+}
+```
diff --git a/strings/SplitStringTrimEx.java b/strings/SplitStringTrimEx.java
deleted file mode 100644
index 108410a6..00000000
--- a/strings/SplitStringTrimEx.java
+++ /dev/null
@@ -1,15 +0,0 @@
-package com.zetcode;
-
-import java.util.Arrays;
-
-public class SplitStringTrimEx {
-
-    public static void main(String[] args) {
-
-        var input = " wood, falcon\t, sky, forest\n";
-
-        var output = input.trim().split("\\s*,\\s*");
-
-        Arrays.stream(output).forEach(System.out::println);
-    }
-}
diff --git a/strings/StringBlank.java b/strings/StringBlank.java
deleted file mode 100644
index 3b181a34..00000000
--- a/strings/StringBlank.java
+++ /dev/null
@@ -1,23 +0,0 @@
-package com.zetcode;
-
-import java.util.List;
-
-public class StringBlank {
-
-    public static void main(String[] args) {
-
-        var data = List.of("sky", "\n\n", "  ", "blue", "\t\t", "", "sky");
-
-        for (int i=0; i<data.size(); i++) {
-
-            var e = data.get(i);
-
-            if (e.isBlank()) {
-                System.out.printf("element with index %d is blank%n", i);
-            } else {
-
-                System.out.println(data.get(i));
-            }
-        }
-    }
-}
diff --git a/strings/StringSplitDotEx.java b/strings/StringSplitDotEx.java
deleted file mode 100644
index febfc907..00000000
--- a/strings/StringSplitDotEx.java
+++ /dev/null
@@ -1,17 +0,0 @@
-package com.zetcode;
-
-import java.util.Arrays;
-import java.util.regex.Pattern;
-
-public class StringSplitDotEx {
-
-    public static void main(String[] args) {
-
-        var address = "127.0.0.1";
-
-//        String[] output = address.split("\\.");
-        String[] output = address.split(Pattern.quote("."));
-
-        Arrays.stream(output).forEach(part -> System.out.println(part));
-    }
-}
diff --git a/strings/StringSplitEx.java b/strings/StringSplitEx.java
deleted file mode 100644
index 46acd716..00000000
--- a/strings/StringSplitEx.java
+++ /dev/null
@@ -1,15 +0,0 @@
-package com.zetcode;
-
-import java.util.Arrays;
-
-public class StringSplitEx {
-
-    public static void main(String[] args) {
-
-        var phoneNumber = "202-555-0154";
-
-        String[] output = phoneNumber.split("-");
-
-        Arrays.stream(output).forEach(part -> System.out.println(part));
-    }
-}
diff --git a/strings/StringUpperLower.java b/strings/StringUpperLower.java
deleted file mode 100644
index 760ac8e4..00000000
--- a/strings/StringUpperLower.java
+++ /dev/null
@@ -1,23 +0,0 @@
-package com.zetcode;
-
-public class StringUpperLower {
-
-    public static void main(String[] args) {
-
-        var word1 = "Cherry";
-
-        var u_word1 = word1.toUpperCase();
-        var l_word1 = u_word1.toLowerCase();
-
-        System.out.println(u_word1);
-        System.out.println(l_word1);
-
-        var word2 = "Čerešňa";
-
-        var u_word2 = word2.toUpperCase();
-        var l_word2 = u_word2.toLowerCase();
-
-        System.out.println(u_word2);
-        System.out.println(l_word2);
-    }
-}
diff --git a/sync-primitives.md b/sync-primitives.md
new file mode 100644
index 00000000..e69de29b
diff --git a/tasks/fizz_buzz.md b/tasks/fizz_buzz.md
new file mode 100644
index 00000000..47a6f9ac
--- /dev/null
+++ b/tasks/fizz_buzz.md
@@ -0,0 +1,52 @@
+# FizzBuzz task
+
+FizzBuzz Instructions
+
+- Print numbers from 1 to N (typically N = 100).
+- For numbers divisible by 3, print "Fizz" instead.
+- For numbers divisible by 5, print "Buzz" instead.
+- For numbers divisible by both 3 and 5, print "FizzBuzz".
+- Otherwise, print the number itself.
+
+## Solution 1
+
+Using classic for loop and if/else statements. 
+
+```java
+void main() {
+
+    for (int i = 1; i <= 100; i++) {
+
+        if (i % 3 == 0 && i % 5 == 0) {
+            System.out.println("FizzBuzz");
+        } else if (i % 3 == 0) {
+            System.out.println("Fizz");
+        } else if (i % 5 == 0) {
+            System.out.println("Buzz");
+        } else {
+            System.err.println(i);
+        }
+    }
+}
+```
+
+## Solution 2
+
+Using stream and switch expression. 
+
+```java
+void main() {
+
+    IntStream.range(1, 101).forEach(this::doFizzBuzz);
+}
+
+void doFizzBuzz(int e) {
+
+    switch (e) {
+        case int n when n % 3 == 0 && n % 5 == 0 -> System.out.println("FizzBuzz");
+        case int n when n % 3 == 0 -> System.out.println("Fizz");
+        case int n when n % 5 == 0 -> System.out.println("Buzz");
+        default -> System.out.println(e);
+    }
+}
+```
diff --git a/threadpools-executors.md b/threadpools-executors.md
new file mode 100644
index 00000000..e69de29b
diff --git a/types/enum.md b/types/enum.md
new file mode 100644
index 00000000..e491a361
--- /dev/null
+++ b/types/enum.md
@@ -0,0 +1,237 @@
+# Enum type 
+
+The enum type is built-in Java data type that defines a fixed set of named constants.   
+The set of constants cannot be changed afterwards. Variables having an enum type can  
+be assigned any of the enumerators as a value.
+
+The enum type provides a more robust and readable way to handle constant values compared   
+to using primitive data types like integers. Enemerations enforce type safety by guaranteeing  
+that the variable can only hold one of the predefined values.
+
+We should use enum types any time we need to represent a fixed set of constants. There are   
+many natural enum types such as the planets in our solar system, seasons, or days of week.   
+These are data sets where we know all possible values at compile time.
+
+
+## Simple
+
+```java
+enum Day {
+
+    MONDAY,
+    TUESDAY,
+    WEDNESDAY,
+    THURSDAY,
+    FRIDAY,
+    SATURDAY,
+    SUNDAY
+}
+
+void main() {
+
+    Day day = Day.MONDAY;
+
+    if (day == Day.MONDAY) {
+
+        System.out.println("It is Monday");
+    }
+
+    System.out.println(day);
+
+    for (Day d : Day.values()) {
+
+        System.out.println(d);
+    }
+}
+```
+
+## Custom constant values
+
+```java
+enum Season {
+
+    SPRING(10),
+    SUMMER(20),
+    AUTUMN(30),
+    WINTER(40);
+
+    private int value;
+
+    private Season(int value) {
+        this.value = value;
+    }
+
+    public int getValue() {
+
+        return value;
+    }
+}
+
+void main() {
+
+    for (Season season : Season.values()) {
+
+        System.out.println(STR."\{season} \{season.getValue()}");
+    }
+}
+```
+
+
+## Custom method
+
+```java
+import java.util.Random;
+
+public enum Coin {
+    HEADS,
+    TAILS;
+
+    public static Coin toss() {
+
+        var rand = new Random();
+        int rdx = rand.nextInt(Coin.values().length);
+        return Coin.values()[rdx];
+    }
+}
+
+void main() {
+
+    for (int i = 1; i <= 15; i++) {
+
+        System.out.print(STR."\{Coin.toss()} ");
+    }
+}
+```
+
+## Switch expression
+
+```java
+import java.util.List;
+
+enum Day {
+    Monday,
+    Tuesday,
+    Wednesday,
+    Thursday,
+    Friday,
+    Saturday,
+    Sunday
+}
+
+boolean isWeekend(Day d) {
+
+    return switch (d) {
+        case Day.Monday, Day.Tuesday, Day.Wednesday, Day.Thursday, Day.Friday -> false;
+        case Day.Saturday, Day.Sunday -> true;
+    };
+}
+
+void main() {
+
+    var days = List.of(Day.Monday, Day.Tuesday, Day.Wednesday, Day.Thursday,
+            Day.Friday, Day.Saturday, Day.Sunday);
+
+    for (var e : days) {
+
+        if (isWeekend(e)) {
+            System.out.print("weekend ");
+        } else {
+            System.out.print("weekday ");
+        }
+    }
+}
+```
+
+
+```java
+import java.util.Random;
+
+void main() {
+
+    Season season = Season.randomSeason();
+
+    String msg = switch (season) {
+
+        case Season.SPRING -> "Spring";
+        case Season.SUMMER -> "Summer";
+        case Season.AUTUMN -> "Autumn";
+        case Season.WINTER -> "Winter";
+    };
+
+    System.out.println(msg);
+}
+
+enum Season {
+    SPRING,
+    SUMMER,
+    AUTUMN,
+    WINTER;
+
+    public static Season randomSeason() {
+        
+        var random = new Random();
+        int ridx = random.nextInt(Season.values().length);
+        return Season.values()[ridx];
+    }
+}
+```
+
+## Planets 
+
+```java
+void main() {
+
+    double earthWeight = 63;
+    double mass = earthWeight / Planet.EARTH.surfaceGravity();
+
+    for (Planet p : Planet.values()) {
+
+        System.out.println(STR."Your weight on \{p} is \{p.surfaceWeight(mass)}");
+    }
+}
+
+enum Planet {
+
+    MERCURY(3.303e+23, 2.4397e6),
+    VENUS(4.869e+24, 6.0518e6),
+    EARTH(5.976e+24, 6.37814e6),
+    MARS(6.421e+23, 3.3972e6),
+    JUPITER(1.9e+27, 7.1492e7),
+    SATURN(5.688e+26, 6.0268e7),
+    URANUS(8.686e+25, 2.5559e7),
+    NEPTUNE(1.024e+26, 2.4746e7);
+
+    private final double mass; // in kilograms
+    private final double radius; // in meters
+
+    Planet(double mass, double radius) {
+        this.mass = mass;
+        this.radius = radius;
+    }
+
+    private double mass() {
+        return mass;
+    }
+
+    private double radius() {
+        return radius;
+    }
+
+    // universal gravitational constant (m3 kg-1 s-2)
+    final double G = 6.67300E-11;
+
+    double surfaceGravity() {
+        return G * mass / (radius * radius);
+    }
+
+    double surfaceWeight(double otherMass) {
+        return otherMass * surfaceGravity();
+    }
+
+    @Override
+    public String toString() {
+        return this.name().charAt(0) + name().substring(1).toLowerCase();
+    }
+}
+```
+
diff --git a/types/record.md b/types/record.md
new file mode 100644
index 00000000..5b5a37d4
--- /dev/null
+++ b/types/record.md
@@ -0,0 +1,148 @@
+# Records
+
+A `record` provides a compact way to define an immutable data class introduced in Java 14.  
+It simplifies creating classes that primarily hold data. 
+
+Key features of records:
+
+- Concise Syntax: Uses the record keyword for a cleaner declaration compared to traditional classes.  
+- Automatic Methods: Essential methods like constructors, getters (accessors), `equals`, `hashCode`,  
+  and `toString` are automatically generated.  
+- Immutable: Records are intended to be immutable, meaning their data cannot be changed after creation.  
+
+In essence, Java records are lightweight classes focused on data storage with built-in functionality.
+
+## Simple example
+
+```java
+void main() {
+
+    var u = new User("John Doe", "gardener");
+    System.out.println(u);
+
+    System.out.println(u.name());
+    System.out.println(u.occupation());
+}
+
+record User(String name, String occupation) {
+}
+```
+
+## equals
+
+Two records are considered equal if a) they are of the same type (record class), b) all  
+their fields have the same value (determined by calling equals on each corresponding field).  
+
+Java automatically generates an `equals` method for records based on the record's fields.  
+The default `equals` method considers all record fields for equality checks.  
+
+```java
+void main() {
+
+    var u = new User("John Doe", "gardener");
+    var u2 = new User("Roger Roe", "driver");
+    var u3 = new User("John Doe", "gardener");
+
+    if (u.equals(u2)) {
+        System.out.println("users are equal");
+    } else {
+        System.out.println("users are not equal");
+    }
+
+    if (u.equals(u3)) {
+        System.out.println("users are equal");
+    } else {
+        System.out.println("users are not equal");
+    }
+}
+
+record User(String name, String occupation) {
+}
+```
+
+## Comparison
+
+```java
+import java.util.Comparator;
+import java.util.List;
+
+void main() {
+
+    var users = List.of(
+            new User("John", "Doe", 1230),
+            new User("Lucy", "Novak", 670),
+            new User("Ben", "Walter", 2050),
+            new User("Robin", "Brown", 2300),
+            new User("Amy", "Doe", 1250),
+            new User("Joe", "Draker", 1190),
+            new User("Janet", "Doe", 980),
+            new User("Albert", "Novak", 1930));
+
+    var sorted = users.stream().sorted(Comparator.comparingInt(User::salary)).toList();
+    System.out.println(sorted);
+}
+
+record User(String fname, String lname, int salary) {
+}
+```
+
+## Comparable
+
+```java
+import java.util.List;
+
+void main() {
+
+    var users = List.of(
+            new User("John", "Doe", 1230),
+            new User("Lucy", "Novak", 670),
+            new User("Ben", "Walter", 2050),
+            new User("Robin", "Brown", 2300),
+            new User("Amy", "Doe", 1250),
+            new User("Joe", "Draker", 1190),
+            new User("Janet", "Doe", 980),
+            new User("Albert", "Novak", 1930));
+
+    var sorted = users.stream().sorted().toList();
+    System.out.println(sorted);
+}
+
+record User(String fname, String lname, int salary) implements Comparable<User> {
+    @Override
+    public int compareTo(User u) {
+        return this.lname.compareTo(u.lname);
+    }
+}
+```
+
+## Filtering
+
+```java
+import java.util.List;
+import java.util.stream.Collectors;
+
+void main() {
+
+    var users = List.of(
+            User.of("John", "Doe", 1230),
+            User.of("Lucy", "Novak", 670),
+            User.of("Ben", "Walter", 2050),
+            User.of("Robin", "Brown", 2300),
+            User.of("Amy", "Doe", 1250),
+            User.of("Joe", "Draker", 1190),
+            User.of("Janet", "Doe", 980),
+            User.of("Albert", "Novak", 1930));
+
+    var filtered = users.stream().filter(e -> e.salary() > 2000)
+            .collect(Collectors.toList());
+    System.out.println(filtered);
+}
+
+record User(String fname, String lname, int salary) {
+    public static User of(String fname, String lname, int salary) {
+        return new User(fname, lname, salary);
+    }
+}
+```
+
+
diff --git a/virtual-threads.md b/virtual-threads.md
new file mode 100644
index 00000000..e69de29b
diff --git a/virtualthreads-structuredconcurrency.md b/virtualthreads-structuredconcurrency.md
new file mode 100644
index 00000000..bf196093
--- /dev/null
+++ b/virtualthreads-structuredconcurrency.md
@@ -0,0 +1,2054 @@
+# Virtual Threads and Structured Concurrency
+
+Virtual threads and structured concurrency represent a paradigm shift in how Java  
+handles concurrent programming. Introduced through Project Loom, these features  
+address fundamental limitations in traditional thread-based concurrency models.  
+Virtual threads are lightweight threads managed by the JVM rather than the  
+operating system, enabling applications to create millions of concurrent tasks  
+without exhausting system resources. Structured concurrency provides a framework  
+for organizing concurrent tasks into well-defined scopes, ensuring proper  
+lifecycle management, error handling, and resource cleanup.  
+
+Traditional Java concurrency relies on platform threads, which are expensive OS  
+resources. Each platform thread consumes significant memory (typically 1MB for  
+the stack) and incurs context-switching overhead when the OS scheduler moves  
+between threads. This limits applications to thousands of concurrent threads at  
+best, forcing developers to use complex asynchronous programming patterns like  
+callbacks, futures, and reactive streams to achieve high concurrency.  
+
+Project Loom solves these problems by introducing virtual threads that are  
+scheduled by the JVM on a small pool of carrier (platform) threads. When a  
+virtual thread blocks on I/O or synchronization, it automatically yields its  
+carrier thread, allowing other virtual threads to run. This enables the simple  
+thread-per-request programming model to scale to millions of concurrent tasks.  
+Combined with structured concurrency, which ensures that child tasks complete  
+before their parent scope exits, Java now offers a powerful, intuitive approach  
+to concurrent programming.  
+
+| Aspect | Traditional Threads | Virtual Threads |
+|--------|---------------------|-----------------|
+| Memory per thread | ~1MB stack | ~1KB initial |
+| Creation cost | High (OS call) | Low (JVM managed) |
+| Max concurrent | Thousands | Millions |
+| Blocking impact | Wastes OS thread | Yields carrier |
+| Programming model | Thread pools, async | Thread-per-task |
+| Debugging | Complex stack traces | Clear stack traces |
+
+## Why Project Loom matters  
+
+Project Loom addresses the fundamental mismatch between the thread-per-request  
+model and the scalability requirements of modern applications. Before Loom,  
+developers faced a difficult choice: use simple blocking code that doesn't scale,  
+or use complex async code that's hard to write, debug, and maintain. Virtual  
+threads eliminate this trade-off by making blocking cheap.  
+
+```java
+import java.util.concurrent.Executors;
+
+void main() throws Exception {
+
+    // Create 100,000 concurrent tasks - impossible with platform threads
+    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+        for (int i = 0; i < 100_000; i++) {
+            int taskId = i;
+            executor.submit(() -> {
+                try {
+                    Thread.sleep(1000);
+                } catch (InterruptedException e) {
+                    Thread.currentThread().interrupt();
+                }
+                if (taskId % 10_000 == 0) {
+                    println("Task " + taskId + " completed");
+                }
+            });
+        }
+    }
+    println("All 100,000 tasks completed");
+}
+```
+
+This example launches 100,000 concurrent tasks, each sleeping for one second.  
+With platform threads, this would require 100GB of memory just for thread stacks  
+and would likely crash the system. With virtual threads, it runs smoothly using  
+minimal resources because sleeping virtual threads don't consume carrier threads.  
+
+## Virtual threads fundamentals  
+
+Virtual threads are instances of Thread that run on carrier threads managed by  
+a ForkJoinPool. They look and behave like regular threads but are scheduled by  
+the JVM rather than the operating system.  
+
+```java
+void main() throws InterruptedException {
+
+    var virtualThread = Thread.ofVirtual()
+        .name("my-virtual-thread")
+        .start(() -> {
+            println("Running in: " + Thread.currentThread());
+            println("Is virtual: " + Thread.currentThread().isVirtual());
+        });
+
+    virtualThread.join();
+
+    var platformThread = Thread.ofPlatform()
+        .name("my-platform-thread")
+        .start(() -> {
+            println("Running in: " + Thread.currentThread());
+            println("Is virtual: " + Thread.currentThread().isVirtual());
+        });
+
+    platformThread.join();
+}
+```
+
+The Thread.ofVirtual factory creates a virtual thread builder, while  
+Thread.ofPlatform creates a platform thread builder. The isVirtual method  
+distinguishes between thread types. Virtual threads have names prefixed with  
+empty string by default but can be named for debugging purposes.  
+
+## Starting virtual threads  
+
+Virtual threads can be started using several methods, from direct creation to  
+executor services.  
+
+```java
+void main() throws InterruptedException {
+
+    // Method 1: Thread.startVirtualThread
+    var t1 = Thread.startVirtualThread(() -> {
+        println("Method 1: startVirtualThread");
+    });
+
+    // Method 2: Thread.ofVirtual().start()
+    var t2 = Thread.ofVirtual().start(() -> {
+        println("Method 2: ofVirtual().start()");
+    });
+
+    // Method 3: Thread.ofVirtual().unstarted() then start()
+    var t3 = Thread.ofVirtual().unstarted(() -> {
+        println("Method 3: unstarted then start");
+    });
+    t3.start();
+
+    t1.join();
+    t2.join();
+    t3.join();
+}
+```
+
+The startVirtualThread method is the most concise for fire-and-forget tasks.  
+The builder pattern with ofVirtual provides more control over thread  
+configuration. Using unstarted allows configuring the thread before starting  
+it, useful when you need to set up the thread before execution begins.  
+
+## Virtual thread per task executor  
+
+The newVirtualThreadPerTaskExecutor creates a new virtual thread for each  
+submitted task, providing seamless integration with existing executor-based code.  
+
+```java
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+
+void main() throws Exception {
+
+    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+        var futures = new ArrayList<Future<String>>();
+
+        for (int i = 1; i <= 10; i++) {
+            int taskId = i;
+            futures.add(executor.submit(() -> {
+                Thread.sleep(100);
+                return "Result from task " + taskId;
+            }));
+        }
+
+        for (var future : futures) {
+            println(future.get());
+        }
+    }
+}
+```
+
+Each task runs in its own virtual thread, allowing massive concurrency without  
+thread pool sizing concerns. The try-with-resources pattern ensures all tasks  
+complete before the executor closes. This executor is ideal for I/O-bound  
+workloads where tasks spend most time waiting.  
+
+
+## Virtual threads with thread factory  
+
+Custom thread factories enable consistent naming and configuration of virtual  
+threads.  
+
+```java
+import java.util.concurrent.Executors;
+import java.util.concurrent.ThreadFactory;
+import java.util.concurrent.atomic.AtomicInteger;
+
+void main() throws Exception {
+
+    var counter = new AtomicInteger(0);
+    ThreadFactory factory = Thread.ofVirtual()
+        .name("worker-", counter.getAndIncrement())
+        .factory();
+
+    try (var executor = Executors.newThreadPerTaskExecutor(factory)) {
+        for (int i = 0; i < 5; i++) {
+            executor.submit(() -> {
+                println("Running: " + Thread.currentThread().getName());
+            });
+        }
+    }
+}
+```
+
+The thread factory creates virtual threads with incrementing names like  
+worker-0, worker-1, etc. This improves debugging and monitoring by providing  
+meaningful thread names in logs and profilers. The factory can be reused  
+across multiple executors for consistent naming.  
+
+## Platform threads vs virtual threads comparison  
+
+Understanding the performance difference between platform and virtual threads  
+helps in choosing the right approach.  
+
+```java
+import java.util.concurrent.Executors;
+
+void main() throws Exception {
+
+    int taskCount = 10_000;
+
+    // Platform threads (limited pool)
+    long startPlatform = System.currentTimeMillis();
+    try (var executor = Executors.newFixedThreadPool(100)) {
+        for (int i = 0; i < taskCount; i++) {
+            executor.submit(() -> {
+                try { Thread.sleep(10); } catch (InterruptedException e) {}
+            });
+        }
+    }
+    long platformTime = System.currentTimeMillis() - startPlatform;
+
+    // Virtual threads (unlimited)
+    long startVirtual = System.currentTimeMillis();
+    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+        for (int i = 0; i < taskCount; i++) {
+            executor.submit(() -> {
+                try { Thread.sleep(10); } catch (InterruptedException e) {}
+            });
+        }
+    }
+    long virtualTime = System.currentTimeMillis() - startVirtual;
+
+    println("Platform threads (100 pool): " + platformTime + "ms");
+    println("Virtual threads: " + virtualTime + "ms");
+}
+```
+
+Platform threads with a fixed pool of 100 must process 10,000 tasks in batches,  
+taking approximately 1 second (10,000 / 100 * 10ms). Virtual threads run all  
+tasks concurrently, completing in roughly 10ms plus overhead. This demonstrates  
+the dramatic throughput improvement for I/O-bound workloads.  
+
+## Structured concurrency introduction  
+
+Structured concurrency organizes concurrent tasks into scopes with clear  
+lifecycles. Tasks started within a scope are guaranteed to complete before the  
+scope exits, preventing orphaned threads and resource leaks.  
+
+```java
+import java.util.concurrent.StructuredTaskScope;
+
+void main() throws Exception {
+
+    try (var scope = new StructuredTaskScope<String>()) {
+        var task1 = scope.fork(() -> {
+            Thread.sleep(500);
+            return "Result 1";
+        });
+
+        var task2 = scope.fork(() -> {
+            Thread.sleep(300);
+            return "Result 2";
+        });
+
+        scope.join();
+
+        println("Task 1: " + task1.get());
+        println("Task 2: " + task2.get());
+    }
+}
+```
+
+The StructuredTaskScope creates a scope for forking subtasks. Each fork  
+creates a new virtual thread to execute the task. The join method waits for  
+all forked tasks to complete. The try-with-resources ensures proper cleanup  
+even if exceptions occur.  
+
+## ShutdownOnFailure policy  
+
+The ShutdownOnFailure policy cancels remaining tasks when any task fails,  
+enabling fail-fast behavior.  
+
+```java
+import java.util.concurrent.StructuredTaskScope;
+
+void main() {
+
+    try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
+        var userTask = scope.fork(() -> fetchUser(1));
+        var orderTask = scope.fork(() -> fetchOrder(1));
+
+        scope.join();
+        scope.throwIfFailed();
+
+        println("User: " + userTask.get());
+        println("Order: " + orderTask.get());
+    } catch (Exception e) {
+        println("Operation failed: " + e.getMessage());
+    }
+}
+
+String fetchUser(int id) throws InterruptedException {
+    Thread.sleep(200);
+    return "User-" + id;
+}
+
+String fetchOrder(int id) throws InterruptedException {
+    Thread.sleep(300);
+    return "Order-" + id;
+}
+```
+
+When one task fails, ShutdownOnFailure cancels all other tasks in the scope.  
+The throwIfFailed method propagates the first exception that occurred. This  
+is ideal when all subtasks must succeed for the overall operation to be valid,  
+like fetching related data that must be consistent.  
+
+## ShutdownOnSuccess policy  
+
+The ShutdownOnSuccess policy returns as soon as any task succeeds, cancelling  
+the remaining tasks.  
+
+```java
+import java.util.concurrent.StructuredTaskScope;
+
+void main() throws Exception {
+
+    try (var scope = new StructuredTaskScope.ShutdownOnSuccess<String>()) {
+        scope.fork(() -> queryServer("Primary", 500));
+        scope.fork(() -> queryServer("Backup", 300));
+        scope.fork(() -> queryServer("Fallback", 700));
+
+        scope.join();
+
+        String result = scope.result();
+        println("First successful result: " + result);
+    }
+}
+
+String queryServer(String name, int latency) throws InterruptedException {
+    Thread.sleep(latency);
+    return name + " responded";
+}
+```
+
+The first task to complete successfully provides the result, and other tasks  
+are cancelled. This pattern is perfect for redundant requests to multiple  
+servers, hedged requests, or any scenario where you need the fastest successful  
+response. The result method returns the winning task's value.  
+
+## Handling task failures  
+
+Structured concurrency provides clean mechanisms for handling failures in  
+concurrent tasks.  
+
+```java
+import java.util.concurrent.StructuredTaskScope;
+
+void main() {
+
+    try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
+        var task1 = scope.fork(() -> {
+            Thread.sleep(100);
+            return "Success";
+        });
+
+        var task2 = scope.fork(() -> {
+            Thread.sleep(50);
+            throw new RuntimeException("Task 2 failed!");
+        });
+
+        scope.join();
+        scope.throwIfFailed(e -> new RuntimeException("Custom: " + e.getMessage()));
+
+        println(task1.get());
+    } catch (Exception e) {
+        println("Caught: " + e.getMessage());
+    }
+}
+```
+
+The overloaded throwIfFailed method accepts a function to transform  
+exceptions, enabling custom error messages or exception types. When task2 fails,  
+task1 is cancelled even if it hasn't completed yet. The exception includes the  
+full context of what failed.  
+
+## Nested structured concurrency  
+
+Structured concurrency scopes can be nested, creating hierarchies of concurrent  
+operations.  
+
+```java
+import java.util.concurrent.StructuredTaskScope;
+
+void main() throws Exception {
+
+    try (var outer = new StructuredTaskScope.ShutdownOnFailure()) {
+        var result = outer.fork(() -> {
+            try (var inner = new StructuredTaskScope.ShutdownOnFailure()) {
+                var a = inner.fork(() -> compute("A"));
+                var b = inner.fork(() -> compute("B"));
+                inner.join();
+                inner.throwIfFailed();
+                return a.get() + " + " + b.get();
+            }
+        });
+
+        outer.join();
+        outer.throwIfFailed();
+
+        println("Combined: " + result.get());
+    }
+}
+
+String compute(String name) throws InterruptedException {
+    Thread.sleep(100);
+    return "Result-" + name;
+}
+```
+
+The inner scope runs two parallel computations, and its combined result becomes  
+the return value of the outer task. If any inner task fails, the inner scope  
+shuts down first, which then causes the outer task to fail. This hierarchical  
+structure makes complex concurrent workflows manageable.  
+
+## Timeout with structured concurrency  
+
+Structured concurrency integrates seamlessly with timeout handling.  
+
+```java
+import java.time.Duration;
+import java.time.Instant;
+import java.util.concurrent.StructuredTaskScope;
+
+void main() {
+
+    try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
+        var task = scope.fork(() -> {
+            Thread.sleep(5000);
+            return "Completed";
+        });
+
+        scope.joinUntil(Instant.now().plus(Duration.ofSeconds(1)));
+        scope.throwIfFailed();
+
+        println(task.get());
+    } catch (Exception e) {
+        println("Timed out or failed: " + e.getClass().getSimpleName());
+    }
+}
+```
+
+The joinUntil method specifies a deadline for all tasks to complete. If tasks  
+don't finish by the deadline, they are interrupted and the scope throws a  
+TimeoutException. This prevents operations from hanging indefinitely and  
+enables responsive applications.  
+
+## Collecting results from multiple tasks  
+
+Aggregating results from multiple concurrent tasks is a common pattern in  
+structured concurrency.  
+
+```java
+import java.util.concurrent.StructuredTaskScope;
+import java.util.concurrent.StructuredTaskScope.Subtask;
+
+void main() throws Exception {
+
+    try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
+        var tasks = new ArrayList<Subtask<String>>();
+
+        for (int i = 1; i <= 5; i++) {
+            int id = i;
+            tasks.add(scope.fork(() -> fetchData(id)));
+        }
+
+        scope.join();
+        scope.throwIfFailed();
+
+        var results = tasks.stream()
+            .map(Subtask::get)
+            .toList();
+
+        println("Results: " + results);
+    }
+}
+
+String fetchData(int id) throws InterruptedException {
+    Thread.sleep((long) (Math.random() * 500));
+    return "Data-" + id;
+}
+```
+
+Multiple tasks are forked and their Subtask handles are collected. After  
+joining, results are extracted using stream operations. All tasks run  
+concurrently, so total time is the maximum individual task time, not the sum.  
+This pattern is ideal for parallel data fetching.  
+
+
+## Custom StructuredTaskScope  
+
+Creating custom scopes enables specialized behavior for domain-specific  
+requirements.  
+
+```java
+import java.util.concurrent.StructuredTaskScope;
+import java.util.concurrent.atomic.AtomicInteger;
+
+class CountingScope<T> extends StructuredTaskScope<T> {
+    private final AtomicInteger successCount = new AtomicInteger(0);
+    private final AtomicInteger failureCount = new AtomicInteger(0);
+
+    @Override
+    protected void handleComplete(Subtask<? extends T> subtask) {
+        if (subtask.state() == Subtask.State.SUCCESS) {
+            successCount.incrementAndGet();
+        } else if (subtask.state() == Subtask.State.FAILED) {
+            failureCount.incrementAndGet();
+        }
+    }
+
+    int getSuccessCount() { return successCount.get(); }
+    int getFailureCount() { return failureCount.get(); }
+}
+
+void main() throws Exception {
+
+    try (var scope = new CountingScope<String>()) {
+        scope.fork(() -> "Success 1");
+        scope.fork(() -> "Success 2");
+        scope.fork(() -> { throw new RuntimeException("Fail"); });
+
+        scope.join();
+
+        println("Successes: " + scope.getSuccessCount());
+        println("Failures: " + scope.getFailureCount());
+    }
+}
+```
+
+Custom scopes override handleComplete to react when tasks finish. This example  
+counts successful and failed tasks. Custom scopes can implement voting policies,  
+result aggregation, partial success handling, or any domain-specific logic.  
+
+## Virtual threads with blocking I/O  
+
+Virtual threads excel at blocking I/O operations, automatically yielding their  
+carrier thread while waiting.  
+
+```java
+import java.net.URI;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.util.concurrent.Executors;
+
+void main() throws Exception {
+
+    var client = HttpClient.newHttpClient();
+    var urls = List.of(
+        "https://httpbin.org/delay/1",
+        "https://httpbin.org/delay/1",
+        "https://httpbin.org/delay/1"
+    );
+
+    long start = System.currentTimeMillis();
+
+    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+        var futures = urls.stream()
+            .map(url -> executor.submit(() -> {
+                var request = HttpRequest.newBuilder()
+                    .uri(URI.create(url))
+                    .build();
+                return client.send(request, 
+                    HttpResponse.BodyHandlers.ofString()).statusCode();
+            }))
+            .toList();
+
+        for (var future : futures) {
+            println("Status: " + future.get());
+        }
+    }
+
+    println("Total time: " + (System.currentTimeMillis() - start) + "ms");
+}
+```
+
+Three HTTP requests that each take 1 second complete in about 1 second total  
+because they run concurrently on virtual threads. While waiting for network  
+responses, the virtual threads yield their carriers, allowing efficient use of  
+the underlying thread pool.  
+
+## Database connection simulation  
+
+Virtual threads handle database-like blocking operations efficiently.  
+
+```java
+import java.util.concurrent.Executors;
+
+void main() throws Exception {
+
+    record User(int id, String name) {}
+
+    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+        var futures = new ArrayList<java.util.concurrent.Future<User>>();
+
+        for (int i = 1; i <= 1000; i++) {
+            int userId = i;
+            futures.add(executor.submit(() -> {
+                Thread.sleep(50);
+                return new User(userId, "User-" + userId);
+            }));
+        }
+
+        int count = 0;
+        for (var future : futures) {
+            future.get();
+            count++;
+        }
+        println("Fetched " + count + " users");
+    }
+}
+```
+
+Simulating 1000 database queries that each take 50ms completes in about 50ms  
+with virtual threads, not 50 seconds. Each query runs in its own virtual  
+thread, and blocking calls like Thread.sleep don't waste platform threads.  
+
+## Semaphore with virtual threads  
+
+Semaphores control access to limited resources when using virtual threads.  
+
+```java
+import java.util.concurrent.Executors;
+import java.util.concurrent.Semaphore;
+
+void main() throws Exception {
+
+    var connectionPool = new Semaphore(10);
+
+    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+        for (int i = 1; i <= 100; i++) {
+            int taskId = i;
+            executor.submit(() -> {
+                try {
+                    connectionPool.acquire();
+                    println("Task " + taskId + " acquired connection");
+                    Thread.sleep(100);
+                } catch (InterruptedException e) {
+                    Thread.currentThread().interrupt();
+                } finally {
+                    connectionPool.release();
+                }
+            });
+        }
+    }
+    println("All tasks completed");
+}
+```
+
+A semaphore limits concurrent database connections to 10, even though 100  
+virtual threads are running. When a virtual thread blocks on acquire, it  
+yields its carrier thread. This pattern enables resource pooling while  
+maintaining the simplicity of thread-per-task programming.  
+
+## Parallel data processing  
+
+Virtual threads simplify parallel processing of data collections.  
+
+```java
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+
+void main() throws Exception {
+
+    var items = List.of("apple", "banana", "cherry", "date", "elderberry",
+                        "fig", "grape", "honeydew", "kiwi", "lemon");
+
+    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+        var futures = items.stream()
+            .map(item -> executor.submit(() -> processItem(item)))
+            .toList();
+
+        var results = new ArrayList<String>();
+        for (var future : futures) {
+            results.add(future.get());
+        }
+
+        println("Processed: " + results);
+    }
+}
+
+String processItem(String item) throws InterruptedException {
+    Thread.sleep((long) (Math.random() * 200));
+    return item.toUpperCase();
+}
+```
+
+Each item is processed in its own virtual thread, allowing concurrent execution.  
+The random sleep simulates varying processing times. Results are collected in  
+submission order, preserving the original sequence while gaining parallelism.  
+
+
+## Structured concurrency for API aggregation  
+
+Structured concurrency excels at aggregating data from multiple APIs.  
+
+```java
+import java.util.concurrent.StructuredTaskScope;
+
+void main() throws Exception {
+
+    record UserProfile(String user, String orders, String preferences) {}
+
+    try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
+        var userTask = scope.fork(() -> fetchUserData(1));
+        var ordersTask = scope.fork(() -> fetchOrders(1));
+        var prefsTask = scope.fork(() -> fetchPreferences(1));
+
+        scope.join();
+        scope.throwIfFailed();
+
+        var profile = new UserProfile(
+            userTask.get(),
+            ordersTask.get(),
+            prefsTask.get()
+        );
+
+        println("Profile: " + profile);
+    }
+}
+
+String fetchUserData(int id) throws InterruptedException {
+    Thread.sleep(300);
+    return "User-" + id;
+}
+
+String fetchOrders(int id) throws InterruptedException {
+    Thread.sleep(500);
+    return "Orders for user " + id;
+}
+
+String fetchPreferences(int id) throws InterruptedException {
+    Thread.sleep(200);
+    return "Prefs for user " + id;
+}
+```
+
+Three API calls run concurrently, and their results are combined into a  
+UserProfile record. Total latency is the maximum of individual calls (500ms),  
+not the sum (1000ms). If any call fails, all others are cancelled, preventing  
+wasted work.  
+
+## Error propagation in structured concurrency  
+
+Structured concurrency ensures errors propagate correctly through task  
+hierarchies.  
+
+```java
+import java.util.concurrent.StructuredTaskScope;
+
+void main() {
+
+    try {
+        processOrder(123);
+        println("Order processed successfully");
+    } catch (Exception e) {
+        println("Order failed: " + e.getMessage());
+    }
+}
+
+void processOrder(int orderId) throws Exception {
+    try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
+        var inventory = scope.fork(() -> checkInventory(orderId));
+        var payment = scope.fork(() -> processPayment(orderId));
+
+        scope.join();
+        scope.throwIfFailed();
+
+        println("Inventory: " + inventory.get());
+        println("Payment: " + payment.get());
+    }
+}
+
+String checkInventory(int orderId) throws Exception {
+    Thread.sleep(100);
+    if (orderId % 2 == 1) {
+        throw new Exception("Inventory check failed for order " + orderId);
+    }
+    return "In stock";
+}
+
+String processPayment(int orderId) throws InterruptedException {
+    Thread.sleep(200);
+    return "Payment confirmed";
+}
+```
+
+When checkInventory fails, the payment task is cancelled and the exception  
+propagates to the caller. This prevents partial operations and ensures either  
+complete success or clean failure. The exception includes full context for  
+debugging.  
+
+## Cancellation handling  
+
+Virtual threads respond to interruption, enabling proper cancellation handling.  
+
+```java
+import java.util.concurrent.StructuredTaskScope;
+
+void main() throws Exception {
+
+    try (var scope = new StructuredTaskScope.ShutdownOnSuccess<String>()) {
+        scope.fork(() -> {
+            for (int i = 0; i < 100; i++) {
+                if (Thread.currentThread().isInterrupted()) {
+                    println("Task 1 was cancelled at iteration " + i);
+                    return "Cancelled";
+                }
+                Thread.sleep(50);
+            }
+            return "Task 1 completed";
+        });
+
+        scope.fork(() -> {
+            Thread.sleep(100);
+            return "Task 2 completed quickly";
+        });
+
+        scope.join();
+        println("Result: " + scope.result());
+    }
+}
+```
+
+Task 2 completes first, triggering ShutdownOnSuccess to cancel Task 1. Task 1  
+checks for interruption and exits gracefully. Proper cancellation handling  
+prevents wasted computation and enables responsive shutdown.  
+
+## Virtual threads with locks  
+
+Virtual threads work with standard Java synchronization primitives.  
+
+```java
+import java.util.concurrent.Executors;
+import java.util.concurrent.locks.ReentrantLock;
+
+void main() throws Exception {
+
+    var lock = new ReentrantLock();
+    var counter = new int[]{0};
+
+    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+        for (int i = 0; i < 1000; i++) {
+            executor.submit(() -> {
+                lock.lock();
+                try {
+                    counter[0]++;
+                } finally {
+                    lock.unlock();
+                }
+            });
+        }
+    }
+
+    println("Counter: " + counter[0]);
+}
+```
+
+ReentrantLock works correctly with virtual threads. When a virtual thread  
+blocks on lock, it may pin its carrier thread (in some cases), so prefer  
+using synchronized or lock-free constructs where possible. For short critical  
+sections, the pinning overhead is minimal.  
+
+## Pinning demonstration  
+
+Pinning occurs when a virtual thread cannot yield its carrier thread, typically  
+inside synchronized blocks.  
+
+```java
+import java.util.concurrent.Executors;
+
+void main() throws Exception {
+
+    var monitor = new Object();
+
+    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+        for (int i = 0; i < 10; i++) {
+            int taskId = i;
+            executor.submit(() -> {
+                synchronized (monitor) {
+                    println("Task " + taskId + " entered synchronized block");
+                    try {
+                        Thread.sleep(100);
+                    } catch (InterruptedException e) {
+                        Thread.currentThread().interrupt();
+                    }
+                    println("Task " + taskId + " exiting synchronized block");
+                }
+            });
+        }
+    }
+}
+```
+
+Sleeping inside a synchronized block pins the virtual thread to its carrier.  
+This limits concurrency because other virtual threads cannot use that carrier.  
+Avoid blocking operations inside synchronized blocks when using virtual threads.  
+Use ReentrantLock with careful design instead.  
+
+## Avoiding pinning with ReentrantLock  
+
+Using ReentrantLock instead of synchronized can reduce pinning issues.  
+
+```java
+import java.util.concurrent.Executors;
+import java.util.concurrent.locks.ReentrantLock;
+
+void main() throws Exception {
+
+    var lock = new ReentrantLock();
+    var sharedResource = new StringBuilder();
+
+    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+        for (int i = 0; i < 10; i++) {
+            int taskId = i;
+            executor.submit(() -> {
+                lock.lock();
+                try {
+                    Thread.sleep(100);
+                    sharedResource.append(taskId).append(" ");
+                } catch (InterruptedException e) {
+                    Thread.currentThread().interrupt();
+                } finally {
+                    lock.unlock();
+                }
+            });
+        }
+    }
+
+    println("Result: " + sharedResource);
+}
+```
+
+With ReentrantLock, the virtual thread may still experience some pinning, but  
+it is generally handled better than synchronized blocks. The lock ensures mutual  
+exclusion while allowing other virtual threads to make progress on their  
+carriers.  
+
+## Concurrent map updates  
+
+ConcurrentHashMap works well with virtual threads for concurrent data access.  
+
+```java
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.Executors;
+
+void main() throws Exception {
+
+    var wordCounts = new ConcurrentHashMap<String, Integer>();
+    var words = List.of("apple", "banana", "apple", "cherry", "banana", 
+                        "apple", "date", "cherry", "banana", "apple");
+
+    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+        for (var word : words) {
+            executor.submit(() -> {
+                wordCounts.merge(word, 1, Integer::sum);
+            });
+        }
+    }
+
+    println("Word counts: " + wordCounts);
+}
+```
+
+The merge method atomically updates counts without explicit locking. Each  
+word is processed in its own virtual thread, but ConcurrentHashMap ensures  
+thread-safe updates. This pattern scales to millions of concurrent updates.  
+
+
+## Fan-out pattern  
+
+The fan-out pattern distributes work across many virtual threads.  
+
+```java
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+
+void main() throws Exception {
+
+    var numbers = List.of(1, 2, 3, 4, 5, 6, 7, 8, 9, 10);
+
+    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+        var futures = numbers.stream()
+            .map(n -> executor.submit(() -> {
+                Thread.sleep((long) (Math.random() * 100));
+                return n * n;
+            }))
+            .toList();
+
+        int sum = 0;
+        for (var future : futures) {
+            sum += future.get();
+        }
+
+        println("Sum of squares: " + sum);
+    }
+}
+```
+
+Each number is squared in its own virtual thread, with results aggregated.  
+The fan-out pattern is ideal for embarrassingly parallel computations where  
+tasks are independent. Total time approaches the maximum task time rather than  
+the sum.  
+
+## Fan-in pattern  
+
+The fan-in pattern collects results from multiple virtual threads into a  
+single result.  
+
+```java
+import java.util.concurrent.StructuredTaskScope;
+import java.util.concurrent.atomic.AtomicInteger;
+
+void main() throws Exception {
+
+    var total = new AtomicInteger(0);
+
+    try (var scope = new StructuredTaskScope<Integer>()) {
+        for (int i = 1; i <= 10; i++) {
+            int value = i;
+            scope.fork(() -> {
+                Thread.sleep((long) (Math.random() * 100));
+                int result = value * value;
+                total.addAndGet(result);
+                return result;
+            });
+        }
+
+        scope.join();
+    }
+
+    println("Total: " + total.get());
+}
+```
+
+Multiple tasks compute partial results that are aggregated into a single total.  
+AtomicInteger ensures thread-safe accumulation. This pattern is common in  
+map-reduce style computations where intermediate results must be combined.  
+
+## Pipeline processing  
+
+Virtual threads enable efficient pipeline processing of data.  
+
+```java
+import java.util.concurrent.BlockingQueue;
+import java.util.concurrent.Executors;
+import java.util.concurrent.LinkedBlockingQueue;
+
+void main() throws Exception {
+
+    BlockingQueue<String> stage1Output = new LinkedBlockingQueue<>();
+    BlockingQueue<String> stage2Output = new LinkedBlockingQueue<>();
+
+    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+        executor.submit(() -> {
+            for (int i = 1; i <= 5; i++) {
+                stage1Output.put("Item-" + i);
+                Thread.sleep(100);
+            }
+            stage1Output.put("DONE");
+            return null;
+        });
+
+        executor.submit(() -> {
+            while (true) {
+                String item = stage1Output.take();
+                if ("DONE".equals(item)) {
+                    stage2Output.put("DONE");
+                    break;
+                }
+                stage2Output.put(item.toUpperCase());
+            }
+            return null;
+        });
+
+        executor.submit(() -> {
+            while (true) {
+                String item = stage2Output.take();
+                if ("DONE".equals(item)) break;
+                println("Final: " + item);
+            }
+            return null;
+        });
+    }
+}
+```
+
+Three pipeline stages run concurrently, connected by blocking queues. Virtual  
+threads make blocking queue operations efficient. The producer-transformer-  
+consumer pattern enables streaming data processing with natural backpressure.  
+
+## Retry with virtual threads  
+
+Implementing retry logic is straightforward with virtual threads.  
+
+```java
+import java.util.concurrent.Callable;
+import java.util.concurrent.Executors;
+
+void main() throws Exception {
+
+    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+        var result = executor.submit(() -> 
+            retryWithBackoff(() -> unreliableOperation(), 3, 100))
+            .get();
+
+        println("Result: " + result);
+    }
+}
+
+String unreliableOperation() throws Exception {
+    if (Math.random() < 0.7) {
+        println("Operation failed, will retry...");
+        throw new Exception("Random failure");
+    }
+    return "Success!";
+}
+
+<T> T retryWithBackoff(Callable<T> operation, int maxRetries, 
+                        long initialDelay) throws Exception {
+    Exception lastException = null;
+    for (int attempt = 0; attempt < maxRetries; attempt++) {
+        try {
+            return operation.call();
+        } catch (Exception e) {
+            lastException = e;
+            Thread.sleep(initialDelay * (1L << attempt));
+        }
+    }
+    throw lastException;
+}
+```
+
+The retry logic uses exponential backoff between attempts. Sleeping in a  
+virtual thread doesn't waste platform threads. This pattern is essential for  
+resilient applications that handle transient failures gracefully.  
+
+## Scatter-gather pattern  
+
+The scatter-gather pattern sends requests to multiple services and collects  
+responses.  
+
+```java
+import java.util.concurrent.StructuredTaskScope;
+
+void main() throws Exception {
+
+    record SearchResult(String source, List<String> results) {}
+
+    try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
+        var webTask = scope.fork(() -> searchWeb("java virtual threads"));
+        var newsTask = scope.fork(() -> searchNews("java virtual threads"));
+        var academicTask = scope.fork(() -> searchAcademic("java virtual threads"));
+
+        scope.join();
+        scope.throwIfFailed();
+
+        var allResults = List.of(
+            webTask.get(),
+            newsTask.get(),
+            academicTask.get()
+        );
+
+        println("Combined results from " + allResults.size() + " sources");
+        allResults.forEach(r -> 
+            println(r.source() + ": " + r.results().size() + " results"));
+    }
+}
+
+SearchResult searchWeb(String query) throws InterruptedException {
+    Thread.sleep(300);
+    return new SearchResult("Web", List.of("Result 1", "Result 2"));
+}
+
+SearchResult searchNews(String query) throws InterruptedException {
+    Thread.sleep(200);
+    return new SearchResult("News", List.of("Article 1"));
+}
+
+SearchResult searchAcademic(String query) throws InterruptedException {
+    Thread.sleep(400);
+    return new SearchResult("Academic", List.of("Paper 1", "Paper 2", "Paper 3"));
+}
+```
+
+Three search services are queried concurrently, and results are aggregated.  
+If any service fails, all searches are cancelled. This pattern improves latency  
+by parallelizing independent service calls.  
+
+## Rate limiting with virtual threads  
+
+Rate limiting controls the pace of operations when using virtual threads.  
+
+```java
+import java.util.concurrent.Executors;
+import java.util.concurrent.Semaphore;
+
+void main() throws Exception {
+
+    var rateLimiter = new Semaphore(5);
+
+    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+        for (int i = 1; i <= 20; i++) {
+            int requestId = i;
+            executor.submit(() -> {
+                try {
+                    rateLimiter.acquire();
+                    try {
+                        println("Processing request " + requestId + 
+                            " at " + System.currentTimeMillis() % 10000);
+                        Thread.sleep(1000);
+                    } finally {
+                        rateLimiter.release();
+                    }
+                } catch (InterruptedException e) {
+                    Thread.currentThread().interrupt();
+                }
+            });
+        }
+    }
+}
+```
+
+A semaphore limits concurrent operations to 5, even with 20 virtual threads  
+requesting access. Virtual threads blocked on the semaphore don't consume  
+platform threads. This pattern prevents overwhelming external services or  
+databases.  
+
+## Timeout per operation  
+
+Individual operation timeouts ensure responsive behavior.  
+
+```java
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+
+void main() {
+
+    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+        var future = executor.submit(() -> {
+            Thread.sleep(5000);
+            return "Completed";
+        });
+
+        try {
+            var result = future.get(1, TimeUnit.SECONDS);
+            println("Result: " + result);
+        } catch (java.util.concurrent.TimeoutException e) {
+            println("Operation timed out");
+            future.cancel(true);
+        } catch (Exception e) {
+            println("Error: " + e.getMessage());
+        }
+    }
+}
+```
+
+The Future.get method with timeout limits how long to wait for a result.  
+Cancelling the future after timeout stops the virtual thread. This prevents  
+individual slow operations from blocking the entire application.  
+
+## Bulk operation timeout  
+
+Timeouts can apply to groups of operations using structured concurrency.  
+
+```java
+import java.time.Duration;
+import java.time.Instant;
+import java.util.concurrent.StructuredTaskScope;
+
+void main() {
+
+    try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
+        for (int i = 1; i <= 5; i++) {
+            int taskId = i;
+            scope.fork(() -> {
+                Thread.sleep(taskId * 500L);
+                return "Task " + taskId + " completed";
+            });
+        }
+
+        try {
+            scope.joinUntil(Instant.now().plus(Duration.ofSeconds(1)));
+            scope.throwIfFailed();
+            println("All tasks completed in time");
+        } catch (java.util.concurrent.TimeoutException e) {
+            println("Some tasks timed out");
+        }
+    } catch (Exception e) {
+        println("Error: " + e.getMessage());
+    }
+}
+```
+
+Tasks taking 500ms, 1000ms, 1500ms, 2000ms, and 2500ms are started. With a 1  
+second deadline, only the first two complete; others are interrupted. This  
+ensures predictable response times for aggregate operations.  
+
+
+## Graceful shutdown  
+
+Virtual thread executors support graceful shutdown patterns.  
+
+```java
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+
+void main() throws InterruptedException {
+
+    ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor();
+
+    for (int i = 1; i <= 10; i++) {
+        int taskId = i;
+        executor.submit(() -> {
+            try {
+                Thread.sleep(taskId * 200L);
+                println("Task " + taskId + " completed");
+            } catch (InterruptedException e) {
+                println("Task " + taskId + " was interrupted");
+            }
+        });
+    }
+
+    Thread.sleep(500);
+    println("Initiating shutdown...");
+    executor.shutdown();
+
+    if (!executor.awaitTermination(1, TimeUnit.SECONDS)) {
+        println("Forcing shutdown...");
+        executor.shutdownNow();
+    }
+
+    println("Executor terminated");
+}
+```
+
+Graceful shutdown waits for running tasks, while shutdownNow interrupts them.  
+Tasks should handle interruption to enable clean shutdown. This pattern ensures  
+resources are released properly when the application stops.  
+
+## Monitoring virtual threads  
+
+JFR events enable monitoring of virtual thread behavior.  
+
+```java
+import java.util.concurrent.Executors;
+
+void main() throws Exception {
+
+    println("Starting virtual thread monitoring demo...");
+    println("Use JFR to capture events: jdk.VirtualThreadStart, " +
+            "jdk.VirtualThreadEnd, jdk.VirtualThreadPinned");
+
+    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+        for (int i = 0; i < 100; i++) {
+            executor.submit(() -> {
+                Thread.sleep(10);
+                return null;
+            });
+        }
+    }
+
+    println("Monitoring complete. Analyze with JFR/JMC for:");
+    println("- Virtual thread creation/termination");
+    println("- Carrier thread utilization");
+    println("- Pinning events");
+}
+```
+
+Java Flight Recorder (JFR) provides events for virtual thread lifecycle,  
+pinning, and carrier thread usage. Use JDK Mission Control to analyze  
+recordings. Monitoring helps identify performance issues and pinning hotspots.  
+
+## Thread-local with virtual threads  
+
+Thread-locals work with virtual threads but have caveats.  
+
+```java
+import java.util.concurrent.Executors;
+
+void main() throws Exception {
+
+    ThreadLocal<String> context = new ThreadLocal<>();
+
+    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+        for (int i = 1; i <= 5; i++) {
+            int taskId = i;
+            executor.submit(() -> {
+                context.set("Context-" + taskId);
+                println(Thread.currentThread().getName() + 
+                    " has context: " + context.get());
+                context.remove();
+            });
+        }
+    }
+}
+```
+
+Each virtual thread has its own thread-local storage. However, with millions of  
+virtual threads, thread-locals can consume significant memory. Consider using  
+scoped values (preview feature) or passing context explicitly for better  
+scalability.  
+
+## Scoped values preview  
+
+Scoped values offer a more efficient alternative to thread-locals for virtual  
+threads.  
+
+```java
+import java.util.concurrent.StructuredTaskScope;
+
+void main() throws Exception {
+
+    ScopedValue<String> USER = ScopedValue.newInstance();
+
+    ScopedValue.where(USER, "Alice").run(() -> {
+        try (var scope = new StructuredTaskScope<String>()) {
+            var task1 = scope.fork(() -> {
+                return "Task 1 sees user: " + USER.get();
+            });
+
+            var task2 = scope.fork(() -> {
+                return "Task 2 sees user: " + USER.get();
+            });
+
+            scope.join();
+
+            println(task1.get());
+            println(task2.get());
+        } catch (Exception e) {
+            println("Error: " + e.getMessage());
+        }
+    });
+}
+```
+
+Scoped values are inherited by child virtual threads automatically. They are  
+immutable within a scope and more memory-efficient than thread-locals. This  
+feature integrates naturally with structured concurrency.  
+
+## Server request handling simulation  
+
+Virtual threads excel at handling many concurrent server requests.  
+
+```java
+import java.util.concurrent.Executors;
+import java.util.concurrent.atomic.AtomicInteger;
+
+void main() throws Exception {
+
+    var requestCount = new AtomicInteger(0);
+    var completedCount = new AtomicInteger(0);
+
+    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+        for (int i = 0; i < 10_000; i++) {
+            executor.submit(() -> {
+                requestCount.incrementAndGet();
+                handleRequest();
+                completedCount.incrementAndGet();
+            });
+        }
+    }
+
+    println("Received: " + requestCount.get() + " requests");
+    println("Completed: " + completedCount.get() + " requests");
+}
+
+void handleRequest() {
+    try {
+        Thread.sleep(100);
+        parseRequest();
+        Thread.sleep(50);
+        queryDatabase();
+        Thread.sleep(30);
+        formatResponse();
+    } catch (InterruptedException e) {
+        Thread.currentThread().interrupt();
+    }
+}
+
+void parseRequest() {}
+void queryDatabase() {}
+void formatResponse() {}
+```
+
+Ten thousand concurrent requests are handled efficiently. Each request involves  
+multiple blocking operations (simulated with sleep). Virtual threads enable  
+thread-per-request architecture without resource exhaustion.  
+
+## Comparison with CompletableFuture  
+
+Virtual threads simplify code compared to CompletableFuture chains.  
+
+```java
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.Executors;
+import java.util.concurrent.StructuredTaskScope;
+
+void main() throws Exception {
+
+    // CompletableFuture approach
+    var cf = CompletableFuture.supplyAsync(() -> {
+        try { Thread.sleep(100); } catch (InterruptedException e) {}
+        return "user";
+    }).thenCompose(user -> CompletableFuture.supplyAsync(() -> {
+        try { Thread.sleep(100); } catch (InterruptedException e) {}
+        return user + "-orders";
+    })).thenApply(data -> data.toUpperCase());
+
+    println("CF result: " + cf.get());
+
+    // Virtual thread approach
+    try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
+        var task = scope.fork(() -> {
+            Thread.sleep(100);
+            String user = "user";
+            Thread.sleep(100);
+            String orders = user + "-orders";
+            return orders.toUpperCase();
+        });
+        scope.join();
+        scope.throwIfFailed();
+        println("VT result: " + task.get());
+    }
+}
+```
+
+The virtual thread version uses straightforward sequential code while  
+maintaining concurrency benefits. CompletableFuture requires chaining and  
+lambdas, making code harder to read and debug. Virtual threads preserve  
+natural code structure.  
+
+## Microservice call aggregation  
+
+Structured concurrency simplifies calling multiple microservices.  
+
+```java
+import java.util.concurrent.StructuredTaskScope;
+
+void main() throws Exception {
+
+    record Order(String id, String userId, List<String> items, 
+                 String shipping, String payment) {}
+
+    try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
+        var userTask = scope.fork(() -> callUserService("user-123"));
+        var inventoryTask = scope.fork(() -> callInventoryService("order-456"));
+        var shippingTask = scope.fork(() -> callShippingService("addr-789"));
+        var paymentTask = scope.fork(() -> callPaymentService("pay-012"));
+
+        scope.join();
+        scope.throwIfFailed();
+
+        var order = new Order(
+            "order-456",
+            userTask.get(),
+            inventoryTask.get(),
+            shippingTask.get(),
+            paymentTask.get()
+        );
+
+        println("Order assembled: " + order);
+    }
+}
+
+String callUserService(String id) throws InterruptedException {
+    Thread.sleep(200);
+    return "John Doe";
+}
+
+List<String> callInventoryService(String id) throws InterruptedException {
+    Thread.sleep(300);
+    return List.of("Widget", "Gadget");
+}
+
+String callShippingService(String id) throws InterruptedException {
+    Thread.sleep(150);
+    return "Express Delivery";
+}
+
+String callPaymentService(String id) throws InterruptedException {
+    Thread.sleep(250);
+    return "Credit Card ****1234";
+}
+```
+
+Four microservice calls run concurrently, with results combined into an Order  
+record. If any service fails, others are cancelled. Total latency is the  
+maximum individual call time (300ms), not the sum (900ms).  
+
+
+## Best practice: prefer structured concurrency  
+
+Structured concurrency should be preferred over unstructured alternatives.  
+
+```java
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+import java.util.concurrent.StructuredTaskScope;
+
+void main() throws Exception {
+
+    // Anti-pattern: unstructured concurrency
+    println("Unstructured approach (not recommended):");
+    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+        Future<String> orphan = executor.submit(() -> {
+            Thread.sleep(1000);
+            return "Orphan result";
+        });
+        println("Executor closed, but task might still run...");
+    }
+
+    // Best practice: structured concurrency
+    println("\nStructured approach (recommended):");
+    try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
+        var managed = scope.fork(() -> {
+            Thread.sleep(100);
+            return "Managed result";
+        });
+        scope.join();
+        scope.throwIfFailed();
+        println("Result: " + managed.get());
+    }
+    println("Scope closed, all tasks guaranteed complete");
+}
+```
+
+Structured concurrency guarantees task completion before scope exit. Unstructured  
+approaches can leave orphan tasks running, causing resource leaks and unexpected  
+behavior. Always prefer StructuredTaskScope for concurrent operations.  
+
+## Best practice: avoid blocking in synchronized  
+
+Minimize blocking operations inside synchronized blocks to prevent pinning.  
+
+```java
+import java.util.concurrent.Executors;
+import java.util.concurrent.locks.ReentrantLock;
+
+void main() throws Exception {
+
+    var lock = new ReentrantLock();
+    var monitor = new Object();
+
+    println("Using ReentrantLock (better for virtual threads):");
+    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+        for (int i = 0; i < 5; i++) {
+            int id = i;
+            executor.submit(() -> {
+                lock.lock();
+                try {
+                    println("Task " + id + " in critical section");
+                } finally {
+                    lock.unlock();
+                }
+            });
+        }
+    }
+
+    println("\nUsing synchronized (may cause pinning):");
+    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+        for (int i = 0; i < 5; i++) {
+            int id = i;
+            executor.submit(() -> {
+                synchronized (monitor) {
+                    println("Task " + id + " in synchronized block");
+                }
+            });
+        }
+    }
+}
+```
+
+While both approaches work, ReentrantLock handles virtual thread scheduling  
+more gracefully than synchronized blocks. For new code using virtual threads,  
+prefer explicit locks or lock-free algorithms.  
+
+## Best practice: resource cleanup  
+
+Proper resource cleanup is essential with virtual threads.  
+
+```java
+import java.util.concurrent.StructuredTaskScope;
+
+void main() throws Exception {
+
+    record Resource(String name) implements AutoCloseable {
+        Resource { println("Opening: " + name); }
+        @Override
+        public void close() { println("Closing: " + name); }
+    }
+
+    try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
+        scope.fork(() -> {
+            try (var resource = new Resource("Resource A")) {
+                Thread.sleep(100);
+                return "Used " + resource.name();
+            }
+        });
+
+        scope.fork(() -> {
+            try (var resource = new Resource("Resource B")) {
+                Thread.sleep(150);
+                throw new RuntimeException("Task B failed");
+            }
+        });
+
+        scope.join();
+
+        try {
+            scope.throwIfFailed();
+        } catch (Exception e) {
+            println("Caught: " + e.getMessage());
+        }
+    }
+
+    println("All resources cleaned up");
+}
+```
+
+Use try-with-resources for automatic cleanup. When tasks fail, resources are  
+still closed properly. Structured concurrency ensures cleanup happens before  
+the scope exits, even during failures.  
+
+## Common pitfall: thread pool sizing  
+
+Fixed thread pools limit virtual thread benefits.  
+
+```java
+import java.util.concurrent.Executors;
+
+void main() throws Exception {
+
+    // Anti-pattern: using fixed pool with virtual threads
+    println("Fixed pool (bad pattern):");
+    long start1 = System.currentTimeMillis();
+    try (var executor = Executors.newFixedThreadPool(10)) {
+        for (int i = 0; i < 100; i++) {
+            executor.submit(() -> {
+                try { Thread.sleep(100); } catch (InterruptedException e) {}
+            });
+        }
+    }
+    println("Fixed pool time: " + (System.currentTimeMillis() - start1) + "ms");
+
+    // Best practice: virtual thread per task
+    println("\nVirtual thread executor (good pattern):");
+    long start2 = System.currentTimeMillis();
+    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+        for (int i = 0; i < 100; i++) {
+            executor.submit(() -> {
+                try { Thread.sleep(100); } catch (InterruptedException e) {}
+            });
+        }
+    }
+    println("Virtual threads time: " + (System.currentTimeMillis() - start2) + "ms");
+}
+```
+
+Fixed thread pools serialize work through limited threads. Virtual thread  
+executors allow all tasks to run concurrently. Use newVirtualThreadPerTaskExecutor  
+for I/O-bound workloads instead of sizing thread pools.  
+
+## Common pitfall: CPU-bound tasks  
+
+Virtual threads don't improve CPU-bound task performance.  
+
+```java
+import java.util.concurrent.Executors;
+
+void main() throws Exception {
+
+    // CPU-bound work - virtual threads don't help
+    println("CPU-bound computation (virtual threads not beneficial):");
+    long start = System.currentTimeMillis();
+    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+        for (int i = 0; i < 4; i++) {
+            int taskId = i;
+            executor.submit(() -> {
+                long sum = 0;
+                for (long j = 0; j < 100_000_000; j++) {
+                    sum += j;
+                }
+                println("Task " + taskId + " sum: " + sum);
+            });
+        }
+    }
+    println("CPU-bound time: " + (System.currentTimeMillis() - start) + "ms");
+
+    // For CPU-bound work, use platform threads with parallelism
+    println("\nUse parallel streams or ForkJoinPool for CPU-bound work");
+}
+```
+
+Virtual threads are optimized for I/O-bound tasks that frequently block. For  
+CPU-intensive computations, use platform threads, parallel streams, or  
+ForkJoinPool. Virtual threads share carrier threads, so CPU-bound tasks can  
+monopolize them.  
+
+## Batch processing with virtual threads  
+
+Virtual threads enable efficient batch processing of large datasets.  
+
+```java
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+
+void main() throws Exception {
+
+    var records = new ArrayList<String>();
+    for (int i = 1; i <= 1000; i++) {
+        records.add("Record-" + i);
+    }
+
+    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+        var futures = records.stream()
+            .map(record -> executor.submit(() -> processRecord(record)))
+            .toList();
+
+        int processed = 0;
+        for (var future : futures) {
+            future.get();
+            processed++;
+        }
+        println("Processed " + processed + " records");
+    }
+}
+
+String processRecord(String record) throws InterruptedException {
+    Thread.sleep(10);
+    return record.toUpperCase();
+}
+```
+
+Each record is processed in its own virtual thread, enabling high throughput.  
+With 1000 records taking 10ms each, sequential processing would take 10 seconds.  
+Virtual threads complete all processing in approximately 10ms plus overhead.  
+
+## Async event handling  
+
+Virtual threads simplify event-driven architectures.  
+
+```java
+import java.util.concurrent.BlockingQueue;
+import java.util.concurrent.Executors;
+import java.util.concurrent.LinkedBlockingQueue;
+
+void main() throws Exception {
+
+    BlockingQueue<String> eventQueue = new LinkedBlockingQueue<>();
+
+    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+        executor.submit(() -> {
+            for (int i = 1; i <= 10; i++) {
+                eventQueue.put("Event-" + i);
+                Thread.sleep(100);
+            }
+            eventQueue.put("SHUTDOWN");
+            return null;
+        });
+
+        for (int i = 0; i < 3; i++) {
+            int handlerId = i;
+            executor.submit(() -> {
+                while (true) {
+                    String event = eventQueue.take();
+                    if ("SHUTDOWN".equals(event)) {
+                        eventQueue.put("SHUTDOWN");
+                        break;
+                    }
+                    println("Handler " + handlerId + " processed: " + event);
+                    Thread.sleep(50);
+                }
+                return null;
+            });
+        }
+    }
+}
+```
+
+Multiple event handlers process events from a shared queue. Blocking on  
+queue.take doesn't waste threads. The shutdown signal propagates to all  
+handlers. This pattern scales to thousands of concurrent event handlers.  
+
+## Connection pooling with virtual threads  
+
+Connection pools work seamlessly with virtual threads.  
+
+```java
+import java.util.concurrent.Executors;
+import java.util.concurrent.Semaphore;
+
+void main() throws Exception {
+
+    var connectionPool = new ConnectionPool(5);
+
+    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+        for (int i = 1; i <= 20; i++) {
+            int queryId = i;
+            executor.submit(() -> {
+                try (var connection = connectionPool.acquire()) {
+                    println("Query " + queryId + " using " + connection);
+                    Thread.sleep(100);
+                }
+            });
+        }
+    }
+
+    println("All queries completed");
+}
+
+class ConnectionPool {
+    private final Semaphore semaphore;
+    private final java.util.concurrent.atomic.AtomicInteger connectionId = new java.util.concurrent.atomic.AtomicInteger(0);
+
+    ConnectionPool(int size) {
+        this.semaphore = new Semaphore(size);
+    }
+
+    Connection acquire() throws InterruptedException {
+        semaphore.acquire();
+        return new Connection(connectionId.incrementAndGet(), this);
+    }
+
+    void release() {
+        semaphore.release();
+    }
+}
+
+record Connection(int id, ConnectionPool pool) implements AutoCloseable {
+    @Override
+    public void close() {
+        pool.release();
+    }
+}
+```
+
+A semaphore-based pool limits concurrent connections. Virtual threads waiting  
+for connections don't block carrier threads. The AutoCloseable pattern ensures  
+connections are returned to the pool.  
+
+## Parallel file processing  
+
+Virtual threads efficiently process multiple files concurrently.  
+
+```java
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+
+void main() throws Exception {
+
+    var files = List.of("file1.txt", "file2.txt", "file3.txt", 
+                        "file4.txt", "file5.txt");
+
+    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+        var futures = files.stream()
+            .map(file -> executor.submit(() -> processFile(file)))
+            .toList();
+
+        for (var future : futures) {
+            println(future.get());
+        }
+    }
+}
+
+String processFile(String filename) throws InterruptedException {
+    println("Processing: " + filename);
+    Thread.sleep((long) (Math.random() * 500));
+    return filename + " processed successfully";
+}
+```
+
+Each file is processed in its own virtual thread. I/O-bound file operations  
+benefit from virtual threads because they spend most time waiting. Total  
+processing time is the maximum individual file time, not the sum.  
+
+
+## Summary comparison table  
+
+| Feature | Platform Threads | Virtual Threads | Structured Concurrency |
+|---------|------------------|-----------------|------------------------|
+| Memory overhead | High (~1MB) | Low (~1KB) | Inherits from virtual |
+| Creation cost | Expensive | Cheap | Adds scope overhead |
+| Max concurrency | Thousands | Millions | Depends on tasks |
+| Blocking cost | Wastes thread | Yields carrier | Same as virtual |
+| Error handling | Manual | Manual | Automatic propagation |
+| Task lifecycle | Unmanaged | Unmanaged | Scoped and managed |
+| Cancellation | Manual interrupt | Manual interrupt | Automatic on failure |
+| Debug/profile | Complex | Clear stacks | Hierarchical context |
+| Best for | CPU-bound | I/O-bound | Coordinated I/O tasks |
+
+## Conclusion  
+
+Virtual threads and structured concurrency fundamentally transform concurrent  
+programming in Java. Virtual threads eliminate the scalability limitations of  
+platform threads, enabling millions of concurrent tasks with minimal memory  
+overhead. When a virtual thread blocks on I/O, it automatically yields its  
+carrier thread, allowing other tasks to proceed.  
+
+Structured concurrency adds organizational structure to concurrent code. By  
+binding task lifecycles to lexical scopes, it ensures that child tasks complete  
+before their parent scope exits. This prevents orphaned threads, simplifies  
+error handling, and makes concurrent code easier to reason about.  
+
+Key takeaways for adopting these features:  
+
+1. **Use virtual threads for I/O-bound workloads**: Web servers, database  
+   clients, and microservices benefit most from virtual threads.  
+
+2. **Prefer structured concurrency**: Use StructuredTaskScope instead of raw  
+   executors to ensure proper task lifecycle management.  
+
+3. **Avoid pinning**: Minimize blocking operations inside synchronized blocks;  
+   prefer ReentrantLock or lock-free algorithms.  
+
+4. **Don't pool virtual threads**: Create a new virtual thread per task;  
+   pooling defeats their purpose.  
+
+5. **Keep CPU-bound work on platform threads**: Virtual threads don't improve  
+   compute-intensive operations.  
+
+6. **Monitor with JFR**: Use Java Flight Recorder to identify pinning and  
+   understand carrier thread utilization.  
+
+7. **Migrate incrementally**: Existing ExecutorService code can switch to  
+   newVirtualThreadPerTaskExecutor with minimal changes.  
+
+Together, virtual threads and structured concurrency make Java a compelling  
+choice for high-concurrency applications, combining the simplicity of  
+thread-per-task programming with the scalability of asynchronous systems.  
diff --git a/web/embeddedjetty/plaintext/pom.xml b/web/embeddedjetty/plaintext/pom.xml
index 259bca5d..64f7ba24 100644
--- a/web/embeddedjetty/plaintext/pom.xml
+++ b/web/embeddedjetty/plaintext/pom.xml
@@ -20,7 +20,7 @@
         <dependency>
             <groupId>org.eclipse.jetty</groupId>
             <artifactId>jetty-server</artifactId>
-            <version>9.4.41.v20210516</version>
+            <version>9.4.56.v20240826</version>
         </dependency>
         <dependency>
             <groupId>org.eclipse.jetty</groupId>
diff --git a/web/embeddedjetty/secureres/pom.xml b/web/embeddedjetty/secureres/pom.xml
index 3a7bdb46..dd3389f9 100644
--- a/web/embeddedjetty/secureres/pom.xml
+++ b/web/embeddedjetty/secureres/pom.xml
@@ -21,7 +21,7 @@
         <dependency>
             <groupId>org.eclipse.jetty</groupId>
             <artifactId>jetty-server</artifactId>
-            <version>9.4.41.v20210516</version>
+            <version>9.4.56.v20240826</version>
         </dependency>
 
         <dependency>
diff --git a/web/httpclient/post-json/pom.xml b/web/httpclient/post-json/pom.xml
index 9f98b348..552093d4 100644
--- a/web/httpclient/post-json/pom.xml
+++ b/web/httpclient/post-json/pom.xml
@@ -19,7 +19,7 @@
         <dependency>
             <groupId>io.undertow</groupId>
             <artifactId>undertow-core</artifactId>
-            <version>2.2.19.Final</version>
+            <version>2.2.24.Final</version>
         </dependency>
 
         <dependency>
diff --git a/web/undertow/fileserver/pom.xml b/web/undertow/fileserver/pom.xml
index e614fc3e..90e632d8 100644
--- a/web/undertow/fileserver/pom.xml
+++ b/web/undertow/fileserver/pom.xml
@@ -19,7 +19,7 @@
         <dependency>
             <groupId>io.undertow</groupId>
             <artifactId>undertow-core</artifactId>
-            <version>2.2.19.Final</version>
+            <version>2.2.24.Final</version>
         </dependency>
     </dependencies>
 
diff --git a/web/undertow/pathparam/pom.xml b/web/undertow/pathparam/pom.xml
index 2c8e440a..a8ba2aa7 100644
--- a/web/undertow/pathparam/pom.xml
+++ b/web/undertow/pathparam/pom.xml
@@ -19,7 +19,7 @@
         <dependency>
             <groupId>io.undertow</groupId>
             <artifactId>undertow-core</artifactId>
-            <version>2.2.19.Final</version>
+            <version>2.2.24.Final</version>
         </dependency>
 
     </dependencies>
diff --git a/web/undertow/queryparam/pom.xml b/web/undertow/queryparam/pom.xml
index 2c8e440a..07622484 100644
--- a/web/undertow/queryparam/pom.xml
+++ b/web/undertow/queryparam/pom.xml
@@ -19,7 +19,7 @@
         <dependency>
             <groupId>io.undertow</groupId>
             <artifactId>undertow-core</artifactId>
-            <version>2.2.19.Final</version>
+            <version>2.3.20.Final</version>
         </dependency>
 
     </dependencies>
diff --git a/web/undertow/routing/pom.xml b/web/undertow/routing/pom.xml
index cd83c525..5a1abfa0 100644
--- a/web/undertow/routing/pom.xml
+++ b/web/undertow/routing/pom.xml
@@ -19,7 +19,7 @@
         <dependency>
             <groupId>io.undertow</groupId>
             <artifactId>undertow-core</artifactId>
-            <version>2.2.19.Final</version>
+            <version>2.2.24.Final</version>
         </dependency>
 
     </dependencies>
diff --git a/web/undertow/sendimage/pom.xml b/web/undertow/sendimage/pom.xml
index f49b8353..56983adf 100644
--- a/web/undertow/sendimage/pom.xml
+++ b/web/undertow/sendimage/pom.xml
@@ -19,7 +19,7 @@
         <dependency>
             <groupId>io.undertow</groupId>
             <artifactId>undertow-core</artifactId>
-            <version>2.2.19.Final</version>
+            <version>2.3.20.Final</version>
         </dependency>
     </dependencies>
 
diff --git a/web/undertow/servlet/pom.xml b/web/undertow/servlet/pom.xml
index 422d6f85..10ca3ef3 100644
--- a/web/undertow/servlet/pom.xml
+++ b/web/undertow/servlet/pom.xml
@@ -19,7 +19,7 @@
         <dependency>
             <groupId>io.undertow</groupId>
             <artifactId>undertow-core</artifactId>
-            <version>2.2.19.Final</version>
+            <version>2.2.24.Final</version>
         </dependency>
 
         <dependency>
diff --git a/web/undertow/simple/pom.xml b/web/undertow/simple/pom.xml
index 16c45f7b..541194a3 100644
--- a/web/undertow/simple/pom.xml
+++ b/web/undertow/simple/pom.xml
@@ -20,7 +20,7 @@
         <dependency>
             <groupId>io.undertow</groupId>
             <artifactId>undertow-core</artifactId>
-            <version>2.2.19.Final</version>
+            <version>2.3.20.Final</version>
         </dependency>
 
     </dependencies>
diff --git a/web/undertow/welcomepage/pom.xml b/web/undertow/welcomepage/pom.xml
index 298c0e0f..207f3c59 100644
--- a/web/undertow/welcomepage/pom.xml
+++ b/web/undertow/welcomepage/pom.xml
@@ -19,7 +19,7 @@
         <dependency>
             <groupId>io.undertow</groupId>
             <artifactId>undertow-core</artifactId>
-            <version>2.2.19.Final</version>
+            <version>2.2.24.Final</version>
         </dependency>
     </dependencies>