Documentation for g_input_stream_read_finish (and others) lacks necessary detail
Submitted by Chris Lord
Link to original bug (#623284)
Description
I've found that the documentation for g_input_stream_read_finish (and asynchronous I/O in general) seems to be rather lacking. It just says 'Finishes an asynchronous stream read operation.'
Once this callback returns, do you need to call g_input_stream_read_async again if bytes_read is >0? If less bytes are read than those you asked for, does that indicate that you've read the entire file? It should probably say this somewhere.
The worst part though, what happens when this function returns an error? Is the InputStream still valid? Should you close it or not? Is it already closed? Will doing a synchronous close still risk a long blocking period?
Take the case of reading a file over the network, where the operation times out. I assume that g_input_stream_read_finish will return an error. In theory, I guess the input stream is now closed, but do I need to call the close function? Could it block?
I think the documentation for this (and related) functions should be padded out a bit with a bit more detail, especially on what happens in error cases. I also think a very simple asynchronous read function would be good too, more similar to the API in libsoup.