Review of IO blocking behaviour

[samoconnor]

I've recently been helping @quinnj to debug his new HTTP.jl package, in particular a new FIFOBuffer type that is intended to behave like the IO buffers in Base (#87, #86, #76, #75, #74). The process of trying to be consistent with Base has highlighted a number of IO behaviour inconsistencies. I've hacked up a script that runs through a sequence of IO operations for various types and produces a MD table of the results (see below).

The two main issues are with the blocking behaviour of read() and eof().

The spec for eof() says: "If the stream is not yet exhausted, this function will block to wait for more data if necessary, and then return false."

• eof() works per spec for BufferStream and TCPSocket.
• For Filesystem.File, IOStream, and PipeBuffer, eof() does not block to wait for more data. Instead it returns true without blocking if there is not currently data available to be read.
• For IOBuffer it seems that eof() just always returns true.

The spec for read(::IO, ::Int) says: "[By default] this function will block repeatedly trying to read all requested bytes, until an error or end-of-file occurs."

• For BufferStream and TCPSocket, read() behaves as specified.
• However, for the other types read() seems to just return however many bytes are available at the time and does not block.
• For IOBuffer, read() always returns an empty array.

Other issues:

• For BufferStream and IOStream, isreadable() returns true after close() is called.
• For BufferStream, iswriteable() returns true after close().
• For BufferStream and IOStream, read() after close() returns empty data, whereas the other types throw an error.
• For BufferStream and TCPSocket, read(io, String) blocks until the stream is closed (this seems consistent with the blocking behaviour of read(io, nb) , however the other types return immediately with a string containing however many bytes are available at the time.
• mark/reset don't work for BufferStream mark/reset broken for BufferStream #24465
• There is no API for sending TCP FIN, e.g. shutdown(fd, SHUT_WR) or uv_shutdown(). If a TCP server waits for a request to be sent before responding, a Julia client would have to call close() to signal end of request, but would then be unable to read the response.
• Perhaps the missing shutdown is related to the inconsistencies with isreadable() and iswriteable(). It seem like maybe there should be a closeread() and closewrite() that respectively cause isreadable() and iswriteable() to return false.
• Calling close on BufferStream causes eof() = true and isopen() = false, but iswriteable() and isreadable() are both still true, and in fact reads and writes continue to work with the closed stream. It seems that BufferStream would benefit from a seperate closewrite() for signalling eof() to the reader.

type	IOBuffer	PipeBuffer	BufferStream	File (IOStream)	Filesystem
init	io = IOBuffer()	io = PipeBuffer()	io = BufferStream()	echo Hello > file	echo Hello > file
	write(io, "Hello")	write(io, "Hello")	write(io, "Hello")	open("file")	Filesystem. open("file")
isreadable()	true	true	true	true	MethodError
isopen()	true	true	true	true	true
eof()	true❗️	false	false	false	false
position	5	0	MethodError	0	0
read(io, 5)	""❗️	"Hello"	"Hello"	"Hello"	"Hello"
eof()	true	true❗️	blocked ✅	true	true
"Again"	write(io, "Again")	write(io, "Again")	write(io, "Again")	echo Again >> file	echo Again >> file
position(io)	10	0	MethodError	5	5
eof(io)	true❗️	false	false	false	false
read(io, 5)	""❗️	"Again"	"Again"	"Again"	"Again"
eof(io)	true	true❗️	blocked ✅	true	true
"Again"	write(io, "Again")	write(io, "Again")	write(io, "Again")	echo Again >> file	echo Again >> file
eof(io)	true❗️	false	false	false	false
read(io, String)	""❗️	"Again"	blocked ✅	"Again"	"Again"
iswritable(io)	true	true	true	false	MethodError
isreadable(io)	true	true	true	true	MethodError
close(io); isopen(io)	false	false	false	false	false
iswritable(io)	false	false	true❗️	false	MethodError
isreadable(io)	false	false	true❗️	true❗️	MethodError
eof(io)	true	true	true	true	Base.UVError
read(io, 5)	Argument Error	Argument Error	""❗️	""❗️	Base.UVError

Note that TCPSocket behaves almost the same as BufferStream but without the isopen() and isreadable() issues:

type	BufferStream	TCPSocket
init	io = BufferStream()	srv = accept(); io = connect()
	write(io, "Hello")	write(srv, "Hello")
isreadable()	true	true
isopen()	true	true
eof()	false	false
position	MethodError	MethodError
read(io, 5)	"Hello"	"Hello"
eof(io)	blocked	blocked
close(io); isopen(io)	true ❗️	false
eof(io)	true	true
isreadable(io)	true❗️	false
read(io, 5)	""	""

[timholy]

I'm not an IO guru so have nothing concrete to add, but just have to say wow, really nice analysis.

[stevengj]

What do you want eof() to do for File and IOBuffer? Block forever since there's no telling when additional bytes could be written to the file/buffer?

[samoconnor]

Hi @stevengj,

I'm not sure what the right interface is, but I am sure that it needs to be well specified and unambiguous so that compatible implementations can be dropped in and "just work".

If read(io, nb) was made to block for simple files, callers who wanted to read just what is in the file now would have to do read(myfile, filesize(myfile)). To be consistent with the current doc, eof() for a simple local file should probably be false/block unless the file is unlinked and there are no other open write file handles on the file.

I understand that a very common use case for simple files is to want to read to the end of what is in the file now. However, the less common use case of reading form a file that is occasionally appended to by a 3rd party needs to be handled too.

Consider also that the IOStream returned by the simple open() function is not always a simple file. See the example below of opening a named pipe (mkfifo). In this case eof() = true seems wrong because a pipe can be expected to have more data at some future time. Likewise, the read(io, 6) call should have blocked. If I'm reading a fixed number of bytes from a named pipe it is probably because there is an agreed protocol where I'm expecting the other end to write that many bytes.

type	File	NamedPipe
init	echo Hello > file	mkfifo fifo; echo Hello > fifo
	open("file")	open("fifo")
typeof(io)	IOStream	IOStream
isopen()	true	true
eof()	false	false
read(io, 5)	"Hello"	"Hello"
eof(io)	true	true
"Again"	echo Again >> file	echo Again > fifo
eof(io)	false	false
read(io, 6)	"Again"	"Again"
eof(io)	true	true

Maybe the answer is to have a user selectable blocking/non-blocking mode (O_NONBLOCK).

Maybe it would be better to have clearly distinct types for simple-file-like-things and stream-like-things.

Or maybe it's best to enforce blocking everywhere and encourage the use of tasks and/or patterns like read(myfile, filesize(myfile)).

Another alternative would be to have a WouldBlockError exception that would be thrown by anything that would block when the "i don't want things to block" option has been set (this would allow writing code that acts as if nothing ever blocks, but not have it deadlock in odd ways when there is a problem).

[bicycle1885]

For IOBuffer it seems that eof() just always returns true.

What does this mean? eof of IOBuffer may return false.

julia> buf = IOBuffer(b"foobar");

julia> eof(buf)
false

[samoconnor]

Hi @bicycle1885,
I think the difference is that my test script uses the IOBuffer() constructor.
So, I guess my finding is that for the default IOBuffer() constructor, it seems that eof() always returns true for the series of function calls in my test scenario. e.g.

julia> io = IOBuffer()
IOBuffer(data=UInt8[...], readable=true, writable=true, seekable=true, append=false, size=0, maxsize=Inf, ptr=1, mark=-1)

julia> eof(io)
true

julia> write(io, "Hello")
5

julia> eof(io)
true

julia> write(io, " World!")
7

julia> eof(io)
true

julia> read(io)
0-element Array{UInt8,1}

julia> String(take!(io))
"Hello World!"

[bicycle1885]

write changes the offset of a buffer so it is quite natural that a sequence of write operations does not change the return value. However, seek operations (e.g. seekstart) will change the return value:

julia> buf = IOBuffer()
IOBuffer(data=UInt8[...], readable=true, writable=true, seekable=true, append=false, size=0, maxsize=Inf, ptr=1, mark=-1)

julia> write(buf, b"foo")
3

julia> eof(buf)
true

julia> seekstart(buf)
IOBuffer(data=UInt8[...], readable=true, writable=true, seekable=true, append=false, size=3, maxsize=Inf, ptr=1, mark=-1)

julia> eof(buf)
false

[samoconnor]

@bicycle1885 I accept that the behaviour of IOBuffer() in isolation could seem "quite natural" in a certain context. i.e. If you expect it to behave like a local disk file. However, as things stand the documentation about how each IO type is supposed to behave is not clear.

The point of posting this issue is to highlight behaviour inconsistencies between the various IO types. I realised that I'd kind of figured out how to use the IO types I was familiar with, but that I this was largely a matter of trial and error and copying usage patterns from other code. When it came to trying to debug the HTTP.jl package, and coming up against questions of "how should function this behave", it wasn't a simple matter of "read and follow the spec". The task seemed to come down to figuring out which of the many IO variants in Base was most like what we wanted and emulating it as best we could.

Maybe the solution is just to have clearer documentation, or as I said above "Maybe it would be better to have clearly distinct types for simple-file-like-things and stream-like-things.". Maybe there needs to be seperate documentation for eof(::AbstractFile) and eof(::AbstractStream).

[StefanKarpinski]

This is a great analysis and we do want to make sure all of this is sane and consistent, but it's a bit too much to bite off for the impending 1.0 release, so based on discussion on triage, we're going to say that I/O blocking behavior is not yet stable and may change in the 1.x series. We will have to be careful to make sure that any changes we make don't break key libraries (e.g. HTTP).

[quinnj]

Luckily, HTTP.jl currently uses it's own streaming buffer type (HTTP.FIFOBuffer), so that should keep it arms-distance from changes in Base until things settle.