Improve Stream.interval/1 documentation

[britto]

By warning about its blocking behavior and suggesting the use of Stream.iterate/2 for generating number sequences.

[lexmag]

It is actually much more cheaper to use Stream.interval(0) than Stream.iterate(0, & &1 + 1):

iex> interval = Stream.interval(0)
iex> :timer.tc(Enum, :take, [interval, 100]) 
{36, ...}
iex> iterate = Stream.iterate(0, &(&1 + 1))
iex> :timer.tc(Enum, :take, [iterate, 100]) 
{184, ...}

[josevalim]

That's because you are using IEx so the anonymous function is being evaluated. Never benchmark in the shell. Doing the one below in a file gives me a slightly faster iterate:

interval = Stream.interval(0)
IO.inspect :timer.tc(Enum, :take, [interval, 1000])

iterate = Stream.iterate(0, &(&1 + 1))
IO.inspect :timer.tc(Enum, :take, [interval, 1000])

[lexmag]

Riiight, though with compiled code there is no clear winner:

{103, ...}
{106, ...}
======
{103, ...}
{98, ...}
======
{103, ...}
{124, ...}
======
{103, ...}
{98, ...}

I believe there is no meaningful difference.

[josevalim]

Right. So let's go with the one that is better semantically. :)

[josevalim]

Can we please remove the bold and say "instead use ..." or "use ... instead". I believe the "use instead" is not idiomatic. :)

[lexmag]

We use use X instead. in every other place.

[josevalim]

I am 👍 because it gives a nudge in the proper direction. I actually have no use cases for Stream.interval and Stream.timer besides possibly testing. They were added in a time we thought Stream would have async functionality but it never became true. It is in my plans to evaluate deprecating them so pushing users away from it is a good idea.

[gusaiani]

@britto @josevalim Mind there's a necesary in the comment, instead of necessary.

[lexmag]

With this addition we have conflicting usage example: we generate sequence of numbers.

[britto]

@gusaiani thanks! fixed.

[lexmag]

Probably we should have parens here, I think better to be closer to what Macro.to_string/1 produce.

[josevalim]

I find it much more readable without the parenthesis. Maybe we should make Macro.to_string/1 smart enough to handle those cases. It has a tendency to add too many parens. :)

[britto]

Thanks. Just applied your suggestions 👍.

[lexmag]

Oh noes. "parens" is the answer to life, the universe, and everything.

[lexmag]

Amount of people who confused by dangling & requires parens. :)

[josevalim]

We had this discussion in the past, so no need to revisit it here. :) It is part of the language, it is here to stay, folks may as well get acquainted with it.

[whatyouhide]

But I am not folks! I don't want to get acquainted! 😄

[britto]

I aggree that the current documentation is pretty self-explanatory. My point here is to warn beginners who might overlook the sleep implication of this function call. Since I've seen some misuse of this function in the wild, I thought it would be a good idea to reinforce the warning.

[josevalim]

❤️ 💚 💙 💛 💜