document pros/cons of seq/sequence/gen

[c-cube]

maybe draw from existing blog posts/readme (including the gagallium post from gasche)

[pmetzger]

Can you link to the blog posts? If you throw together (in a few minutes) a not-really document with no more than a paragraph or two of what it should contain and links to the things you want to steal from, that might be enough for someone like me to start filling it out.

[c-cube]

http://gallium.inria.fr/blog/generators-iterators-control-and-continuations/ my talk at some OUPS: http://cedeela.fr/~simon/talks/sequence.pdf

for a short explanation of the differences:

• seq is pure, functional, and can be iterated on as many times as needed (if providers of the iterators did their job correctly). It's like a lazy list, minus the memoization, and behaves like a value. You can write cartesian_product, zip, map2, for_all2`, etc. on it because you (the caller) control iteration.

• gen is imperative, mutable, and consumable (you can't iterate twice on the same 'a gen). It looks a lot like iterators in rust/java/… and can be pretty efficient in some cases. Since you control iteration you can also write map2, for_all2, etc but only with linear use of input generators (since you can traverse them only once). That requires some trickery for cartesian_product (like storing already produced elements internally).

• sequence is not under the control of the consumer: you give it a callback and it'll call it on every element. Therefore it's not as flexible as gen, and even less so than seq. The upside is that it can be super super fast, especially for things like filter or flat_map. In some cases it can be turned back to nested for loops or just a call to Foo.iter with a complicated callback. Memory consumption should be good too. You cannot write zip, map2, etc since these require step-wise iteration on several iterators, whereas sequence only offers the equivalent of nested loops.

[pmetzger]

Where would you like such a document to be placed ultimately? And what should it be written in?

[c-cube]

Good question, since it concerns all three libraries (gen, sequence, oseq/seq/stdlib). I think it should be a markdown file, I can host it somewhere (or we could make it into a gist?)

[bluddy]

How about ocamlverse?

[c-cube]

We could have a copy of it on ocamlverse, sure. I'd still like the source to also be in one of the iterators' repositories.