Lib io

Module editing plan template

1. Announcement to mailing list

• Proposed editor: your name
• Date proposed: date of proposal
• Link: link to email

Notes from discussion on mailing list

• There are some

2. Research of standards and techniques

1. Standard: standard - link to docs - ...

Summary of research on standards and leading techniques

Relevant standards and techniques exist?

Those intended to follow (and why)

Those intended to ignore (and why)

3. Research of libraries from other languages

• .NET
• Java io nio
• C / C++ stdio
• C++ iostreams - Probably don't want to take a lot of influence from C++
• C++ boost iostreams
• C (Plan 9) bio - tidied up / simplified stdio
• D stdio - stdio-like
• Go - many fine-grained interfaces
• Python 3 io - includes text/binary division
• Common Lisp streams - very composable, possibly over-engineered
• Haskell System.IO
• Ada streams streamIO sequentialIO

Summary of research from other languages:

Structures and functions commonly appearing

Types of I/O sources and sinks

• File
• TCP socket
• Unix domain socket
• Pipe
• UDP
• Memory buffer
• String
• Formatting + formatted values
• Serialization

IO adaptors / filters / converters

• Pattern matching and replacement
• Character encodings
• Compression
• Encryption

Variations on implementation seen

Error handling

• Return values - requires explicit checks, lots of noise
• Exceptions - results in nicer looking code, error handling at arbitrary granularity

Pitfalls and hazards associated with each variant

Relationship to other libraries and/or abstract interfaces

4. Module writing

• Pull request: link to bug

Additional implementation notes

Error handling

I/O is an area where nearly every operation can result in unexpected errors. It needs to be convenient to use I/O on the non-error path while also possible to handle errors efficiently.

Some use cases:

• I'm hacking together a quick prototype or script that does a bunch of file manipulation. Thinking about all the possible ways I/O could fail is not the point of this work and it's ok for the entire process to fail if something goes wrong. I don't want to be inconvenienced with handling errors.
• I'm doing some performance critical I/O on a server and want to recover from an I/O failure in the most efficient way possible. I'm ok with writing extra error handling code.

In Rust our error handling options are 'conditions' and the Result type.

Conditions are events that can be raised, usually upon error, and optionally handled by dynamically-scoped 'condition handlers'. An unhandled condition results in task failure. Condition handlers are not like exceptions - they are handled at the site of the error, not after unwinding the stack. There is no way in Rust to 'catch' an exception. Conditions are not used widely and it's unknown how well they work in practice.

The Result type is a monad-like type that can either be Ok(A) or Err(B). Calculations on Result can be chained together in various ways based on previous results. They are generally considered unwieldy.