Lesson 3: Multi-Threading

Executors, futures, CompletableFuture, virtual threads, atomic counters, deterministic aggregation, top-N ranking, and ordered parallel results.

scripts/run.sh lesson_3 demo
scripts/run.sh lesson_3 exercise
scripts/apply_answers.sh lesson_3
scripts/run.sh lesson_3 verify
scripts/reset_exercises.sh lesson_3

Lesson README

Lesson 3: Multi-Threading

This lesson presents Java concurrency as task orchestration plus shared-state discipline.

120-Minute Plan

Exercise

Use workbook.md for the full two-hour learner path. It includes concurrency tracing, staged implementation rounds, and edge-case drills.

Edit src/exercise/java/tutorial/lesson3/exercise/ConcurrentStats.java.

Functions to implement:

• countWordsParallel
• mergeCounts
• mergeAll
• totalWordCount
• topWord
• topWords
• countDocumentsContaining
• countWordsExcludingStopWords
• documentLengthsParallel

The stubs use simple behavior so learners can run the file before implementing the concurrent solution.

After applying answers, run scripts/run.sh lesson_3 verify to check parallel/sequential consistency, deterministic top-N ordering, exact token matching, stop-word filtering, empty input, and ordered parallel results.

Learner Workbook

Learner Workbook: Lesson 3 Multi-Threading

This workbook is designed to take about two hours. The goal is not to make every line concurrent. The goal is to know where concurrency helps, how Java represents tasks, and how to avoid unsafe shared state.

What You Should Understand By The End

• The difference between a task, thread, executor, future, and atomic value.
• Why result aggregation is often safer than mutating shared state.
• How to preserve deterministic output while running work concurrently.
• How interruption and task failure should be handled.
• Why parallelism has overhead and is not always faster.

0-15 Minutes: Run And Label Output

Run:

scripts/reset_exercises.sh lesson_3
scripts/run.sh lesson_3 demo
scripts/run.sh lesson_3 exercise

Label each demo output line as one of:

• sequential
• fixed thread pool
• CompletableFuture
• virtual thread
• atomic counter

15-35 Minutes: Trace The Demo

Open src/demo/java/tutorial/lesson3/demo/ThreadingDemo.java.

Trace the fixed-pool section:

• Executor is created.
• Tasks are submitted.
• Futures are stored.
• Results are collected.
• Executor is closed.

Then inspect the virtual-thread section. Write one sentence explaining what virtual threads make cheaper, and one sentence explaining what they do not solve.

35-50 Minutes: Read The Exercise API

Open src/exercise/java/tutorial/lesson3/exercise/ConcurrentStats.java.

Group functions by skill:

• Counting: countWordsSequential, countWordsParallel, countWordsExcludingStopWords
• Merging: mergeCounts, mergeAll
• Ranking: topWord, topWords
• Querying: countDocumentsContaining
• Ordered parallel results: documentLengthsParallel

Before editing, identify which functions can be implemented without concurrency. Those are good warmups.

50-95 Minutes: Implement In Rounds

Round 1:

• Implement mergeCounts.
• Verify it returns a new map and does not mutate inputs.

Round 2:

• Implement mergeAll.
• Test an empty list and overlapping keys.

Round 3:

• Implement totalWordCount, topWords, and topWord.
• Tie-break alphabetically so output is deterministic.

Round 4:

• Implement countDocumentsContaining.
• It must match exact tokens, not substrings.
• Blank search words return 0.

Round 5:

• Implement countWordsExcludingStopWords.
• Normalize stop words to lowercase.

Round 6:

• Implement countWordsParallel.
• Do not let worker tasks mutate one shared HashMap.
• Each task should produce a map; the caller merges maps.

Round 7:

• Implement documentLengthsParallel.
• Preserve input order even though work runs concurrently.

95-110 Minutes: Verify Answers

Run:

scripts/apply_answers.sh lesson_3
scripts/run.sh lesson_3 verify
scripts/reset_exercises.sh lesson_3

Read failures carefully. Concurrency bugs often show up as nondeterministic output, mutation of input maps, or wrong ordering.

110-120 Minutes: Edge-Case Drill

Try these cases:

• Empty document list
• Blank document
• Repeated punctuation
• Uppercase and lowercase copies of the same word
• Search for thread when documents contain threads
• topWords with limit 0, 1, larger than map size, and -1
• Stop words with different casing

Reset when done:

scripts/reset_exercises.sh lesson_3

Instructor Notes

Instructor Notes: Lesson 3 Multi-Threading

Session Goal

Teach Java concurrency as task coordination plus state discipline. Learners should understand how to run independent work concurrently, collect results, and avoid shared mutable state when aggregation is simpler.

Learning Outcomes

By the end of 120 minutes, learners should be able to:

• Explain the difference between a thread, task, executor, future, and atomic value.
• Use an ExecutorService with try-with-resources.
• Collect Future results and handle interruption correctly.
• Explain virtual threads at a practical level.
• Implement a parallel word-count exercise by producing independent maps and merging them.

Before Class

Run:

scripts/reset_exercises.sh lesson_3
scripts/run.sh lesson_3 demo
scripts/run.sh lesson_3 exercise

Confirm javac -version is 21 or newer. Lesson 3 uses Executors.newVirtualThreadPerTaskExecutor().

Know the key files:

• src/demo/java/tutorial/lesson3/demo/ThreadingDemo.java
• src/exercise/java/tutorial/lesson3/exercise/ConcurrentStats.java

Minute-By-Minute Plan

Teaching Script

Open with:

"Concurrency is not just making code faster. It is deciding what can happen independently and what data must be coordinated."

For the fixed-pool section, trace this sequence:

• Create a bounded executor.
• Submit independent prime-count tasks.
• Store futures.
• Read each result with get.
• Let try-with-resources close the executor.

Key explanation:

"The task is concurrent, but result collection here is deliberately boring. Boring result collection is a feature."

For virtual threads:

"A virtual thread is still a Java thread from the programmer's perspective. The runtime can schedule many of them efficiently, especially when they block. They are not a substitute for thinking about shared state."

Exercise Facilitation

Learners edit ConcurrentStats.java.

Recommended implementation path:

• Leave countWordsSequential unchanged.
• Implement mergeCounts and mergeAll first because the parallel solution depends on them.
• Implement totalWordCount, topWords, and topWord.
• Implement exact document matching and stop-word filtering.
• Implement countWordsParallel by submitting one task per document.
• Implement ordered parallel document lengths.
• Catch InterruptedException, restore the interrupt flag, and throw an unchecked exception.
• Catch ExecutionException and wrap it.

Hints:

• "Do not have every task mutate one shared map."
• "Return one map per document, then merge."
• "Use at most documents.size() workers."
• "An empty document list should not create a zero-sized pool."

Expected Answer Behavior

After applying answers:

scripts/apply_answers.sh lesson_3
scripts/run.sh lesson_3 verify

Expected important lines:

lesson_3 answers verified

Common Mistakes

• Creating a fixed pool with size zero for an empty input.
• Updating a shared HashMap from multiple tasks.
• Swallowing InterruptedException.
• Forgetting future.get() can throw ExecutionException.
• Measuring tiny inputs and concluding concurrency is always faster.

Discussion Prompts

• What would change if documents were read from disk or network?
• Should this use virtual threads instead of a fixed pool?
• How would you preserve input order in the output?
• Where should cancellation be handled?
• What is the smallest input where parallelism might pay off?

Extension Challenge

Ask learners to add a stop-word filter for words such as the, and, and are. Then ask whether the filter belongs inside wordsIn, inside each task, or as a separate preprocessing step.

Functions In This Lesson

private ConcurrentStats() {

public static Map<String, Integer> countWordsSequential(List<String> documents) {

public static Map<String, Integer> countWordsParallel(List<String> documents) {

public static Map<String, Integer> mergeCounts(Map<String, Integer> left, Map<String, Integer> right) {

public static Map<String, Integer> mergeAll(List<Map<String, Integer>> maps) {

public static int totalWordCount(Map<String, Integer> counts) {

public static Optional<String> topWord(Map<String, Integer> counts) {

public static List<String> topWords(Map<String, Integer> counts, int limit) {

public static int countDocumentsContaining(List<String> documents, String word) {

public static Map<String, Integer> countWordsExcludingStopWords(List<String> documents, Set<String> stopWords) {

public static List<Integer> documentLengthsParallel(List<String> documents) {

private static List<String> wordsIn(String document) {

private ThreadingDemo() {

public static void main(String[] args) throws ExecutionException, InterruptedException {

private static int countPrimesUpTo(int maxInclusive) {

private static boolean isPrime(int value) {

private AnswerVerifier() {

public static void main(String[] args) {

private static void expectEquals(Object expected, Object actual, String label) {

private static void expectThrows(Runnable action, String label) {

private ConcurrentStats() {

public static Map<String, Integer> countWordsSequential(List<String> documents) {

public static Map<String, Integer> countWordsParallel(List<String> documents) {

public static Map<String, Integer> mergeCounts(Map<String, Integer> left, Map<String, Integer> right) {

public static Map<String, Integer> mergeAll(List<Map<String, Integer>> maps) {

public static int totalWordCount(Map<String, Integer> counts) {

public static Optional<String> topWord(Map<String, Integer> counts) {

public static List<String> topWords(Map<String, Integer> counts, int limit) {

public static int countDocumentsContaining(List<String> documents, String word) {

public static Map<String, Integer> countWordsExcludingStopWords(List<String> documents, Set<String> stopWords) {

public static List<Integer> documentLengthsParallel(List<String> documents) {

private static List<String> wordsIn(String document) {

private ExerciseRunner() {

public static void main(String[] args) {

private ConcurrentStats() {

public static Map<String, Integer> countWordsSequential(List<String> documents) {

public static Map<String, Integer> countWordsParallel(List<String> documents) {

public static Map<String, Integer> mergeCounts(Map<String, Integer> left, Map<String, Integer> right) {

public static Map<String, Integer> mergeAll(List<Map<String, Integer>> maps) {

public static int totalWordCount(Map<String, Integer> counts) {

public static Optional<String> topWord(Map<String, Integer> counts) {

public static List<String> topWords(Map<String, Integer> counts, int limit) {

public static int countDocumentsContaining(List<String> documents, String word) {

public static Map<String, Integer> countWordsExcludingStopWords(List<String> documents, Set<String> stopWords) {

public static List<Integer> documentLengthsParallel(List<String> documents) {

private static List<String> wordsIn(String document) {