Crate embedded_error_chain

Easy error handling for embedded devices (no_alloc and no_std).

A rust library implementing easy error handling for embedded devices. An Error value is only a single u32 in size and supports up to 4 chained error codes. Each error code can have a value from 0 to 15 (4 bits). All error codes come from an enum that implements the ErrorCategory trait (a derive macro exists). This trait is also used to implement debug printing and equality for each error code.

This library was inspired by libraries such as error-chain and anyhow, though its goal is to work in no_std and no_alloc environments with very little memory overhead.

Example

use embedded_error_chain::prelude::*;

#[derive(Clone, Copy, ErrorCategory)]
#[repr(u8)]
enum SpiError {
    BusError,
    // ...
}

static LAST_GYRO_ACC_READOUT: usize = 200;

#[derive(Clone, Copy, ErrorCategory)]
#[error_category(links(SpiError))]
#[repr(u8)]
enum GyroAccError {
    InitFailed,

    #[error("{variant} (readout={})", LAST_GYRO_ACC_READOUT)]
    ReadoutFailed,

    /// Value must be in range [0, 256)
    #[error("{variant}: {summary}")]
    InvalidValue,
}

#[derive(Clone, Copy, ErrorCategory)]
#[error_category(links(GyroAccError))]
#[repr(u8)]
enum CalibrationError {
    Inner,
}

fn main() {
    if let Err(err) = calibrate() {
        // log the error
        println!("{:?}", err);
        // ...
    }

    let readout = match gyro_acc_readout() {
        Ok(val) => val,
        Err(err) => {
            if let Some(spi_error) = err.code_of_category::<SpiError>() {
                // try to fix it
                0
            }
            else {
                panic!("unfixable spi error");
            }
        }
    };
}

fn spi_init() -> Result<(), SpiError> {
    Err(SpiError::BusError)
}

fn gyro_acc_init() -> Result<(), Error<GyroAccError>> {
    spi_init().chain_err(GyroAccError::InitFailed)?;
    Ok(())
}

fn gyro_acc_readout() -> Result<u32, Error<GyroAccError>> {
    Err(SpiError::BusError.chain(GyroAccError::InvalidValue))
}

fn calibrate() -> Result<(), Error<CalibrationError>> {
    gyro_acc_init().chain_err(CalibrationError::Inner)?;
    Ok(())
}

Modules

marker	Marker types.
prelude	Everything for easy error handling.

Structs

Error	An error that consists of an ErrorCode that belongs to an ErrorCategory and optionally up to 4 chained error codes of different types that implement ErrorCategory.
ErrorCategoryHandle	A handle to a type that implements ErrorCategory.
ErrorCodeFormatterVal	A wrapped ErrorCodeFormatter value.
ErrorData	The entire data of the error and its error code chain.
ErrorIter	An iterator over all error codes in this Error.

Constants

ERROR_CHAIN_LEN

The maximum amount of error codes that can be chained to an Error.

Traits

ChainError	A trait that allows chaining of Error values.
ErrorCategory	A trait that implements the logic for debug printing and ErrorCode conversion. It also specifies the links to other error categories that allows Errors of different types to be chained.
ResultChainError	A trait that allows chaining if a Result contains an Error value.

Functions

format_chained

Debug format the given error_code using f (if f is Some), get the ErrorCategoryHandle of the type parameter C, and get the next ErrorCodeFormatter if next_formatter is Some.

Type Definitions

ErrorCode	An error code.
ErrorCodeFormatter	A chained formatter function.

Derive Macros

ErrorCategory

Derive ErrorCategory for an enum.