Enum thrift::Error

pub enum Error {
    Transport(TransportError),
    Protocol(ProtocolError),
    Application(ApplicationError),
    User(Box<dyn Error + Sync + Send>),
}

Error type returned by all runtime library functions.

thrift::Error is used throughout this crate as well as in auto-generated Rust code. It consists of four variants defined by convention across Thrift implementations:

1. Transport: errors encountered while operating on I/O channels
2. Protocol: errors encountered during runtime-library processing
3. Application: errors encountered within auto-generated code
4. User: IDL-defined exception structs

The Application variant also functions as a catch-all: all handler errors are automatically turned into application errors.

All error variants except Error::User take an eponymous struct with two required fields:

1. kind: variant-specific enum identifying the error sub-type
2. message: human-readable error info string

kind is defined by convention while message is freeform. If none of the enumerated kinds are suitable use Unknown.

To simplify error creation convenience constructors are defined for all variants, and conversions from their structs (thrift::TransportError, thrift::ProtocolError and thrift::ApplicationError into thrift::Error.

Examples

Create a TransportError.

use thrift::{TransportError, TransportErrorKind};

// explicit
let err0: thrift::Result<()> = Err(
  thrift::Error::Transport(
    TransportError {
      kind: TransportErrorKind::TimedOut,
      message: format!("connection to server timed out")
    }
  )
);

// use conversion
let err1: thrift::Result<()> = Err(
  thrift::Error::from(
    TransportError {
      kind: TransportErrorKind::TimedOut,
      message: format!("connection to server timed out")
    }
  )
);

// use struct constructor
let err2: thrift::Result<()> = Err(
  thrift::Error::Transport(
    TransportError::new(
      TransportErrorKind::TimedOut,
      "connection to server timed out"
    )
  )
);


// use error variant constructor
let err3: thrift::Result<()> = Err(
  thrift::new_transport_error(
    TransportErrorKind::TimedOut,
    "connection to server timed out"
  )
);

Create an error from a string.

use thrift::{ApplicationError, ApplicationErrorKind};

// we just use `From::from` to convert a `String` into a `thrift::Error`
let err0: thrift::Result<()> = Err(
  thrift::Error::from("This is an error")
);

// err0 is equivalent to...
let err1: thrift::Result<()> = Err(
  thrift::Error::Application(
    ApplicationError {
      kind: ApplicationErrorKind::Unknown,
      message: format!("This is an error")
    }
  )
);

Return an IDL-defined exception.

// Thrift IDL exception definition.
exception Xception {
  1: i32 errorCode,
  2: string message
}

use std::error::Error;
use std::fmt;
use std::fmt::{Display, Formatter};

// auto-generated by the Thrift compiler
#[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd)]
pub struct Xception {
  pub error_code: Option<i32>,
  pub message: Option<String>,
}

// auto-generated by the Thrift compiler
impl Error for Xception {
  fn description(&self) -> &str {
    "remote service threw Xception"
  }
}

// auto-generated by the Thrift compiler
impl From<Xception> for thrift::Error {
  fn from(e: Xception) -> Self {
    thrift::Error::User(Box::new(e))
  }
}

// auto-generated by the Thrift compiler
impl Display for Xception {
  fn fmt(&self, f: &mut Formatter) -> fmt::Result {
    self.description().fmt(f)
  }
}

// in user code...
let err: thrift::Result<()> = Err(
  thrift::Error::from(Xception { error_code: Some(1), message: None })
);

Variants

Transport(TransportError)

Errors encountered while operating on I/O channels.

These include connection closed and bind failure.

Protocol(ProtocolError)

Errors encountered during runtime-library processing.

These include message too large and unsupported protocol version.

Application(ApplicationError)

Errors encountered within auto-generated code, or when incoming or outgoing messages violate the Thrift spec.

These include out-of-order messages and missing required struct fields.

This variant also functions as a catch-all: errors from handler functions are automatically returned as an ApplicationError.

User(Box<dyn Error + Sync + Send>)

IDL-defined exception structs.

Methods

impl Error

pub fn read_application_error_from_in_protocol(
    i: &mut dyn TInputProtocol
) -> Result<ApplicationError>

Create an ApplicationError from its wire representation.

Application code should never call this method directly.

pub fn write_application_error_to_out_protocol(
    e: &ApplicationError,
    o: &mut dyn TOutputProtocol
) -> Result<()>

Convert an ApplicationError into its wire representation and write it to the remote.

Application code should never call this method directly.

Trait Implementations

impl From<String> for Error

fn from(s: String) -> Self

Performs the conversion.

impl<'a> From<&'a str> for Error

fn from(s: &'a str) -> Self

Performs the conversion.

impl From<TransportError> for Error

fn from(e: TransportError) -> Self

Performs the conversion.

impl From<ProtocolError> for Error

fn from(e: ProtocolError) -> Self

Performs the conversion.

impl From<ApplicationError> for Error

fn from(e: ApplicationError) -> Self

Performs the conversion.

impl From<Error> for Error

fn from(err: Error) -> Self

Performs the conversion.

impl From<FromUtf8Error> for Error

fn from(err: FromUtf8Error) -> Self

Performs the conversion.

impl Display for Error

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Debug for Error

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Error for Error

fn description(&self) -> &str

This method is soft-deprecated.

fn cause(&self) -> Option<&dyn Error>

Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

The lower-level cause of this error, if any.

fn source(&self) -> Option<&(dyn Error + 'static)>

The lower-level source of this error, if any.

fn backtrace(&self) -> Option<&Backtrace>

🔬 This is a nightly-only experimental API. (backtrace)

Returns a stack backtrace, if available, of where this error ocurred.