What you'll learn: By the end of this lesson you will be able to say which JVM memory areas belong to one thread and which are shared, explain what lands on the heap and when an
OutOfMemoryErrororStackOverflowErroris thrown, state what the Java memory model promises about one thread seeing another thread's writes (happens-before, volatile, monitors, final fields), explain why a program with a data race has more outcomes than you can predict by reading it, and use a Java lab that lists every interleaving of small programs to see this without a flaky test.
Picture an office where every person has a private notepad and the team shares one whiteboard. Your notepad is yours alone and cheap to use. The whiteboard is shared, so anything on it can be read, changed or wiped by anyone. Now suppose one colleague writes a figure on the whiteboard and then raises a hand, and you only trust the figure if you saw the raised hand first. The hand is a rule that connects her writing to your reading. Without the hand, she may have written the number, but nothing says you must already see it.
The JVM has the same two parts. Each thread has private memory (its call stack) and all threads share one heap. And the language has a rule, the Java memory model, that says which "raised hands" make one thread's writes visible to another. This lesson covers both: the run-time data areas that say where things live, and the happens-before rules that say when a write must be seen. The next lesson, Garbage Collectors: G1 and ZGC, covers how the heap is cleaned.
Verified with the Java Language Specification and Java Virtual Machine Specification for Java SE 25, the java.util.concurrent package documentation and the Oracle GC tuning guide, on 2026-11-16. Lab run with Java 25.
The core idea
Each Java thread has its own stack, all threads share one heap, and the memory model decides when a write by one thread must be visible to a read by another: only when the two actions are ordered by a happens-before edge. Without such an edge, the specification allows the reader to see an old value. Everything below is detail on one of those four clauses.
Three illustrations run through the lesson, each labelled:
- Minimal example: two threads incrementing a counter, listed schedule by schedule in the Java lab.
- Realistic example: ShopStream's catalogue service sharing a price snapshot between a refresher thread and request threads, in "In practice".
- Failure example: a
StackOverflowErrorthat ends one thread while the heap stays shared, plus the heap that runs out at 2 a.m.
The run-time data areas
The Java Virtual Machine Specification (section 2.5) lists the memory the JVM manages and separates it by who owns it. Some areas are created at start-up and live until the JVM ends; others are per thread.
| Area | Owner | What it holds | Failure the specification names |
|---|---|---|---|
pc register |
One per thread | The current instruction of that thread | None named |
| JVM stack | One per thread, created with the thread | A frame per method call | StackOverflowError if a larger stack than permitted is needed; OutOfMemoryError if memory for a new thread's stack cannot be made available |
| Native method stack | One per thread, optional | Support for native methods |
Both errors, in the same two situations |
| Heap | Shared by all threads, created at start-up | Objects; reclaimed by the garbage collector | OutOfMemoryError when a computation needs more heap than can be made available |
| Method area | Shared by all threads | Class-level data and compiled code; logically part of the heap | OutOfMemoryError when an allocation cannot be satisfied |
| Run-time constant pool | One per class or interface, taken from the method area | The class file's constants at run time | OutOfMemoryError if it cannot be built |
The specification says: "The Java Virtual Machine has a heap that is shared among all Java Virtual Machine threads." Heap storage "is reclaimed by an automatic storage management system (known as a garbage collector); objects are never explicitly deallocated", and no particular collector is assumed. Stacks and the heap may be of fixed size or may expand and contract.
Figure 1. What each thread owns and what all threads share. How to read this: the three threads on the left each carry their own stack (not drawn separately). Every arrow into the heap is a reference from a stack frame to an object. Only the heap and the method area are common to the three threads, which is why shared mutable objects are where concurrency bugs live.
A primitive local variable lives in a stack frame no other thread can see. A local that holds an object holds a reference; the object is on the heap, and two threads holding references to the same object share it.
Reachability and sizing
The Java Language Specification (12.6.1) defines the word the collector uses: "A reachable object is any object that can be accessed in any potential continuing computation from any live thread." The language does not say when storage is reclaimed once an object is unreachable. The java.lang.ref documentation adds that an object is strongly reachable if it can be reached without traversing a Reference object; everything in a normal object graph is.
The java command documents -Xmx (maximum heap size) and -Xms (minimum and initial heap size); the default maximum is "chosen at runtime based on system configuration", and "for server deployments, -Xms and -Xmx are often set to the same value". -Xss sets the thread stack size. At the time of writing for Java 25, -XX:MaxRAMPercentage defaults to 25 percent, and -XX:+UseContainerSupport (container limits detected) is documented as enabled by default. Set the heap deliberately instead of trusting a default you have not measured.
OutOfMemoryError is thrown "when the Java Virtual Machine cannot allocate an object because it is out of memory, and no more memory could be made available by the garbage collector". -XX:+HeapDumpOnOutOfMemoryError writes the heap to a file when the heap runs out; it is disabled by default.
The Java memory model: when does a thread see a write?
If thread 1 writes a variable and thread 2 reads it, what may thread 2 see? The intuitive answer is "the latest value", and the specification does not promise that for free. Chapter 17 of the JLS says that when two conflicting accesses (two accesses to the same variable, at least one a write) are not ordered by a happens-before relationship, the program contains a data race. The specification gives the guarantee only for programs without races: "If a program is correctly synchronized, then all executions of the program will appear to be sequentially consistent", where correctly synchronized means all sequentially consistent executions are free of data races.
Sequential consistency is the intuitive world: all actions occur in one total order consistent with each thread's program order. The specification then says why a real execution of a racy program can leave that world. About the textbook example (two threads, B = 1; r2 = A and A = 2; r1 = B, all starting at 0) it says the trace "can observe r2 == 0 and r1 == 0 and still be happens-before consistent", because "since there is no synchronization, each read can see either the write of the initial value or the write by the other thread". In no one-at-a-time ordering of the four steps can both reads return 0, yet the specification allows it.
The happens-before edges you rely on
| Edge | What the specification says |
|---|---|
| Program order | Within one thread, an action that comes first in program order happens-before a later one |
| Monitor | An unlock on a monitor happens-before every subsequent lock on that monitor |
| Volatile | A write to a volatile field happens-before every subsequent read of that field |
| Thread start | A call to start() happens-before any action in the started thread |
| Thread join | All actions in a thread happen-before another thread successfully returns from join() on it |
java.util.concurrent extends the same idea. Its package documentation lists, among others: actions before placing an object into any concurrent collection happen-before actions after removing it in another thread; actions before submitting a Runnable to an Executor happen-before its execution begins; actions of a task happen-before the retrieval of its result through Future.get(); and actions before Lock.unlock happen-before actions after a successful Lock.lock on the same lock.
The edges compose: a plain write then a volatile write in one thread, and a volatile read that sees it then a plain read in another, order the plain write before the plain read (Figure 2).
Figure 2. A volatile write publishes everything written before it. How to read this: the plain write comes first in the writer's program order, the volatile write follows it, and the reader's volatile read of the set flag creates the edge. If the reader had read data without first seeing ready, no edge would exist and nothing would be promised.
Atomicity and final fields
A single write to a non-volatile long or double is treated as two separate writes, while "writes and reads of volatile long and double values are always atomic", and reference reads and writes are always atomic (JLS 17.7). Final fields have their own rule (JLS 17.5): a thread that can only see a reference to an object after it is completely initialized "is guaranteed to see the correctly initialized values for that object's final fields", while a plain field beside it "could see 0". And a volatile field orders each single read or write; it does not make x = x + 1, a read followed by a write, atomic.
Build it: every schedule of a race, in Java
This is the minimal example. A real race is unreliable to reproduce, so the lab does not try to provoke one. Instead it lists every way two small programs can interleave under sequential consistency and counts the outcomes.
Goal. See why an unsynchronised x = x + 1 can lose an update, what one indivisible step changes, why the store-buffering outcome is missing from a sequentially consistent list yet allowed by the specification, and which hand-offs the language guarantees on real threads.
Setup. From the repository's examples/backend folder:
./gradlew :labs:jvm-memory-model:check --console=plain
./gradlew -q :labs:jvm-memory-model:run
The first command runs 10 tests. The second prints the table below. The code is in examples/backend/labs/jvm-memory-model/src/main/java/buildingai/labs/jvmmemorymodel/.
How it works. ScheduleExplorer walks every ordering of the threads' steps that keeps each thread's own order and counts the outcomes. Litmus holds four programs. Publication holds hand-offs with a guaranteed result: a plain field published through a volatile flag, a counter under one monitor, and a final field read through an unsynchronised reference. The tests assert only guaranteed outcomes, so none can flake. The racy versions (a stale plain field, a half-built object) are not run, because the specification allows them but does not make them happen on demand. One more test shows that a StackOverflowError ends only the thread whose stack is full while the heap stays shared.
Expected output, captured from a real run (Java 25.0.3, 2026-11-08):
Schedules of small programs under sequential consistency (one global order, program order kept).
A real JVM may also show outcomes that are NOT in these lists when the program has a data race (JLS 17.4.5).
1. Lost update, x = x + 1 in two threads, no lock
schedules: 6
x=1 in 4 of 6
x=2 in 2 of 6
2. Same increment inside one synchronized block
schedules: 2
x=2 in 2 of 2
3. Store buffering, plain fields: T1: B = 1; r2 = A T2: A = 2; r1 = B
schedules: 6
r1=0 r2=2 in 1 of 6
r1=1 r2=0 in 1 of 6
r1=1 r2=2 in 4 of 6
4. Message passing, flag and data: T1: data = 1; ready = 1 T2: r1 = ready; r2 = data
schedules: 6
r1=0 r2=0 in 1 of 6
r1=0 r2=1 in 4 of 6
r1=1 r2=1 in 1 of 6
Hand-offs with a guaranteed result (real threads):
plain field published through a volatile flag: reader saw 42
4 threads x 10000 increments under one monitor: 40000
final field read through an unsynchronised reference: 3
What the output shows. Scenario 1 counts schedules, not probabilities: four of six orderings lose an update. Scenario 2 treats the increment as one step, which one monitor gives. Scenario 3 never prints r1=0 r2=0, yet the specification's own example allows it for plain fields: the list models the world you imagine, and the gap is what a data race opens up. Scenario 4 never shows the flag without the data under sequential consistency; the volatile edge of Figure 2 is what promises that for a real program.
Break it. In Publication.VolatileFlag, remove volatile from ready. The tests will usually still pass on your machine, and that is the point: without the edge the language no longer promises that the plain field is visible when the flag is, and no test can prove the failure either way. Put it back. Then, in Litmus.lostUpdateUnderOneLock, split the step into a read step and a write step; the outcome list gains x=1.
Stretch. Add a third thread to the lost-update litmus and predict the number of schedules first.
What the model leaves out. Real hardware and compilers, the full formal memory model, and any claim about how often a race shows up.
Choosing how threads hand off data: the trade-offs
Figure 3. A first-pass choice for sharing a value. How to read this: start at the top and take the first branch that fits. Confinement and immutability avoid the question entirely; locks are for state that must change in place.
| Option | Gain | Cost | Wrong when |
|---|---|---|---|
| Thread confinement | No edge needed, no contention | One thread owns the data | Several threads must read it |
Immutable snapshot, final fields, replaced through a volatile reference |
Readers need no lock and see a fully built object | A new object per change | The object is huge and changes constantly |
volatile field |
Visibility and order for single reads and writes | Does not make x = x + 1 atomic |
You need a compound update |
synchronized or a Lock |
Mutual exclusion plus visibility | Waiting, deadlock risk | A hot path where threads queue behind one lock |
java.util.concurrent hand-offs (executors, futures, concurrent collections) |
The edge is built in | Must use their methods | You bypass them with a plain shared field |
In practice: ShopStream's price snapshot
This is the realistic example, an educational scenario on the course's running example ShopStream; nothing in it describes a real company. Every figure is illustrative.
This is a realistic scenario, not a case history.
The situation
The catalogue service answers product-page requests from a pool of request threads. Prices change several times an hour, so a background thread refreshes an in-memory price table from the database. The first version shares the table through a plain field that the refresher replaces and the request threads read. It passed every test and the team shipped it.
Starting architecture
Figure 4. One writer, many readers, one shared reference. How to read this: the refresher builds a complete new table and only then stores the reference. The question the memory model answers is what a request thread is allowed to see when it reads that reference.
Options considered
| Option | Behaviour | Risk |
|---|---|---|
| A. Plain field, replaced by the refresher | Works in every test | No happens-before edge: readers are not promised a fresh or fully built table |
| B. Lock around every read and write | Correct | Request threads queue behind one lock on the hottest path |
C. Immutable table with final fields, reference declared volatile |
Readers need no lock; the volatile write publishes the finished table | One new table per refresh |
The decision
Option C. The table is built, filled and then stored with one volatile write, and the table class has only final fields. The team writes the rule in the code comment: the table is never changed after the reference is stored. The reasoning is the lesson's Figure 2 with a bigger payload.
Rollout and verification
A test can only check outcomes the language guarantees, so the team's tests cover the guaranteed behaviour, as the lab does: a reader that sees the new reference sees a complete table. They do not try to prove the old version broken, since the specification allows the failure but does not make it appear on demand. In production they watch the snapshot's age (time since the last successful refresh), the refresher's failures and the heap used after collections.
The 2 a.m. failure
The page reads: catalogue pods restart every few hours with OutOfMemoryError. The cause is not the memory model. A later change made the refresher keep every previous table "for audit", all strongly reachable from a list, so each refresh adds a live table and the collector can reclaim none of them. The checks: look at heap use after each collection (it only climbs), enable the heap dump on out-of-memory and open it to see which collection holds the tables, and compare the flags -Xmx or MaxRAMPercentage with the container's limit. The mitigation is to drop the list and store only the latest snapshot. The lasting fix is a test that refreshes many times and asserts the number of retained tables, and an alert on heap use after collection trending upward.
Architect's notes
- Name the edge. For every value shared between threads, say which happens-before edge protects it. "It is just a field" is not an answer.
- Prefer immutable objects and confinement. They remove the question; locks and volatile answer it with care.
- Do not trust a passing test for a race. It saw one allowed outcome.
- Set the heap deliberately and read heap use after collections.
- Reference means retention. A cache or static map keeps objects reachable.
Common mistakes
- Sharing a plain field between threads and calling it fine because it worked locally.
- Using
volatilefor a counter. It gives visibility, not an atomic read-modify-write. - Publishing a half-built object by letting its reference escape from a constructor into a shared field.
- Catching
OutOfMemoryErrorand carrying on as if memory had been freed. - Keeping history in memory "just in case": every entry in a collection is a live object.
Key takeaways
- Each thread has a private stack and
pcregister; the heap and method area are shared. - Objects live on the heap, and the collector reclaims those no live thread can reach; the specification leaves the choice of collector to the implementation.
- A data race is two conflicting accesses with no happens-before edge between them; correctly synchronized programs behave as if sequentially consistent.
- The edges you use: program order, monitors, volatile, thread start and join, and the
java.util.concurrenthand-offs. - Final fields are safely visible after construction; a volatile read or write is atomic even for
longanddouble, but a compound update is not. - A test cannot prove a race absent; reason from the edges.
Practice exercises
Exercise 1 (20 min). For each variable in a small class you write (a counter, a config reference, a cached string), say whether it is shared and which happens-before edge protects it.
Exercise 2 (45 min). Run the lab. Predict the number of schedules for a lost update with three threads before running the stretch, and explain how it relates to the binomial count.
Exercise 3 (1 hour). Run "Break it". Explain why the test still passes with volatile removed, and what that says about testing races.
Exercise 4 (2 hours). For ShopStream's cart service, list every object shared between request threads, choose confinement, immutability or a lock for each, and write down what OutOfMemoryError would mean for the service.
Related reading
- Garbage Collectors: G1 and ZGC: how the heap this lesson describes is reclaimed.
- LRU Cache in Java: a shared mutable structure and its thread-safety choices.
- Latency vs Throughput: why a pause is a latency event.
- Backpressure: what to do when work arrives faster than memory and threads can absorb.
- Capacity and Cost: sizing memory is part of sizing the service.
Official documentation
- Java Language Specification, Java SE 25, chapter 17, Threads and Locks, and 12.6 Finalization (the definition of reachable).
- Java Virtual Machine Specification, Java SE 25, chapter 2, section 2.5 run-time data areas.
- Java SE 25 API:
java.util.concurrentpackage summary, memory consistency properties andjava.lang.ref. - Oracle, HotSpot Virtual Machine Garbage Collection Tuning Guide, Java SE 25: Ergonomics.
- Oracle, The
javacommand, Java SE 25.