[ci skip] document that multiple yield in inline iterator cause code bloat

[timotheecour]

• this documents that multiple yield in inline iterator cause code bloat

it's probably by design and not a bug but should be documented as it's a gotcha; see example below:

/cc @Araq

iterator myiter(): int =
  yield 10
  yield 11

proc main()=
  for a in myiter():
    echo "done"
main()

generates with --embedsrc -d:release:

N_LIB_PRIVATE N_NIMCALL(void, main_audQMEKlkQTCwd9cxcZvVCg)(void) {
	{
		NI a;
		a = (NI)0;
//    for a in myiter():
		a = ((NI) 10);
//      echo "done"
		echoBinSafe(TM_12xtM2ZmWTyc1IoNCQwzsA_2, 1);
//    for a in myiter():
		a = ((NI) 11);
//      echo "done"
		echoBinSafe(TM_12xtM2ZmWTyc1IoNCQwzsA_2, 1);
	}
}

links

• see also [superseded] [os] fix #8734, #8353: parentDir, parentDirs now work reliably #10545 (comment) for relevant discussion, where os.parentDirs was deemed unsuitable in compiler/packagehandling.nim which had to roll it's own version:

iterator myParentDirs(p: string): string =
  # XXX os's parentDirs is stupid (multiple yields) and triggers an old bug...

• for an example of how to switch from multiple yield to a single yield, see this PR: [TODO] os.parentDirs now uses a single yield to avoid code bloat; refs #10553 #10557

note

• D ranges would have the benefit of inline iterator in terms of having 0 overhead, while avoiding the code bloat associated with it (hence would likely be faster when instruction cache starts becoming a bottleneck because of resulting code bloat)
• the only tradeoff is that writing a range is sometimes a bit more complex than writing an iterator because it requires the iteration state to be explicit as opposed to implicit; but that's only for callee (the caller sees no difference); see https://github.com/timotheecour/vitanim/blob/master/drange/src/drange/drange_algorithms.nim for an experiment with this idea in Nim (note newest yet-to-be-pushed version doesn't use concept to avoid its bugs, see chaining of procs with concepts yields Error: too nested for type matching or exponential compile time #9422 (comment))

[Araq]

Well it's not like you cannot fight the code bloat in the codegen with some usages of goto so there is no inherent advantage of D's way. And what you call a "minor annoyance" for the iterator implementor gets ugly, quickly.

[timotheecour]

Well it's not like you cannot fight the code bloat in the codegen with some usages of goto

we should definitely, if it's possible to use goto

so there is no inherent advantage of D's way

we've talked about this; D ranges (which again, are feasible in nim without compiler support AFAIK) are 1st class; and I'll eventually make more progress in that direction when i find time

And what you call a "minor annoyance" for the iterator implementor gets ugly, quickly.

I did write * a bit more complex, not minor annoyance; yes that's the tradeoff. Without the above mentioned goto in inline iterator implementation to avoid code bloat, the "corrected" inline iterator that avoids multiple yield also has to model iteration state though (see #10557) ; with the "corrected" implementation using goto, well, let's see when we have that.