Stream API/specs: File.stream! vs IO.stream

Chat / Discussions
1

Posting this in discussions because it’s more of an open question about API design/conventions, but while looking through the documentation around streams, I found myself wondering why File includes a stream! function whereas IO has stream. According to specs, both functions appear to work similarly, returning an Enumerable directly (not wrapped in a tuple), and neither mentions any error cases I noticed, so why the different name?

My impression was that there is a pretty strong convention that a ! suffix in a function should always indicate that an error could be expected in certain conditions, whereas a function without ! should never be expected to return an error, but could return either a “status tuple” (actually not sure if there’s a more technical term for {:ok, res}/{:error, res} return values) or a result more directly, which I guess would mean that IO.stream is more “correct,” since, unlike File.read!, File.stream! will not error even when the path is invalid, etc?

Mostly just curious because I am designing a stream API for one of my own modules where most of the functions return status couples, but I don’t foresee any error cases for the streaming API. Appreciate any input!

1 Like
2

File.stream! has a line that’s easy to miss in the docs:

Operating the stream can fail on open for the same reasons as File.open!/2

“Operating” is the key part - you can File.stream! things that don’t exist, and you won’t get the exception until something forces the stream.

For instance:

iex(1)> File.stream!("nosuchfile.txt")

%File.Stream{
  line_or_bytes: :line,
  modes: [:raw, :read_ahead, :binary],
  path: "nosuchfile.txt",
  raw: true
}

iex(2)> File.stream!("nosuchfile.txt") |> Enum.to_list()

** (File.Error) could not stream "nosuchfile.txt": no such file or directory
    (elixir 1.13.0) lib/file/stream.ex:83: anonymous fn/3 in Enumerable.File.Stream.reduce/3
    (elixir 1.13.0) lib/stream.ex:1517: anonymous fn/5 in Stream.resource/3
    (elixir 1.13.0) lib/enum.ex:4143: Enum.reverse/1
    (elixir 1.13.0) lib/enum.ex:3488: Enum.to_list/1

IO.stream can’t fail in any of these ways since it takes either a PID (that you’d get from calling File.open! and possibly getting an exception) or an atom (to refer to stdio), so it doesn’t get a !.

1 Like
3

So I didn’t notice that actual line but I’m certainly familiar with the behavior that a File stream will fail when you try to iterate on it. I am less familiar with working with IO streams though so that was probably a bad assumption of mine that there were some cases that might cause an error at that point. I guess it’s just that lazy evaluation is an interesting edge case for this convention. My first reaction is that even if using the stream might create an error at a certain point, the function name should only express the possible return values, but it’s clear why that would be difficult to adhere to in this case.

Interestingly, my case involves different stream sources so it complicates even further. if a stream API might return an IO stream or a File stream, how should it be named? stream! because in certain conditions an error might be raised on iteration? :thinking: