Error signaling revisions

Author: aturon

errors/README.md

@@ -1,13 +1,3 @@
 # Errors
 
-Errors are classified along two dimensions:
-
-* **Avoidability**. Can the error be avoided by providing well-formed
-  input? Unavoidable errors stem from external conditions like the
-  existence of a file or availability of memory.
-
-* **Recoverability**. Can the operation cleanly exit after the error has occurred?
-  Unrecoverable errors are usually not avoidable.
-
-Error [signaling](signaling.md) and [handling](handling.md) depends on how the
-error is classified.
+> **[FIXME]** Add some general text here.

errors/signaling.md

@@ -1,18 +1,59 @@
 # Signaling errors [RFC]
 
-### For unrecoverable errors, `fail!`.
+Errors fall into one of three categories:
 
-Unrecoverable errors are rare and catastrophic.  Since there is no way
-to cleanly exit the operation that discovered the error, there is no
-sensible return value. Instead, `fail` unwinds the task's stack. See
-"Handling Errors" below for guidance on how to use tasks to isolate
-unrecoverable errors.
+* Catastrophic errors, e.g. out of memory.
+* Unpreventable errors, e.g. file not found.
+* Preventable errors, e.g. wrong input encoding, index out of bounds.
+
+The signaling strategy is determined by the error category.
+
+## Catastrophic errors
+
+An error is _catastrophic_ if there is no meaningful way for the current task to
+continue after the error occurs.
+
+Catastrophic errors are _extremely_ rare, especially outside of `libstd`.
+
+**Canonical examples**: out of memory, stack overflow.
+
+> **[FIXME]** These are believed to be the _only_ catastrophic errors in
+> Rust/libstd at the moment. We should confirm, and say so.
+
+### For catastrophic errors, use `fail!`.
+
+Invoking `fail!` causes the current task to fail, which:
+
+* unwinds the task's stack
+* poisons any channels or other synchronization connecting the task to others
 
 For example,
 [`rt::heap::allocate`](http://static.rust-lang.org/doc/master/std/rt/heap/fn.allocate.html)
 fails the task if allocation fails.
 
-### For recoverable but unavoidable errors, use `Result`.
+Task failure does not mean that the entire program must abort.
+For example, by breaking a program into a parent task that monitors its
+children, the program _can_ meaningfully recover from task failures at the
+global level. See [the error handling section](handling.md) for guidance
+on working with task failure.
+
+## Unpreventable errors
+
+An error is _unpreventable_ if it is caused by circumstances out of the
+program's control.
+
+Unpreventable errors are common for operations that involve I/O or other access
+to shared resources.
+
+**Canonical example**: file not found.
+
+### For unpreventable errors, use `Result`.
+
+The
+[`Result<T,E>` type](http://static.rust-lang.org/doc/master/std/result/index.html)
+represents either a success (yielding `T`) or failure (yielding `E`). By
+returning a `Result`, a function allows its clients to discover and react to
+external circumstances that are obstructing an operation.
 
 The `E` component in `Result<T,E>` should convey details about the external
 circumstances that caused the error. Use an `enum` when multiple kinds of errors
@@ -24,67 +65,109 @@ uses the `Result` type pervasively, with
 [`IoError`](http://static.rust-lang.org/doc/master/std/io/struct.IoError.html)
 providing details when an error occurs.
 
-### For recoverable and avoidable errors, prefer `Result`.
+## Preventable errors
+
+An error is _preventable_ if its absence can be guaranteed by restricting the
+arguments given to the operation.
 
-Avoidable errors can only arise when a function places additional expectations
-on its input beyond its static type. When the error is also recoverable, there
-are two choices.
+Preventable errors are common for operations that impose constraints on their
+parameters beyond their static type.
 
-#### Preferred: returning a `Result`
+**Canonical examples**: wrong input encoding, index out of bounds.
+
+### For preventable errors, prefer `Result`.
+
+Preventable errors present API designers with a choice:
+* Permit erroneous input, return `Result`, and use the `Err` variant to inform
+  the client of the error.
+* Treat erroneous input as a _contract violation_ (i.e., assertion failure) and `fail!`.
+
+The right choice depends on the _overall design_ of an API: some APIs make it
+very easy to obtain and work with valid inputs, in which case working with `Result` would be a needless distraction.
+
+But when in doubt, prefer `Result`.
+
+#### When to return a `Result`
+
+For preventable errors in APIs where
+
+* ensuring input validity ahead of time is difficult or expensive, or
+* validity checking is a useful byproduct of attempting an operation,
+
+return a `Result`.
 
 Following the principle of
 [returning useful intermediate results](../features/functions-and-methods/output.md),
-the function should return a `Result` value with an error component saying
-exactly where things went wrong. This information is typically produced when
-validating or consuming input anyway; returning it to the client allows for
-better error reporting and possibly recovery.
+the `Result`'s error component should give detail about which part of the input
+was invalid -- information that is typically produced during input validation or
+processing anyway.
 
 For example, a function `from_str` for parsing into a given type should return a
-`Result` with error component giving the location or span of parsing
-failure.
+`Result` with error component giving the location or span of parsing failure.
 
-Clients can treat the function's contract as a kind of assertion by
-calling `unwrap` on the `Result`, which will produce a failure _in the
-client's code_ when the client breaks the contract.
+If clients believe they are providing valid input, they can use `unwrap` on the
+`Result` to assert as much; this will produce a failure _in the client's
+code_ if things go wrong.
 
-#### Failing.
+#### When to `fail!`
 
-While returning a `Result` makes for a very clear interface, it can be
-burdensome:
+For preventable errors in APIs where
 
-* Clients have to `unwrap` the result to assert that they have
-  satisfied the function's contract.
-* The function has to internally propagate the `Result`, and possibly
-  perform extra cleanup.
+* input validity can be easily checked, or
+* parts of the API naturally produce valid inputs for other parts, or
+* invalid inputs clearly represent a logic error,
 
-Sometimes avoidable, recoverable errors are very rare and clearly
-indicate a logic error rather than bad input. Such errors are also
-likely to cause task failure at some point (usually because clients
-would just `unwrap`).
+using `fail!` is acceptable.
 
-In those rare cases, it is acceptable to invoke `fail!` when the error
-is discovered. The expectations on the input then become a strong part
-of the function's contract, and violating them is always a preventable
-bug. The failure conditions should be clearly stated in a `Failure`
-section of the function's doc comment.
+The expectations on the input then become a _contract_ for the function, and
+violating them is akin to an assertion failure -- a bug. The failure conditions
+should be clearly stated in a `Failure` section of the function's doc comment.
 
-For example, slice indexing fails on an out of bounds error, which is
-recoverable and avoidable but nearly always represents a bug (and is
-hopefully rare).
+The benefit of using `fail!` is that the signatures of the API's functions are
+simpler, and using the API does not require the client to constantly `unwrap`.
+
+For example, slice indexing fails on an out of bounds error, which is a
+preventable error and nearly always represents a bug. Moreover, most uses of
+array indexing naturally incorporate a bounds check already, e.g. looping over
+array indices.
 
 > **[FIXME]** `std` also contains some more dubious examples, like the
 > [`to_c_str`](http://static.rust-lang.org/doc/master/std/c_str/trait.ToCStr.html#tymethod.to_c_str)
 > method, which fails when the string contains an interior
 > `null`. What do we want to say about those?
 
-### Fallible convenience methods. [OPEN]
+#### Do not provide both `Result` and `fail!` variants. [RFC]
+
+An API should not provide both `Result`-producing and `fail`ing versions of an
+operation. It should provide just the `Result` version, allowing clients to use
+`try!` or `unwrap` instead as needed.
+
+There is one exception to this rule, however. Some APIs are strongly oriented
+around failure, in the sense that their functions/methods are explicitly
+intended as assertions.  If there is no other way to check in advance for the
+validity of invoking an operation `foo`, however, the API may provide a
+`checked_foo` variant that returns a `Result`.
+
+The main examples in `libstd` providing both variants are:
+* Channels, which are the primary point of failure propagation between tasks. As
+  such, calling `recv()` is an _assertion_ that the other end of the channel is
+  still alive, which will propagate failures from the other end of the
+  channel. On the other hand, since there is no separate way to atomically test
+  whether the other end has hung up, channels provide a `recv_opt` variant that
+  produces a `Result`.
+
+  > **[FIXME]** The `_opt` suffix needs to be replaced by a `checked_` prefix.
+
+
+* `RefCell`, which provides a dynamic version of the borrowing rules. Calling
+  the `borrow()` method is intended as an assertion that the cell is in a
+  borrowable state, and will `fail!` otherwise. On the other hand, there is no
+  separate way to check the state of the `RefCell`, so the module provides a
+  `try_borrow` variant that produces a `Result`.
 
-> **[OPEN]** This is a big open issue: when should APIs provide
-> convenience methods that amount to `unwrap`ping a `Result`? E.g.,
-> the `RefCell` type has `borrow` and `try_borrow`, with `.borrow()`
-> equivalent to `try_borrow().unwrap()`.
+    > **[FIXME]** The `try_` prefix needs to be replaced by a `checked_` prefix.
 
-### Avoid `Option` for error signaling.
+### Avoid `Option` for error signaling. [RFC]
 
 The `Option` type should be reserved for cases that do not represent errors, but
 rather possible outcomes for well-formed inputs under normal circumstances.
@@ -93,8 +176,8 @@ For example,
 [the `Vec::pop` method](http://static.rust-lang.org/doc/master/std/vec/struct.Vec.html)
 returns an `Option`, yielding `None` when the vector is empty.
 
-Even when there is no interesting error information to return, prefer `Result<T,
-()>` to `Option<T>` as a way of signaling that the `Err` case represents an
+Even when there is no interesting error information to return, prefer
+`Result<T,()>` to `Option<T>` as a way of signaling that the `Err` case represents an
 erroneous outcome, not a normal outcome.
 
 Rather than providing a `try_frob` function yielding an `Option`, provide a