Range over a function in Go: the loop body is a function the iterator calls, and everything else follows

What is actually going on

A function can now stand to the right of range. The specification explains what that means in one sentence:

So a range over a function is a call of that function. And the compiler turns the loop body into a separate function and passes it in as the argument. That argument is what gets called yield.

// what you wrote
for x := range f {
	...
}
 
// what it becomes
f(func(x T) bool {
	...
})

No theory is needed to check this: let the iterator print what it is doing and the body print what it got.

for v := range talking { ... }

    iterator: started
    iterator: calling yield(0)
  loop body: got 0
    iterator: yield returned true
    iterator: calling yield(1)
  loop body: got 1
    iterator: yield returned true
    iterator: calling yield(2)
  loop body: got 2
    iterator: yield returned true
    iterator: out of values, returning on my own

The lines alternate: the body ran between two lines of the iterator. There is only one way that happens — the body was called by the iterator itself.

All control passes through one value

The body became a function, and a function can only return a value. So everything the loop uses to control itself has to fit into the return value.

The first two rows are the same: to the iterator, continue and running to the end are one event. It does not know the words break and continue — it sees true or false.

What this means for you. If you write an iterator, the result of yield cannot be ignored:

// broken: the traversal continues whatever the body answered
for _, v := range s {
	yield(v)
}
 
// correct
for _, v := range s {
	if !yield(v) {
		return   // the body said stop
	}
}

The first version compiles and looks harmless. It crashes on the first break in somebody else's loop — with a panic whose text is below.

The main thing: a return from the body does not leave at once

The body is a function. You cannot return out of a function on behalf of whoever called it. And a return inside the loop has to leave the outer function, the one the loop is written in.

Calling a function whose loop body contains a return:

    iterator: opened the resource
    body: got 0
    body: got 1
    body: got 2
    body: doing a return
    iterator: yield returned false, returning
    iterator: CLOSED the resource (defer)

  the function returned: "a value from the loop body"

Look at the order. Nothing left the function after "doing a return". First yield returned false. Then the iterator finished. Then its defer ran. Only after that did the calling function return.

The compiler has nowhere to put that return: a live call of the iterator, with defer statements not yet run, sits between the body and the outer function. So a return in the body means "stop the loop and remember that we have to leave", and the leaving happens later.

This is what makes iterators worth writing. Because the iterator always gets to run its defer — on every exit from the body — cleanup inside it can be written the way it is written in any other function:

func lines(name string) iter.Seq[string] {
	return func(yield func(string) bool) {
		f, err := os.Open(name)
		if err != nil {
			return
		}
		defer f.Close()   // runs on every exit from the loop body
 
		sc := bufio.NewScanner(f)
		for sc.Scan() {
			if !yield(sc.Text()) {
				return
			}
		}
	}
}

The calling code does not need to know a file is open in there:

for line := range lines("access.log") {
	if strings.Contains(line, "panic") {
		return line   // the file closes itself
	}
}

A callback cannot do this: you can neither leave the outer function from inside it nor stop the traversal — it has nothing to return. That is the difference, and it is not cosmetic.

There is a subtlety here, and it decides where cleanup goes. On a return from the body the iterator gets control back and runs its own code after yield. On a panic in the body it does not: yield never returns, the panic unwinds straight through the iterator's frame, and of the iterator's own code only its defer runs. Measured:

    iterator: opened the resource
    body: panicking
    iterator: CLOSED the resource (defer)
    caller: recovered the panic: body panic

Hence the rule: cleanup goes in a defer, not in a line after yield. And put nothing but the exit after yield — on a return that line does run, and anything more expensive than checking a boolean is paid twice.

Four mistakes the runtime catches

All four happen while running, not at compile time.

yield after break:        runtime error: range function continued iteration after function for loop body returned false
yield after a panic:      runtime error: range function continued iteration after loop body panic
yield after the loop:     runtime error: range function continued iteration after whole loop exit
iterator ate the panic:   runtime error: range function recovered a loop body panic and did not resume panicking

The first three are about calling yield again. Every loop carries a state variable of its own, and every entry into the body is checked against it. That is why an iterator which saved yield and calls it later, or from another goroutine, fails predictably instead of corrupting data in silence.

The fourth is the one nobody arrives at on their own.

func bad(yield func(int) bool) {
	defer func() { _ = recover() }()   // looks like reasonable protection
	yield(0)
}

That defer is put there so the iterator will not bring the program down on a mistake of its own. But a panic from the body passes through the iterator's frame — the body was called from here — and this recover catches it too. From the outside the panic would simply have vanished. The runtime does not allow that.

Three rules follow: do not save yield; check its result and return on false; do not put a blanket defer recover() in an iterator.

The cost: zero or sixfold

The usual argument against iterators is that a function call per element is expensive. There are two answers, and they have to be read together.

The compiler can see which function will arrive:

It cannot:

Same iterator, same work. One thing changed: in the second case the compiler does not know which function will arrive and cannot inline it. A call per element appeared, and so did allocations.

A rule you can apply by eye. An iterator is free where the compiler sees the function at the loop: slices.Values(s) right in the loop header, your own iterator nearby, a short wrapper. It costs a call per element where the function arrives as a parameter of a large function, out of a variable, or out of a struct field.

Not "do not use iterators" but "do not hide an iterator behind an inlining boundary in a hot loop".

Honestly, about that tenth. In the first table the iterator rows came out slightly faster than the plain range, and the ranges did not overlap. It does not follow that an iterator is faster: these are two equivalent loops the compiler unrolled differently, and the sign of such a difference changes between versions. What does follow is different — the expected sixfold is simply not there.

Do not measure this with b.Loop

If you go and check the cost yourself, know about the trap.

The same two rows as in the first table, and a different answer. The cause is not the iterator but the measurement: since Go 1.24 the compiler does not inline calls inside the body of b.Loop. It is written in the compiler itself:

So a benchmark on b.Loop always shows only the expensive half — the one from the second table. Measure with a loop over b.N, and with -benchmem.

iter.Seq is just a name for a function type

Nothing new was added to the language:

type Seq[V any]     func(yield func(V) bool)
type Seq2[K, V any] func(yield func(K, V) bool)

So your iterator is no different from a library one. maps.Keys and maps.Values give a sequence over a map, slices.Values over a slice, and slices.All gives index-value pairs. Going back: slices.Collect gathers into a slice, slices.Sorted gathers and sorts. Hence the shortest way to walk a map in order — slices.Sorted(maps.Keys(m)).

One convention is worth keeping: a collection's traversal method is called All, and it returns an iter.Seq or an iter.Seq2. Then the calling code reads the same everywhere: for k, v := range c.All().

What is out of scope here

iter.Pull — the opposite direction, where you pull the next value yourself; that is a separate topic. And single-use iterators, the ones that cannot be traversed twice: none of the measurements here involve one.

The short list

• Check the result of yield and return on false.
• Put cleanup in the iterator's defer — it runs on every exit from the body.
• Put nothing but the exit after yield.
• Do not save yield and do not pass it to a goroutine.
• Do not put a blanket defer recover() in an iterator.
• Call a collection's traversal method All.
• In a hot loop, do not hide the iterator behind an inlining boundary.
• Do not benchmark iterators with b.Loop.

A mechanism the language does not contain

Go 1.23 made it legal to write for x := range f, where f is a function. The measurements in this article were taken on go1.24.7 — a toolchain on which the mechanism has not been news for a year.

The temptation to read it as sugar is strong: to the right of range you could already put a slice, a map, a channel and an integer, and now also a function — one more case in the same list. Except that the compiler unrolls the other cases into a loop, and turns this one inside out.

Synthesized means invented by the compiler — and it invents it out of your loop body. The comment in rewrite.go opens with exactly that: The basic idea is to rewrite

for x := range f {
	...
}

into

f(func(x T) bool {
	...
})

— and corrects itself on the very next line: But it's not usually that easy.

What follows is one place where it is not that easy per section. Each of them changes something about the code you will write.

The loop body is a function, and the iterator calls it

No theory is needed to check this: let the iterator print what it is doing and the body print what it got.

for v := range talking { ... }

    iterator: started
    iterator: calling yield(0)
  loop body: got 0
    iterator: yield returned true
    iterator: calling yield(1)
  loop body: got 1
    iterator: yield returned true
    iterator: calling yield(2)
  loop body: got 2
    iterator: yield returned true
    iterator: out of values, returning on my own

The lines alternate: the body ran between two lines of the iterator. There is only one way that can happen — the body was called by the iterator itself.

The same run prints the call stack from the body of two nested loops over functions, the outer one over one and the inner one over other:

0  main.frames
1  main.block1.one.block1-range2-range4
2  main.other
3  main.block1-range2
4  main.one
5  main.block1
6  main.main
7  runtime.main
8  runtime.goexit

Read bottom-up, the frames come in pairs: main.one is the iterator, main.block1-range2 is the body of the outer loop, main.other is the second iterator, main.block1.one.block1-range2-range4 is the body of the inner one. The compound name on the top frame is a trace of inlining: the compiler pulled one into block1 and built the name out of both.

So what. First, your loop body has a name and you will see it — in a panic trace, in a profile, in a debugger. A frame with a -rangeN suffix is not somebody else's code and not a runtime detail: it is the lines you wrote between the braces, and that name is how you find them.

Second, and this matters more: there is now somebody else's frame between your code before the loop and your code inside it. Everything that used to work across the body boundary in an ordinary loop — leaving the function, defer, a panic — now crosses a call boundary instead. The rest of the article is about what follows from that.

break is return false, continue is return true

The body became a function, and a function can only return a value. So everything the loop uses to control itself has to fit into a return value — and there is exactly one.

The first two rows are identical. From the iterator's point of view continue and running to the end are the same event, because both mean return true. The compiler says so outright:

The iter package states the same thing from the other side — the side of whoever writes the iterator:

So what. If you write an iterator, you have no right to ignore the result of yield. The line

for _, v := range s {
	yield(v)   // result thrown away — the iterator is broken
}

compiles and looks harmless, but it means "keep going whatever the body answers". The first break in somebody's loop turns that into a panic — which one exactly is two sections below. There is exactly one correct shape:

for _, v := range s {
	if !yield(v) {
		return   // the body said stop, so the traversal must stop
	}
}

A return from the body does not leave immediately

Here the mechanism stops being a harmless rearrangement of code. The body is a function; you cannot return out of a function on behalf of whoever called it. And a return in a loop body has to leave the outer function, the one the loop is written in.

Calling a function whose loop body contains a return:

    iterator: opened the resource
    body: got 0
    body: got 1
    body: got 2
    body: doing a return
    iterator: yield returned false, returning
    iterator: CLOSED the resource (defer)

  the function returned: "a value from the loop body"

Nothing left the function after the line "doing a return". First yield returned false. Then the iterator ran its own code after yield. Then its defer ran. And only after all of that did the calling function return — with the value the body asked for three lines earlier.

It cannot be otherwise, and that is worth spelling out. The compiler has nowhere to put that return: it cannot jump out of the body through the iterator's frame, because between them sits a live call with defer statements not yet run. So a return in the body means not "leave" but "stop the loop and remember that we have to leave afterwards": the exit is stored in a variable, and the exit itself is performed in the calling function, after the iterator has handed control back.

The specification describes the same thing from the contract side:

Note the word terminates: break is named as an example, not as the only case. A return from the body is a termination too, and it reaches the iterator the same way — as a false out of yield.

So what — and here the consequence is stronger than the fact. A deferred exit means the iterator always gets to run its defer. Not usually, not if the body behaved: always, on every exit from the body. And if that is so, cleanup inside an iterator can be written the way it is written in any other function:

func lines(name string) iter.Seq[string] {
	return func(yield func(string) bool) {
		f, err := os.Open(name)
		if err != nil {
			return
		}
		defer f.Close()   // runs on every exit from the loop body
 
		sc := bufio.NewScanner(f)
		for sc.Scan() {
			if !yield(sc.Text()) {
				return
			}
		}
	}
}

The calling code neither closes the file nor knows it exists:

for line := range lines("access.log") {
	if strings.Contains(line, "panic") {
		return line   // the file gets closed, though nobody asked for it
	}
}

This is why iterators are better than callbacks: a callback can neither stop the traversal nor leave the outer function — it has nothing to return — while an iterator allows both without handing ownership of the resource outwards. The mechanism is built this way for the sake of that property, and that property is exactly what gets lost when it is called sugar.

A panic reaches the iterator differently from a return

The word "always" above applies to defer — and to defer only. The distinction is small in itself, but it decides where cleanup goes, so it was measured separately. Same iterator, now with a line AFTER yield, and the body panics instead of returning:

The same experiment as above, with two differences: the iterator
has a line AFTER yield, and the body panics instead of returning.

    iterator: opened the resource
    body: panicking
    iterator: CLOSED the resource (defer)
    caller: recovered the panic: body panic

There is no "line AFTER yield" in the output. On a panic yield does not return control at all — the panic unwinds straight through the iterator's frame, and of the iterator's own code only its defer runs.

Hence the rule this experiment was set up for: cleanup goes in a defer, not in a line after yield. A line after yield will not run when the body panics; a defer runs in both cases. And the other half of the same rule: put nothing but the exit after yield — on a return from the body that line does run, and anything there more expensive than checking a boolean is paid twice.

Four mistakes the runtime catches

The contract "yield returned false, do not call it again" has an enforcer. All four violations are caught while running rather than at compile time, and each has its own text.

yield after break:        runtime error: range function continued iteration after function for loop body returned false
yield after a panic:      runtime error: range function continued iteration after loop body panic
yield after the loop:     runtime error: range function continued iteration after whole loop exit
iterator ate the panic:   runtime error: range function recovered a loop body panic and did not resume panicking

Where they come from is explained in the same place that describes the rewrite:

So every loop carries a state variable of its own, and every entry into the body is checked against it. That explains the first three texts and why they differ: the state distinguishes "the body said stop", "the body panicked" and "the loop is over entirely". A yield saved somewhere and called later, or from another goroutine, fails predictably and with a readable text instead of corrupting data in silence.

The fourth is the one nobody arrives at on their own. It is not about a repeated call at all:

func bad(yield func(int) bool) {
	defer func() { _ = recover() }()   // looks like reasonable protection
	yield(0)
}

That defer is written so the iterator will not bring the program down on a mistake of its own. But a panic from the loop body passes through the iterator's frame — the body was called from here — and this recover catches it too. From the outside that would look like a panic that vanished: the loop ended quietly, the calling function carried on, and a panic from its own code surfaced nowhere. The runtime does not allow that and fails itself, with the text range function recovered a loop body panic and did not resume panicking.

So what. Three rules, each straight out of those four lines.

• Do not save yield — not in a field, not in a package variable, not in a goroutine. It lives for exactly one traversal.
• Check the result of yield and return on false. That is not a style preference but the only shape that does not crash.
• Do not put a blanket defer recover() in an iterator. If you do need to catch your own panic, catch it around your own code rather than around yield, and always resume somebody else's.

Nesting and labels: not a jump but two stops in a row

A labelled break across two levels looks like a jump past the intermediate code. But there is nowhere to jump: two iterator frames sit between the levels, and both have to hand control back.

Two loops over functions, a labelled break out of the inner one:

      body: A1
      body: A2
      body: A3
      inner iterator: returned
      body: B1
      body: B2
      body: break Loop
      inner iterator: yield returned false
      inner iterator: returned
    outer iterator: yield returned false
    outer iterator: returned

It reads like this: the inner yield returned false, the inner iterator finished and left; the body of the outer loop returned false too, the outer iterator finished and left. Two stops in a row, each through its own yield.

The normal path is visible in the same output: after A3 the inner iterator returned on its own, with no false involved, and the next line is B1. The inner iterator's cleanup runs on every step of the outer loop, not once at the end.

So what. A labelled break out of a nested loop over functions is safe: the defer of both iterators will run. But the cost is worth remembering too — if the inner iterator opens a connection on every step of the outer loop, it closes one on every step as well, and nothing in the loop's own code shows that.

iter.Seq is a name for a function type, not a new entity

Nothing was added to the language for any of the above. The iter package contains two type declarations, and both are just names:

type Seq[V any]     func(yield func(V) bool)
type Seq2[K, V any] func(yield func(K, V) bool)

The package documentation defines an iterator in the words normally used for a callback:

The standard library rests on that and asks for nothing more. maps.Keys and maps.Values hand back an iter.Seq over a map, slices.Values over a slice, and slices.All gives index-value pairs as an iter.Seq2. Going the other way, slices.Collect gathers a sequence into a slice and slices.Sorted gathers and sorts it. This is why slices.Sorted(maps.Keys(m)) is the shortest way to walk a map in key order, and why it contains no new concept at all.

The run confirms all of it at once, including a hand-written collection:

slices.Sorted(maps.Keys(m))    -> [grusha sliva yabloko]
slices.Sorted(maps.Values(m))  -> [1 2 3]

for k, v := range (set{m}).All()   // All() returns an iter.Seq2
      grusha   3
      sliva    2
      yabloko  1

slices.Collect(slices.Values([]int{4,1,3})) -> [4 1 3]

for i, v := range slices.All([]string{"a", "b", "c"})
      0 a
      1 b
      2 c

So what. Because iter.Seq is the name of a function type, your own iterator is no different from a library one: it fits into slices.Collect, into slices.Sorted, into any third-party function that takes an iter.Seq. Write it as a function, not as an object with state.

And one convention worth holding to: a collection's traversal method is called All. That is what the iter package and the standard library call it, and it makes the calling code read the same everywhere: for k, v := range c.All().

The cost is not one number but two

Now the thing that most often postpones the whole mechanism: "a function call per element has to be expensive". There are two answers, six times apart.

First, the case where the compiler knows at the loop which function will arrive.

Now the same iterator and the same work, but the compiler cannot see the function: it arrives as a parameter of a function too large to inline, or it lives in a package variable.

These two blocks have to be read together. On its own each one misleads: by the first an iterator is always free, by the second always expensive. Neither is true. The very same line for v := range seq costs either nothing or a call per element, and what decides that is not the iterator but whether the compiler knows the function at the loop.

Hence a rule you can apply by eye, without a profiler.

• Free where the compiler sees the function: a literal or a call such as slices.Values(s) right in the loop header, your own iterator nearby, a short wrapper function that inlines whole.
• A call per element plus allocations where it does not: an iter.Seq arriving as a parameter of a large function, sitting in a variable, coming out of a struct field or an interface. The measurement covers two of those — a parameter of a non-inlinable function and a package variable; the rest are the same case for the same reason, that the compiler cannot name the function.

The practical conclusion is not "do not use iterators" but "do not hide an iterator behind a boundary the compiler will not cross, in a hot loop". In cold code, 25 microseconds per 10,000 elements is not worth a single rearrangement.

Key-value pairs need no separate discussion: iter.Seq2 behaves the same way.

About the tenth the iterator came out faster by

In the first block the iterator rows sit slightly below the plain range: 4108–4242 against 4782–4971. The ranges did not overlap, and that has to be said out loud rather than glossed over.

It does not follow that an iterator is faster than a plain range. These are two different but equivalent loops: the same sum, unrolled differently by the compiler on this machine. The sign of a difference like that changes between versions and between machines, and nothing can be built on it.

What does follow from the block is substantive: the expected sixfold is not there, and no row allocates. The same time and the same zero bytes show up in the last row as well — a traversal by callback, with no iterator at all. In this case the iterator adds nothing: no time, no memory.

The benchmarking trap: on b.Loop an iterator is always expensive

This section exists because after the previous one the reader will go and measure it, and on current Go will write a benchmark that lies.

b.Loop arrived as the recommended replacement for a loop over b.N — it keeps the timer itself and keeps the body from being optimized away. But since Go 1.24 the compiler does not inline calls inside its body:

For ordinary code this is a detail. For an iterator it decides everything, because its whole cost consists of whether the compiler inlined the function or not. Measuring on b.Loop disables inlining by force and therefore always shows only the expensive half — the one from the second cost block.

So what. If you are measuring the cost of an iterator, measure it with a loop over b.N, the way bench/goiter/cost_test.go does, and do not forget -benchmem: the allocation column says more here than the nanoseconds. And a benchmark of somebody else's showing that Go iterators are six times more expensive is worth checking for a b.Loop in its body first.

What is out of scope here

Two things are named so that you know they exist and do not look for them above.

iter.Pull — the opposite direction: turning an iterator into a pair of functions you pull yourself when you want the next value. It has its own construction and its own cost; it is a separate topic.

Single-use iterators — the ones that cannot be traversed twice because a consumable source sits behind them. None of the measurements here involve one, and every conclusion above applies to iterators that can be called again.

What to check in your own code

• Writing an iterator: check the result of yield and return on false. Ignoring it is not allowed — it compiles, then crashes on the first break in somebody else's loop.
• Put cleanup in the iterator's defer. It runs on every exit from the body, including a return from the middle and a panic. That is the main reason to write an iterator rather than a callback.
• Put nothing but the exit after yield. Anything else there also runs when the body leaves by return.
• Do not save yield — not in a field, not in a package variable, not in a goroutine: the runtime catches that and brings the program down.
• Do not put a blanket defer recover() in an iterator: it swallows your body's panic, and the runtime reports that with a panic of its own.
• Call a collection's traversal method All and return an iter.Seq or an iter.Seq2 from it — then your type slots into the same slices.Collect and slices.Sorted as everything else.
• In a hot loop, do not hide the iterator behind an inlining boundary: a parameter of a large function, a package variable, a struct field. There it costs a call per element and three allocations.
• Do not benchmark iterators with b.Loop. Inlining is off inside its body, and the answer will always be "expensive".

How to reproduce the numbers

Two scripts, answering different questions. bench/goiter/mechanics.go measures no time at all: it prints the order of calls, the stack, the panic texts and the output of the standard library. bench/goiter/cost_test.go together with bench/goiter/cost.sh measures the cost.

The directory is a separate Go module, so the tests run from inside it:

go run bench/goiter/mechanics.go
cd bench/goiter && ./cost.sh
cd bench/goiter && go test .

The third command is TestSameWork: it checks that every way of traversing produces the same sum. Without it the benchmark would be comparing different work and saying nothing about it — a row that accidentally walked half the slice would simply look fast.

cost.sh runs the benchmarks in interleaved rounds and prints the range across rounds rather than the best result. If the ranges of two rows overlap, there is no difference between them, however large it may look in a single run.

The published run: go1.24.7 linux/amd64, Intel Xeon 2.80 GHz. The mechanism arrived in Go 1.23 and the numbers were taken on 1.24.7 — on another version the absolute nanoseconds will differ. What will not change is the main thing: the B/op and allocs/op columns, and the fact that the whole gap between the two cost blocks rests on one circumstance, whether the compiler can see the function. The output of mechanics.go contains no numbers at all, so it reproduces verbatim.

What measured this

• bench/goiter/mechanics.go
• bench/goiter/cost_test.go
• bench/goiter/cost.sh