Start building a music player server #17

Merged
savanni merged 15 commits from music-player into main 2023-02-11 17:59:16 +00:00
2 changed files with 43 additions and 0 deletions
Showing only changes of commit 6ee7887bd2 - Show all commits

3
flow/readme.md Normal file
View File

@ -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.

View File

@ -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 {