faster iteration over a Flatten of heterogenous iterators (JuliaLang#58522)

seems to help in many cases. would fix the precise MWE given in
JuliaLang#52552, but does not
necessarily fix comprehensively all perf issues of all heterogenous
flattens. but, may as well be better when it's possible


setup:
```
julia> using BenchmarkTools

julia> A = rand(Int, 100000); B = 1:100000;

julia> function g(it)
           s = 0
           for i in it
               s += i
           end
           s
       end
```

before:
```
julia> @Btime g($(Iterators.flatten((A, B))))
  12.461 ms (698979 allocations: 18.29 MiB)

julia> @Btime g($(Iterators.flatten(i for i in (A, B))))
  12.393 ms (698979 allocations: 18.29 MiB)

julia> @Btime g($(Iterators.flatten([A, B])))
  15.115 ms (999494 allocations: 25.93 MiB)

julia> @Btime g($(Iterators.flatten((A, Iterators.flatten((A, B))))))
  82.585 ms (2997964 allocations: 106.78 MiB)
```

after:
```
julia> @Btime g($(Iterators.flatten((A, B))))
  135.958 μs (2 allocations: 64 bytes)

julia> @Btime g($(Iterators.flatten(i for i in (A, B))))
  149.500 μs (2 allocations: 64 bytes)

julia> @Btime g($(Iterators.flatten([A, B])))
  17.130 ms (999498 allocations: 25.93 MiB)

julia> @Btime g($(Iterators.flatten((A, Iterators.flatten((A, B))))))
  13.716 ms (398983 allocations: 10.67 MiB)
```

Author: adienes

base/iterators.jl

@@ -1239,20 +1239,48 @@ flatten_length(f, T) = throw(ArgumentError(
 length(f::Flatten{I}) where {I} = flatten_length(f, eltype(I))
 length(f::Flatten{Tuple{}}) = 0
 
-@propagate_inbounds function iterate(f::Flatten, state=())
-    if state !== ()
-        y = iterate(tail(state)...)
-        y !== nothing && return (y[1], (state[1], state[2], y[2]))
+@propagate_inbounds function iterate(fl::Flatten)
+    it_result = iterate(fl.it)
+    it_result === nothing && return nothing
+
+    inner_iterator, next_outer_state = it_result
+    inner_it_result = iterate(inner_iterator)
+
+    while inner_it_result === nothing
+        it_result = iterate(fl.it, next_outer_state)
+        it_result === nothing && return nothing
+
+        inner_iterator, next_outer_state = it_result
+        inner_it_result = iterate(inner_iterator)
     end
-    x = (state === () ? iterate(f.it) : iterate(f.it, state[1]))
-    x === nothing && return nothing
-    y = iterate(x[1])
-    while y === nothing
-         x = iterate(f.it, x[2])
-         x === nothing && return nothing
-         y = iterate(x[1])
+
+    item, next_inner_state = inner_it_result
+    return item, (next_outer_state, inner_iterator, next_inner_state)
+end
+
+@propagate_inbounds function iterate(fl::Flatten, state)
+    next_outer_state, inner_iterator, next_inner_state = state
+
+    # try to advance the inner iterator
+    inner_it_result = iterate(inner_iterator, next_inner_state)
+    if inner_it_result !== nothing
+        item, next_inner_state = inner_it_result
+        return item, (next_outer_state, inner_iterator, next_inner_state)
+    end
+
+    # advance the outer iterator
+    while true
+        outer_it_result = iterate(fl.it, next_outer_state)
+        outer_it_result === nothing && return nothing
+
+        inner_iterator, next_outer_state = outer_it_result
+        inner_it_result = iterate(inner_iterator)
+
+        if inner_it_result !== nothing
+            item, next_inner_state = inner_it_result
+            return item, (next_outer_state, inner_iterator, next_inner_state)
+        end
     end
-    return y[1], (x[2], x[1], y[2])
 end
 
 reverse(f::Flatten) = Flatten(reverse(itr) for itr in reverse(f.it))