Цикл по функции в Go: тело — это функция, которую вызывает итератор, и отсюда всё остальное

Что вообще происходит

Справа от range теперь может стоять функция. Спецификация объясняет, что это значит, одной фразой:

То есть цикл по функции — это вызов этой функции. А тело цикла компилятор превращает в отдельную функцию и передаёт ей аргументом. Она и называется yield.

// то, что вы написали
for x := range f {
	...
}
 
// то, во что это превращается
f(func(x T) bool {
	...
})

Проверить это можно без всякой теории: пусть итератор печатает, что он делает, а тело — что получило.

1. ЦИКЛ ПО ФУНКЦИИ — ЭТО ВЫЗОВ ЭТОЙ ФУНКЦИИ
------------------------------------------------------------------
  for v := range talking { ... }

    итератор: начал работу
    итератор: зову yield(0)
  тело цикла: получил 0
    итератор: yield вернул true
    итератор: зову yield(1)
  тело цикла: получил 1
    итератор: yield вернул true
    итератор: зову yield(2)
  тело цикла: получил 2
    итератор: yield вернул true
    итератор: значения кончились, возвращаюсь сам

Строки чередуются: тело выполнилось между двумя строками итератора. Так бывает только в одном случае — если тело вызвал сам итератор.

Управление проходит через одно значение

Тело стало функцией, а функция умеет только вернуть значение. Значит, всё, чем цикл управляет собой, придётся уложить в возвращаемое значение.

2. BREAK — ЭТО RETURN FALSE, CONTINUE — ЭТО RETURN TRUE
------------------------------------------------------------------
  тело доработало до конца     шаг 0: yield вернул true
  тело доработало до конца     шаг 1: yield вернул true
  тело доработало до конца     шаг 2: yield вернул true

  тело сделало continue        шаг 0: yield вернул true
  тело сделало continue        шаг 1: yield вернул true
  тело сделало continue        шаг 2: yield вернул true

  тело сделало break           шаг 0: yield вернул false

Первые две группы совпали дословно: для итератора continue и «тело доработало до конца» — одно событие. Он не знает слов break и continue, он видит только true или false.

Что из этого следует для вас. Если вы пишете итератор, результат yield игнорировать нельзя:

// сломано: обход продолжится, что бы тело ни ответило
for _, v := range s {
	yield(v)
}
 
// правильно
for _, v := range s {
	if !yield(v) {
		return   // тело сказало «хватит»
	}
}

Первый вариант компилируется и выглядит безобидно. Он падает на первом же break в чужом цикле — паникой, текст которой приведён ниже.

Главное: return из тела не выходит сразу

Тело — это функция. Из функции нельзя вернуться за того, кто её вызвал. А return внутри цикла обязан выйти из внешней функции — той, где цикл стоит.

3. RETURN ИЗ ТЕЛА НЕ ВЫХОДИТ НЕМЕДЛЕННО
------------------------------------------------------------------
  Вызываем функцию, у которой внутри цикла стоит return:

    итератор: открыл ресурс
    тело: получил 0
    тело: получил 1
    тело: получил 2
    тело: делаю return
    итератор: yield вернул false, возвращаюсь
    итератор: ЗАКРЫЛ ресурс (defer)

  функция вернула: "значение из тела цикла"

Смотрите на порядок. После «делаю return» управление не ушло из функции. Сначала yield вернул false. Потом итератор доработал. Потом отработал его defer. И только после этого вернулась вызывающая функция.

Компилятору некуда деть этот return: между телом и внешней функцией стоит живой вызов итератора с невыполненными defer. Поэтому return в теле означает «останови цикл и запомни, что надо выйти», а сам выход происходит позже.

Ради этого итераторы и удобны. Раз итератор всегда доигрывает свои defer — при любом выходе из тела, — уборку внутри него можно писать как в обычной функции:

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()   // выполнится при любом выходе из тела цикла
 
		sc := bufio.NewScanner(f)
		for sc.Scan() {
			if !yield(sc.Text()) {
				return
			}
		}
	}
}

Вызывающему коду не надо знать, что там открыт файл:

for line := range lines("access.log") {
	if strings.Contains(line, "panic") {
		return line   // файл закроется сам
	}
}

Обратный вызов так не умеет: из него нельзя ни выйти наружу, ни прервать обход — возвращать ему нечего. В этом и разница, и она не косметическая.

А вот тут есть тонкость, которая решает, куда класть уборку. При return из тела итератор получает управление обратно и доигрывает свой код после yield. При панике в теле — не получает: yield не возвращает управление вовсе, паника разматывает кадр итератора насквозь, и из его кода выполняются только defer. Замерено:

    итератор: открыл ресурс
    тело: паникую
    итератор: ЗАКРЫЛ ресурс (defer)
    вызывающий: поймал панику: паника тела

Отсюда правило: уборка идёт в defer, а не в строку после yield. А после yield держите только выход — при return эта строка выполняется, и всё дороже проверки булева значения вы платите ещё раз.

Четыре ошибки, которые ловит рантайм

Все четыре — во время работы, а не при компиляции.

5. ЧЕТЫРЕ ОШИБКИ ИТЕРАТОРА, КОТОРЫЕ ЛОВИТ РАНТАЙМ
------------------------------------------------------------------
  yield после break:       runtime error: range function continued iteration after function for loop body returned false
  yield после паники:      runtime error: range function continued iteration after loop body panic
  yield после цикла:       runtime error: range function continued iteration after whole loop exit
  итератор съел панику:    runtime error: range function recovered a loop body panic and did not resume panicking

Первые три — про повторный вызов yield. У каждого цикла есть своя переменная состояния, и каждый вход в тело с ней сверяется. Поэтому итератор, который сохранил yield и зовёт его позже или из другой горутины, падает предсказуемо, а не портит данные молча.

Четвёртая — та, до которой не додумываются.

func bad(yield func(int) bool) {
	defer func() { _ = recover() }()   // выглядит как разумная защита
	yield(0)
}

Такой defer ставят, чтобы итератор не уронил программу на своей ошибке. Но паника из тела проходит через кадр итератора — тело вызвано отсюда, — и этот recover ловит её тоже. Снаружи паника просто исчезла бы. Рантайм этого не допускает.

Три правила отсюда: не сохраняйте yield; проверяйте его результат и выходите по false; не ставьте в итераторе общий defer recover().

Цена: ноль или в шесть раз

Обычный довод против итераторов — «вызов функции на каждый элемент дорог». Ответа два, и их надо читать вместе.

Компилятор видит, какая функция придёт:

8. КОГДА КОМПИЛЯТОР ВИДИТ ИТЕРАТОР, ОБХОД СТОИТ КАК ОБЫЧНЫЙ
------------------------------------------------------------------
                                     нс/оп         Б/оп   выдел.  кратно
  обычный range по срезу             4782-4971     0      0       x1.0
  range по slices.Values             4108-4242     0      0       x0.9
  range по рукописному iter.Seq      4024-4339     0      0       x0.8
  iter.Seq параметром функции        4030-4327     0      0       x0.8
  обратный вызов, без итератора      4027-4248     0      0       x0.8

Не видит:

9. КОГДА НЕ ВИДИТ, ПОЯВЛЯЕТСЯ ВЫЗОВ НА КАЖДЫЙ ЭЛЕМЕНТ
------------------------------------------------------------------
                                     нс/оп         Б/оп   выдел.  кратно
  обычный range по срезу             4716-4931     0      0       x1.0
  iter.Seq в функцию без вкладыв.    28820-29810   42     3       x6.0
  iter.Seq из пакетной переменной    29615-31949   42     3       x6.2

Итератор один и тот же, работа одна и та же. Изменилось одно: во втором случае компилятор не знает, какая функция придёт, и не может её вложить. Появились и вызов на элемент, и выделения памяти.

Правило, которое можно применять глазами. Итератор бесплатен там, где компилятор видит функцию в точке обхода: slices.Values(s) прямо в заголовке цикла, свой итератор рядом, короткая обёртка. Он стоит вызова на элемент там, где функция приходит параметром большой функции, из переменной или из поля структуры.

Не «не пользуйтесь итераторами», а «не прячьте итератор за границу вкладывания в горячем цикле».

Честно про десятую долю. В блоке 8 строки с итератором вышли чуть быстрее обычного range, и диапазоны не перекрылись. Из этого не следует, что итератор быстрее: это два равносильных цикла, которые компилятор развернул по-разному, и знак такой разницы меняется от версии к версии. Следует другое — ожидаемой шестикратности здесь нет вовсе.

Не меряйте это на b.Loop

Если пойдёте проверять цену у себя, знайте про ловушку.

11. ЛОВУШКА ЗАМЕРА: ВНУТРИ B.LOOP ВКЛАДЫВАНИЕ ВЫКЛЮЧЕНО
------------------------------------------------------------------
                                     нс/оп         Б/оп   выдел.  кратно
  обычный range, замер на b.Loop     6209-6769     0      0       x1.0
  slices.Values, замер на b.Loop     29275-33132   88     4       x4.7

Те же две строки, что в блоке 8, и другой ответ. Дело не в итераторе, а в замере: начиная с Go 1.24 компилятор не вкладывает вызовы внутри тела b.Loop. Это записано в самом компиляторе:

Значит, замер на b.Loop всегда показывает только дорогую половину — ту, что в блоке 9. Меряйте циклом по b.N и с -benchmem.

iter.Seq — это просто имя типа функции

В язык ничего нового не добавляли:

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

Поэтому ваш итератор ничем не отличается от библиотечного. maps.Keys и maps.Values дают последовательность по карте, slices.Values — по срезу, slices.All — пары «индекс, значение». В обратную сторону: slices.Collect собирает в срез, slices.Sorted собирает и сортирует. Отсюда самый короткий способ обойти карту по порядку — slices.Sorted(maps.Keys(m)).

Одно соглашение стоит соблюдать: метод обхода коллекции называется All, и возвращает он iter.Seq или iter.Seq2. Тогда вызывающий код читается одинаково у всех: for k, v := range c.All().

Что осталось за рамками

iter.Pull — обратное направление, когда следующее значение дёргаете вы сами; это отдельная тема. И одноразовые итераторы — те, которые нельзя обойти дважды: здесь их нет ни в одном замере.

Короткий список

• Проверяйте результат yield и выходите по false.
• Уборку кладите в defer итератора — она отработает при любом выходе из тела.
• После yield ставьте только выход.
• Не сохраняйте yield и не передавайте его в горутину.
• Не ставьте в итераторе общий defer recover().
• Метод обхода коллекции называйте All.
• В горячем цикле не прячьте итератор за границу вкладывания.
• Не меряйте итераторы на b.Loop.

Механизм, которого в языке нет

Go 1.23 разрешил писать for x := range f, где f — функция. Замеры в этой статье сняты на go1.24.7 — то есть на версии, где механизм уже год как не новость.

Соблазн прочитать это как сахар велик: справа от range стояли срез, карта, канал и число, теперь стоит ещё и функция — казалось бы, ещё один случай в том же списке. Но остальные случаи компилятор разворачивает в цикл, а этот — выворачивает наизнанку.

Синтезированная — то есть придуманная компилятором. Придумывает он её из вашего тела цикла. Комментарий в rewrite.go начинается ровно с этого: The basic idea is to rewrite (Основная идея — переписать)

for x := range f {
	...
}

в

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

— и следующей же строкой себя поправляет: But it's not usually that easy. (Но обычно всё не так просто.)

Дальше — по одному месту, где «не так просто», на раздел. Каждое из них что-нибудь меняет в том, как вы напишете код.

Тело цикла — это функция, и вызывает её итератор

Проверяется это без всякой теории: пусть итератор печатает, что он делает, а тело — что получило.

1. ЦИКЛ ПО ФУНКЦИИ — ЭТО ВЫЗОВ ЭТОЙ ФУНКЦИИ
------------------------------------------------------------------
  for v := range talking { ... }

    итератор: начал работу
    итератор: зову yield(0)
  тело цикла: получил 0
    итератор: yield вернул true
    итератор: зову yield(1)
  тело цикла: получил 1
    итератор: yield вернул true
    итератор: зову yield(2)
  тело цикла: получил 2
    итератор: yield вернул true
    итератор: значения кончились, возвращаюсь сам

  Печать итератора и печать тела чередуются: тело выполнилось
  МЕЖДУ двумя строками итератора. Так может быть только в
  одном случае — если тело вызвал сам итератор.

  Стек вызовов из тела двух вложенных циклов по функциям
  (внешний идёт по one, внутренний по 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

Стек читается снизу вверх, и кадры в нём идут парами: main.one — итератор, main.block1-range2 — тело внешнего цикла, main.other — второй итератор, main.block1.one.block1-range2-range4 — тело внутреннего. Составное имя у верхнего кадра — след вкладывания: компилятор втянул one внутрь block1 и собрал имя из обоих.

И что с того. Во-первых, у вашего тела цикла есть имя, и вы его увидите — в трассировке паники, в профиле, в отладчике. Кадр с суффиксом -rangeN — не чужой код и не деталь рантайма: это строки, которые вы написали между фигурными скобками, и искать их надо по этому имени.

Во-вторых, и это важнее: между вашим кодом до цикла и вашим кодом внутри цикла теперь стоит чужой кадр. Всё, что в обычном цикле работало «через границу тела» — выход из функции, defer, паника, — теперь пересекает границу вызова. Дальше вся статья про то, что из этого следует.

break — это return false, continue — это return true

Тело стало функцией, а функция умеет только вернуть значение. Значит, всё, чем цикл управляет собой, надо уместить в возвращаемое значение — и оно там одно.

2. BREAK — ЭТО RETURN FALSE, CONTINUE — ЭТО RETURN TRUE
------------------------------------------------------------------
  тело доработало до конца     шаг 0: yield вернул true
  тело доработало до конца     шаг 1: yield вернул true
  тело доработало до конца     шаг 2: yield вернул true

  тело сделало continue        шаг 0: yield вернул true
  тело сделало continue        шаг 1: yield вернул true
  тело сделало continue        шаг 2: yield вернул true

  тело сделало break           шаг 0: yield вернул false

Первые две группы совпадают дословно. С точки зрения итератора continue и «тело доработало до конца» — одно и то же событие, потому что и то и другое означает return true. Компилятор про это говорит прямо:

Ту же вещь с другой стороны — со стороны того, кто итератор пишет, — формулирует пакет iter:

И что с того. Если вы пишете итератор, у вас нет права игнорировать результат yield. Строка

for _, v := range s {
	yield(v)   // результат выброшен — итератор сломан
}

компилируется и выглядит безобидно, но означает «продолжать обход, что бы тело ни ответило». Первый же break в чужом цикле превратит это в панику — какую именно, показано двумя разделами ниже. Правильная форма ровно одна:

for _, v := range s {
	if !yield(v) {
		return   // тело сказало «хватит» — обход обязан прекратиться
	}
}

return из тела не выходит немедленно

Здесь механизм перестаёт быть безобидной перестановкой кода. Тело — это функция; из функции нельзя вернуться за того, кто её вызвал. А return в теле цикла обязан выйти из внешней функции — той, где стоит цикл.

3. RETURN ИЗ ТЕЛА НЕ ВЫХОДИТ НЕМЕДЛЕННО
------------------------------------------------------------------
  Вызываем функцию, у которой внутри цикла стоит return:

    итератор: открыл ресурс
    тело: получил 0
    тело: получил 1
    тело: получил 2
    тело: делаю return
    итератор: yield вернул false, возвращаюсь
    итератор: ЗАКРЫЛ ресурс (defer)

  функция вернула: "значение из тела цикла"

Порядок строк здесь — весь результат. После «делаю return» управление не ушло из функции. Сначала yield вернул false. Потом итератор доработал свой код после yield. Потом отработал его defer. И только после этого вернулась вызывающая функция — со значением, которое тело просило вернуть три строки назад.

Иначе быть не может, и это стоит проговорить до конца. Компилятору некуда деть return: он не может выпрыгнуть из тела через кадр итератора, потому что между ними живой вызов с ещё не выполненными defer. Поэтому return в теле означает не «выйти», а «остановить цикл и запомнить, что после него надо выйти»: код выхода уходит в переменную, а сам выход выполняется в вызывающей функции — уже после того, как итератор вернул управление.

Спецификация ту же вещь описывает со стороны договора:

Обратите внимание на слово terminates: break назван примером, а не единственным случаем. return из тела — такое же завершение, и приходит к итератору тем же способом: как false из yield.

И что с того, а это здесь сильнее самого факта. Отсроченный выход означает, что итератор всегда доигрывает свои defer. Не «обычно», не «если тело вело себя прилично» — всегда, при любом выходе из тела. А раз так, уборку внутри итератора можно делать так же, как в обычной функции:

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()   // отработает при любом выходе из тела цикла
 
		sc := bufio.NewScanner(f)
		for sc.Scan() {
			if !yield(sc.Text()) {
				return
			}
		}
	}
}

Вызывающему коду не надо ни закрывать файл, ни знать, что он есть:

for line := range lines("access.log") {
	if strings.Contains(line, "panic") {
		return line   // файл закроется, хотя закрывать его никто не просил
	}
}

Это и есть причина, по которой итераторы удобнее обратных вызовов: обратный вызов не может ни прервать обход, ни выйти из внешней функции — возвращать ему нечего, — а итератор и то и другое разрешает, не отдавая наружу владение ресурсом. Ради этого механизм и устроен так, как устроен, и именно эта черта пропадает, когда его называют сахаром.

Паника приходит к итератору не так, как return

Слово «всегда» выше относится к defer — и только к нему. Само по себе это различие мелкое, но оно решает, куда класть уборку, поэтому измерено отдельно. Тот же итератор, но со строкой ПОСЛЕ yield, и тело не возвращается, а паникует:

4. ПАНИКА ПРИХОДИТ К ИТЕРАТОРУ НЕ ТАК, КАК RETURN
------------------------------------------------------------------
  Тот же опыт, что в блоке 3, с двумя отличиями: у итератора
  есть строка ПОСЛЕ yield, а тело вместо return паникует.

    итератор: открыл ресурс
    тело: паникую
    итератор: ЗАКРЫЛ ресурс (defer)
    вызывающий: поймал панику: паника тела

Строки «ПОСЛЕ yield» в выводе нет. При панике yield не возвращает управление вовсе — паника разматывает кадр итератора насквозь, и из его кода выполняются только defer.

Отсюда правило, ради которого этот опыт и поставлен: уборка идёт в defer, а не в строку после yield. Строка после yield не выполнится при панике тела; defer выполнится и там и там. И вторая половина того же правила: после yield вообще стоит держать только выход — при return из тела эта строка выполняется, и всё, что там стоит дороже проверки булева значения, вы платите ещё раз.

Четыре ошибки, которые ловит рантайм

У договора «yield вернул false — больше не звать» есть исполнитель. Все четыре нарушения ловятся во время работы, а не при компиляции, и текст ошибки в каждом случае свой.

5. ЧЕТЫРЕ ОШИБКИ ИТЕРАТОРА, КОТОРЫЕ ЛОВИТ РАНТАЙМ
------------------------------------------------------------------
  yield после break:       runtime error: range function continued iteration after function for loop body returned false
  yield после паники:      runtime error: range function continued iteration after loop body panic
  yield после цикла:       runtime error: range function continued iteration after whole loop exit
  итератор съел панику:    runtime error: range function recovered a loop body panic and did not resume panicking

Откуда они берутся, компилятор объясняет там же, где описывает переписывание:

То есть у каждого цикла — своя переменная состояния, и каждый вход в тело сверяется с ней. Это объясняет и первые три текста, и то, почему они разные: состояние различает «тело сказало стоп», «тело паникнуло» и «цикл вообще кончился». Сохранённый где-то yield, позванный позже или из другой горутины, падает предсказуемо и с внятным текстом, а не портит данные молча.

Четвёртая — та, до которой не додумываются. Она не про повторный вызов вовсе:

func bad(yield func(int) bool) {
	defer func() { _ = recover() }()   // выглядит как разумная защита
	yield(0)
}

Такой defer пишут, чтобы итератор не уронил программу на своей собственной ошибке. Но паника из тела цикла проходит через кадр итератора — тело же вызвано отсюда, — и этот recover ловит её тоже. Снаружи это выглядело бы как исчезнувшая паника: цикл молча закончился, вызывающая функция поехала дальше, а panic из её собственного кода нигде не всплыл. Рантайм такого не допускает и падает сам, с текстом range function recovered a loop body panic and did not resume panicking.

И что с того. Три правила, каждое прямо из этих четырёх строк.

• Не сохраняйте yield — ни в поле, ни в пакетной переменной, ни в горутине. Он живёт ровно один обход.
• Проверяйте результат yield и выходите по false. Это не стиль, а единственная форма, которая не падает.
• Не ставьте в итераторе общий defer recover(). Если ловить свою панику всё-таки надо, ловите её вокруг своего кода, а не вокруг yield, и обязательно поднимайте чужую снова.

Вложенность и метки: не прыжок, а две остановки

break с меткой через два уровня выглядит как прыжок мимо промежуточного кода. Но прыгать некуда: между уровнями стоят кадры двух итераторов, и обоим надо вернуть управление.

6. ВЛОЖЕННЫЕ ЦИКЛЫ И BREAK С МЕТКОЙ
------------------------------------------------------------------
  Два цикла по функциям, break с меткой из внутреннего:

      тело: A1
      тело: A2
      тело: A3
      внутренний итератор: вернулся
      тело: B1
      тело: B2
      тело: break Loop
      внутренний итератор: yield вернул false
      внутренний итератор: вернулся
    внешний итератор: yield вернул false
    внешний итератор: вернулся

Читается это так: внутренний yield вернул false, внутренний итератор доиграл и вышел; тело внешнего цикла тоже вернуло false, внешний итератор доиграл и вышел. Две остановки подряд, каждая по своему yield.

Заодно видно поведение внутреннего цикла при нормальном ходе: после A3 внутренний итератор вернулся сам, без всякого false, и следующая же строка — B1. Уборка внутреннего итератора выполняется на каждом шаге внешнего, а не один раз в конце.

И что с того. break с меткой из вложенного цикла по функциям безопасен: defer обоих итераторов выполнится. Но помнить стоит и цену — если внутренний итератор на каждом шаге внешнего открывает соединение, он его на каждом шаге и закроет, и по коду цикла этого не видно.

iter.Seq — это имя типа функции, а не новая сущность

В язык для всего перечисленного не добавили ничего. Пакет iter содержит два объявления типов, и оба — просто имена:

7. ITER.SEQ2 И СТАНДАРТНАЯ БИБЛИОТЕКА
------------------------------------------------------------------
  Два типа, и оба — просто имена для функций:

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

  slices.Sorted(maps.Keys(m)): [груша слива яблоко]
  slices.Sorted(maps.Values(m)): [1 2 3]

  Метод All() коллекции возвращает iter.Seq2, и по нему
  ходят обычным for ... range с двумя переменными:

      груша    3
      слива    2
      яблоко   1

  slices.Collect собирает последовательность обратно в срез:
      slices.Collect((set{m}).All() по ключам) -> [груша слива яблоко]
      slices.Collect(slices.Values([]int{4,1,3})) -> [4 1 3]

  slices.All даёт пары «индекс, значение» для среза:
      0 a
      1 b
      2 c

Документация пакета определяет итератор теми же словами, какими описывают обратный вызов:

Стандартная библиотека держится на этом и ничего больше не требует. maps.Keys и maps.Values отдают iter.Seq по карте, slices.Values — по срезу, slices.All — пары «индекс, значение» как iter.Seq2. В обратную сторону работают slices.Collect, который собирает последовательность в срез, и slices.Sorted, который собирает и сортирует. Именно поэтому slices.Sorted(maps.Keys(m)) — самый короткий способ обойти карту по отсортированным ключам, и в нём нет ни одного нового понятия.

И что с того. Раз iter.Seq — это имя типа функции, ваш собственный итератор ничем не отличается от библиотечного: он подходит в slices.Collect, в slices.Sorted, в любую чужую функцию, принимающую iter.Seq. Писать его надо как функцию, а не как объект с состоянием.

И одно соглашение, за которое стоит держаться: метод обхода коллекции называется All. Так его называют в пакете iter и в стандартной библиотеке, и вызывающий код от этого читается одинаково у всех: for k, v := range c.All().

Цена — не одно число, а два

Теперь то, ради чего механизм чаще всего откладывают: «вызов функции на каждый элемент — это же дорого». Ответа два, и они отличаются в шесть раз.

Сначала случай, когда компилятор в точке обхода знает, какая функция придёт.

8. КОГДА КОМПИЛЯТОР ВИДИТ ИТЕРАТОР, ОБХОД СТОИТ КАК ОБЫЧНЫЙ
------------------------------------------------------------------
                                     нс/оп         Б/оп   выдел.  кратно
  обычный range по срезу             4782-4971     0      0       x1.0
  range по slices.Values             4108-4242     0      0       x0.9
  range по рукописному iter.Seq      4024-4339     0      0       x0.8
  iter.Seq параметром функции        4030-4327     0      0       x0.8
  обратный вызов, без итератора      4027-4248     0      0       x0.8

  Ни одного выделения памяти и то же время, что у обычного range.
  Компилятор вложил и итератор, и тело: вызова на элемент не осталось.

Теперь тот же итератор и та же работа, но компилятор функцию не видит: она приходит параметром в функцию, которая не помещается в бюджет вкладывания, или лежит в пакетной переменной.

9. КОГДА НЕ ВИДИТ, ПОЯВЛЯЕТСЯ ВЫЗОВ НА КАЖДЫЙ ЭЛЕМЕНТ
------------------------------------------------------------------
                                     нс/оп         Б/оп   выдел.  кратно
  обычный range по срезу             4716-4931     0      0       x1.0
  iter.Seq в функцию без вкладыв.    28820-29810   42     3       x6.0
  iter.Seq из пакетной переменной    29615-31949   42     3       x6.2

  Та же работа и тот же итератор. Изменилось одно: компилятор больше не
  знает, какая функция придёт, и не может её вложить. Появились и вызов
  на элемент, и выделения памяти под замыкание.

Эти два блока обязаны читаться вместе. Поодиночке каждый вводит в заблуждение: по первому итератор бесплатен всегда, по второму дорог всегда. Верно ни то ни другое. Одна и та же строка for v := range seq стоит либо ноль, либо вызов на каждый элемент, и решает это не итератор, а то, известна ли компилятору функция в точке обхода.

Отсюда правило, которое можно применять глазами, без профилировщика.

• Бесплатно там, где компилятор видит функцию: литерал или вызов вроде slices.Values(s) прямо в заголовке цикла, свой итератор рядом, короткая функция-обёртка, которая целиком вкладывается.
• Вызов на элемент и выделения там, где не видит: iter.Seq пришёл параметром в большую функцию, лежит в переменной, приходит из поля структуры или из интерфейса. Замер закрывает два таких случая из перечисленных — параметр невкладываемой функции и пакетную переменную; остальные — тот же случай по той же причине: компилятор не может назвать функцию по имени.

Практический вывод не «не пользуйтесь итераторами», а «не прячьте итератор за границу, которую компилятор не переступает, в горячем цикле». В холодном коде разница в 25 микросекунд на 10 000 элементов не стоит ни одной перестановки.

Про пары «ключ — значение» отдельного разговора не нужно: iter.Seq2 ведёт себя так же.

10. ПАРА КЛЮЧ-ЗНАЧЕНИЕ
------------------------------------------------------------------
                                     нс/оп         Б/оп   выдел.  кратно
  обычный range по срезу с индексом  4764-5186     0      0       x1.0
  range по slices.All (iter.Seq2)    4752-4950     0      0       x1.0

Про десятую долю, на которую итератор оказался быстрее

В блоке 8 строки с итератором идут чуть ниже обычного range: 4108–4242 против 4782–4971. Диапазоны не перекрылись, и это надо сказать вслух, а не замолчать.

Из этого не следует, что итератор быстрее обычного range. Это два разных, но равносильных цикла: одна и та же сумма, разные развёртки, которые компилятор выбрал на этой машине. Знак такой разницы меняется от версии к версии и от машины к машине, и строить на нём нечего.

Следует из блока другое, и это как раз содержательно: ожидаемой шестикратности здесь нет, и выделений нет ни у одной строки. Ровно то же время и ноль байт показывает и последняя строка — обход обратным вызовом, без всякого итератора. То есть в этом случае итератор не добавляет ничего: ни времени, ни памяти.

Ловушка замера: на b.Loop итератор всегда дорогой

Этот раздел нужен потому, что читатель после предыдущего пойдёт мерить у себя — и на нынешнем Go напишет замер, который соврёт.

11. ЛОВУШКА ЗАМЕРА: ВНУТРИ B.LOOP ВКЛАДЫВАНИЕ ВЫКЛЮЧЕНО
------------------------------------------------------------------
                                     нс/оп         Б/оп   выдел.  кратно
  обычный range, замер на b.Loop     6209-6769     0      0       x1.0
  slices.Values, замер на b.Loop     29275-33132   88     4       x4.7

  Те же две строки, что в блоке 8, и другой ответ. Причина не в
  итераторе, а в замере: компилятор не вкладывает вызовы внутри тела
  b.Loop. Это записано в самом компиляторе, в
  cmd/compile/internal/inline/interleaved/interleaved.go:
  «No inlining nor devirtualization performed on b.Loop body».

b.Loop появился как рекомендуемая замена циклу по b.N — он сам держит таймер и сам не даёт выбросить тело. Но начиная с Go 1.24 компилятор не вкладывает вызовы внутри его тела:

Для обычного кода это мелочь. Для итератора — определяющее обстоятельство: вся его цена и состоит в том, вложил компилятор функцию или нет. Замер на b.Loop выключает вкладывание принудительно и потому всегда показывает только дорогую половину — ту, что в блоке 9.

И что с того. Если вы меряете цену итератора, меряйте её циклом по b.N, как это сделано в bench/goiter/cost_test.go, и не забудьте -benchmem: столбец выделений здесь говорит больше, чем наносекунды. А чужой замер, показывающий, что итераторы в Go дороги в шесть раз, стоит первым делом проверить на предмет b.Loop в теле.

Что осталось за рамками

Две вещи названы, чтобы вы знали, что они есть, и не искали их выше.

iter.Pull — обратное направление: превращение итератора в пару функций, которые вы дёргаете сами, когда вам нужно следующее значение. Устройство у него своё и цена своя; это отдельная тема.

Одноразовые итераторы — те, которые нельзя обойти дважды, потому что за ними стоит расходуемый источник. Здесь их нет ни в одном замере, и все приведённые выводы касаются итераторов, которые можно позвать снова.

Что стоит проверять в своём коде

• Пишете итератор — проверяйте результат yield и выходите по false. Игнорировать его нельзя: компилируется, но падает на первом же break в чужом цикле.
• Уборку кладите в defer итератора. Она отработает при любом выходе из тела, включая return из середины и панику. Это главная причина писать итератор, а не обратный вызов.
• После yield в итераторе ставьте только выход. Всё, что стоит там ещё, выполнится и при выходе тела по return.
• Не сохраняйте yield — ни в поле, ни в пакетной переменной, ни в горутине: рантайм это ловит и роняет программу.
• Не ставьте в итераторе общий defer recover(): он съест панику вашего тела, и рантайм об этом сообщит отдельной паникой.
• Метод обхода коллекции называйте All и возвращайте из него iter.Seq или iter.Seq2 — тогда ваш тип встанет в те же slices.Collect и slices.Sorted.
• В горячем цикле не прячьте итератор за границу вкладывания: параметр большой функции, пакетная переменная, поле структуры. Там он стоит вызова на каждый элемент и трёх выделений.
• Не меряйте итераторы на b.Loop. Внутри его тела вкладывание выключено, и ответ всегда будет «дорого».

Как воспроизвести числа

Два скрипта, и они отвечают на разные вопросы. bench/goiter/mechanics.go не меряет времени вовсе: он печатает порядок вызовов, стек, тексты паник и вывод стандартной библиотеки — блоки 1–7. bench/goiter/cost_test.go вместе с bench/goiter/cost.sh меряет цену — блоки 8–11.

Каталог — отдельный модуль Go, поэтому тесты запускаются из него:

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

Третья команда — это TestSameWork: она проверяет, что все способы обхода дают одну и ту же сумму. Без неё замер сравнивал бы разную работу и молчал об этом: строка, случайно обходящая половину среза, выглядела бы просто быстрой.

cost.sh гоняет бенчмарки чередующимися раундами и печатает диапазон по раундам, а не лучший результат. Если диапазоны двух строк перекрылись, разницы между ними нет, сколько бы её ни казалось по одному прогону.

Опубликованный прогон: go1.24.7 linux/amd64, Intel Xeon 2,80 ГГц. Механизм появился в Go 1.23, а числа сняты на 1.24.7 — на другой версии абсолютные наносекунды будут другими. Не изменится главное: столбцы Б/оп и выдел. и то, что разница между блоками 7 и 8 держится на одном обстоятельстве — видит компилятор функцию или нет. В выводе mechanics.go чисел нет вовсе, поэтому он воспроизводится дословно.

Чем измерено

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