Start building a music player server #17
|
@ -0,0 +1,3 @@
|
|||
# Flow
|
||||
|
||||
This is a library to help with application control flow, separating fatal errors from normal recoverable errors. This is almost entirely inspired by [Error Handling in a Correctness-Critical Rust Project](https://sled.rs/errors.html) in the sled.rs library.
|
|
@ -1,14 +1,40 @@
|
|||
//! Control Flow for Correctness-Critical applications
|
||||
//!
|
||||
//! https://sled.rs/errors.html
|
||||
//!
|
||||
//! Where the sled.rs library uses `Result<Result<A, Error>, FatalError>`, these are a little hard to
|
||||
//! work with. This library works out a set of utility functions that allow us to work with the
|
||||
//! nested errors in the same way as a regular Result.
|
||||
use std::error::Error;
|
||||
|
||||
/// Implement this trait for the application's fatal errors.
|
||||
///
|
||||
/// Fatal errors should be things that should trigger an application shutdown. Applications should
|
||||
/// not try to recover from fatal errors, but simply bring the app to the safest shutdown point and
|
||||
/// report the best possible information to the user.
|
||||
///
|
||||
/// Examples: database corruption, or the database is unavailable in an application that cannot
|
||||
/// function without it. Graphics environment cannot be initialized in a GUI app.
|
||||
///
|
||||
/// Applications should generally have only one FatalError type. There are no handling utilities
|
||||
/// for Fatal conditions, so Fatal conditions must be handled through an ordinary `match`
|
||||
/// statement.
|
||||
pub trait FatalError: Error {}
|
||||
|
||||
/// Flow<A, FE, E> represents a return value that might be a success, might be a fatal error, or
|
||||
/// might be a normal handleable error.
|
||||
pub enum Flow<A, FE, E> {
|
||||
/// The operation was successful
|
||||
Ok(A),
|
||||
/// The operation encountered a fatal error. These should be bubbled up to a level that can
|
||||
/// safely shut the application down.
|
||||
Fatal(FE),
|
||||
/// Ordinary errors. These should be handled and the application should recover gracefully.
|
||||
Err(E),
|
||||
}
|
||||
|
||||
impl<A, FE, E> Flow<A, FE, E> {
|
||||
/// Apply an infallible function to a successful value.
|
||||
pub fn map<B, O>(self, mapper: O) -> Flow<B, FE, E>
|
||||
where
|
||||
O: FnOnce(A) -> B,
|
||||
|
@ -20,6 +46,9 @@ impl<A, FE, E> Flow<A, FE, E> {
|
|||
}
|
||||
}
|
||||
|
||||
/// Apply a potentially fallible function to a successful value.
|
||||
///
|
||||
/// Like `Result.and_then`, the mapping function can itself fail.
|
||||
pub fn and_then<B, O>(self, handler: O) -> Flow<B, FE, E>
|
||||
where
|
||||
O: FnOnce(A) -> Flow<B, FE, E>,
|
||||
|
@ -31,6 +60,9 @@ impl<A, FE, E> Flow<A, FE, E> {
|
|||
}
|
||||
}
|
||||
|
||||
/// Map a normal error from one type to another. This is useful for converting an error from
|
||||
/// one type to another, especially in re-throwing an underlying error. `?` syntax does not
|
||||
/// work with `Flow`, so you will likely need to use this a lot.
|
||||
pub fn map_err<F, O>(self, mapper: O) -> Flow<A, FE, F>
|
||||
where
|
||||
O: FnOnce(E) -> F,
|
||||
|
@ -42,6 +74,7 @@ impl<A, FE, E> Flow<A, FE, E> {
|
|||
}
|
||||
}
|
||||
|
||||
/// Provide a function to use to recover from (or simply re-throw) an error.
|
||||
pub fn or_else<O, F>(self, handler: O) -> Flow<A, FE, F>
|
||||
where
|
||||
O: FnOnce(E) -> Flow<A, FE, F>,
|
||||
|
@ -54,6 +87,8 @@ impl<A, FE, E> Flow<A, FE, E> {
|
|||
}
|
||||
}
|
||||
|
||||
/// Convert from a normal `Result` type to a `Flow` type. The error condition for a `Result` will
|
||||
/// be treated as `Flow::Err`, never `Flow::Fatal`.
|
||||
impl<A, FE, E> From<Result<A, E>> for Flow<A, FE, E> {
|
||||
fn from(r: Result<A, E>) -> Self {
|
||||
match r {
|
||||
|
@ -63,19 +98,23 @@ impl<A, FE, E> From<Result<A, E>> for Flow<A, FE, E> {
|
|||
}
|
||||
}
|
||||
|
||||
/// Convenience function to create an ok value.
|
||||
pub fn ok<A, FE: FatalError, E: Error>(val: A) -> Flow<A, FE, E> {
|
||||
Flow::Ok(val)
|
||||
}
|
||||
|
||||
/// Convenience function to create an error value.
|
||||
pub fn error<A, FE: FatalError, E: Error>(err: E) -> Flow<A, FE, E> {
|
||||
Flow::Err(err)
|
||||
}
|
||||
|
||||
/// Convenience function to create a fatal value.
|
||||
pub fn fatal<A, FE: FatalError, E: Error>(err: FE) -> Flow<A, FE, E> {
|
||||
Flow::Fatal(err)
|
||||
}
|
||||
|
||||
#[macro_export]
|
||||
/// Return early from the current function if the value is a fatal error.
|
||||
macro_rules! return_fatal {
|
||||
($x:expr) => {
|
||||
match $x {
|
||||
|
@ -87,6 +126,7 @@ macro_rules! return_fatal {
|
|||
}
|
||||
|
||||
#[macro_export]
|
||||
/// Return early from the current function is the value is an error.
|
||||
macro_rules! return_error {
|
||||
($x:expr) => {
|
||||
match $x {
|
||||
|
|
Loading…
Reference in New Issue