Tracing Stack and Heap Values in Rust

Hello! In the first module, you wrote functions and worked with values such as integers, arrays, and structs. This module asks a new question: where does a value live while the program runs? That question will help explain Rust’s rules for ownership and borrowing later on.

Today you’ll trace a small program’s stack frames, heap allocation, and string data. The goal is not to memorize machine addresses. It is to look at a Rust value and identify which parts have a fixed size, which parts need storage allocated at runtime, and what happens when a function returns.

Two kinds of storage

The stack holds function-call frames. A frame provides space for a function’s local values and other information needed for the call. Frames follow a last-in, first-out pattern: if main calls measure, the measure frame is the first of those two frames to finish.

The heap provides storage requested while the program runs. Unlike a stack frame, a heap allocation can hold data whose required size is determined at runtime. Allocating it involves finding a suitable region of memory and keeping track of that region until it can be released.

Watch these short animations before reading the more precise account below.

The Rust book gives the underlying model. Its description of stack storage applies to values with a known, fixed size; it does not mean that every fixed-size value must be on the stack.

A useful rule for tracing code is: locate the value, then locate any data it points to. Those may be in different places. For example, an integer local can be represented entirely within a function’s frame. A String local has a fixed-size part in the frame, but its text is normally in a separate heap allocation.

A String has two locations to trace

Consider:

let mut name = String::from("rust");
name.push_str(" api");

A String value contains three pieces of information: a pointer to its text buffer, the length of the text currently stored there, and the buffer’s capacity. This fixed-size information can reside in a stack frame. The buffer containing the UTF-8 bytes of rust api resides on the heap.

Length and capacity are measured in bytes. After the append, the length here is 8 bytes. The capacity is at least 8, but you should not guess its exact value: the implementation may reserve extra room. Appending might also require a new, larger heap allocation if the old buffer cannot hold the additional text.

The supplied diagram is useful if you read its right-hand side as a picture of a value and the bytes it points to:

That last distinction matters. A string literal such as "api" has type &str. You can think of the &str value as a pointer and a length: it describes some text but does not own a growable buffer. The bytes of a string literal are stored with the compiled program, not in a new heap allocation each time the literal is used. A &str can also point to bytes inside a String’s heap buffer. We’ll study the borrowing rules that make this safe in later lessons; for now, just trace the view separately from the bytes it describes.

Trace a complete program

Here is a small program using types you have already encountered:

fn measure(label: &str) -> usize {
    let overhead: usize = 2;
    label.len() + overhead
}

fn main() {
    let count: i32 = 7;
    let points: [i32; 3] = [4, 5, 6];
    let literal: &str = "api";

    let mut name = String::from("rust");
    name.push_str(" api");

    let size = measure(name.as_str());
    println!("{count} {points:?} {literal} {name} {size}");
}

Read it in snapshots rather than trying to imagine all memory at once.

Before measure is called, main has a stack frame. In the straightforward memory model, count and the three elements of points fit within fixed-size local storage. literal is a fixed-size view; its "api" bytes belong to the program’s literal data, not to main’s stack frame. name has its pointer, length, and capacity in main’s frame, while its rust api bytes are in a heap buffer.

While measure runs, it has its own stack frame. name.as_str() supplies a &str view of name’s text. The parameter label describes the same eight bytes in the heap buffer; calling measure does not create a second copy of that text. The local overhead is a fixed-size usize. The function calculates 8 plus 2 and returns the usize value 10.

After measure returns, its frame is gone. The size value in main is 10, and main can still use name: the heap text was not part of the temporary measure frame. Once main finishes and name goes out of scope, Rust arranges for the allocation owned by the String to be released. The exact ownership rule behind that cleanup is a topic for the next lesson.

This is a conceptual tracing model, not a promise about each machine instruction. An optimizing compiler may keep a small local in a register or inline a function. Conversely, a fixed-size value can be placed in heap storage as part of a heap-allocated container. Stack versus heap tells you about storage in the model; it is not a type label that permanently attaches to every integer or string.

What to carry forward

When tracing a Rust program, separate three questions: What is the value’s fixed-size representation? Where is any data it points to? Which function call or allocation keeps that storage available? For an integer local, the first question may be enough. For a String or &str, answering only “stack” or “heap” misses an important part of the picture.

Next, you’ll use this layout to predict what assignment and function calls do to values—and why copying an integer is different from transferring a String.