Struct ANNError 

pub struct ANNError { /* private fields */ }

Common error type shared through DiskANN.

This type disambiguates the runtime origin of errors using the kind() enum. Third party implementations of DiskANN plugin types like provider can use kind() and the downcasting API to throw custom errors from low in the callstack and retrieve those errors higher in the stack.

use diskann::{ANNError, ANNErrorKind, error::ErrorContext};
use thiserror::Error;

// A custom error type used by a third-party.
#[derive(Debug, Error)]
#[error("custom error: {0}")]
struct CustomError(usize);

// A low-level function that returns an error.
fn errors() -> Result<(), ANNError> {
    Err(ANNError::new(ANNErrorKind::Tagged(100), CustomError(42)))
}

// A function that propagates an error, adding context.
fn propagates_with_context() -> Result<(), ANNError> {
    errors().context("propagated")
}

// Call a function that returns a contextual error.
let err = propagates_with_context().unwrap_err();

// The formatted error will contain the base error and all contexts.
let message = err.to_string();
assert!(message.contains("custom error: 42"));
assert!(message.contains("propagated"));

// If we retrieve the `ANNErrorKind`, we can recognize that it belongs to a third-party
// plugin.
assert_eq!(err.kind(), ANNErrorKind::Tagged(100));

// If we know the concrete error type, we can downcast the error.
let downcasted = err.downcast_ref::<CustomError>().unwrap();
assert_eq!(downcasted.0, 42);

Backtraces

Backtraces will be obtained upon the first construction of an ANNError if the environment variable RUST_BACKTRACE=1 is set.

Backtrace collection adds a time overhead to error collection.

Legacy API

The log_* prefixed constructors exist to maintain compatibility with an earlier iteration of this struct. These constructors set an internal ANNErrorKind and have the side effect of logging the constructed object at an Error level.

The log records associated with these messages contain the following keyed metadata:

• “diskann.file” (&str) - The file of the constructor’s caller.
• “diskann.line” (&str) - The line within the file of the constructor’s caller.

This can lead to double logging as errors are logged upon creation, and the logged again upon reaching the top level.

Properties

ANNError has the following properties to support efficiency:

• std::mem::size_of::<ANNError>() == 16: The struct is 16 bytes. This allows it to be returned in registers rather than on the stack.
• std::mem::size_of::<Option<ANNError>>() == 16: The struct can use Rust’s niche optimization.

Implementations

impl ANNError

pub fn new<E>(kind: ANNErrorKind, err: E) -> Self

where E: Error + Send + Sync + 'static,

Construct a new ANNError encapsulating err.

Errors constructed this way can be retrieved using downcasting.

use diskann::{ANNError, ANNErrorKind};
use std::env::VarError;

let err = ANNError::new(
    ANNErrorKind::IndexError,
    VarError::NotPresent,
);

let retrieved: VarError = err.downcast::<VarError>().unwrap();

Attributes

• track_caller: Internally, the type err is embedded inside a Located struct, recording the file and line of creation. The [track_caller] attribute allows for precise recording of the caller.

• inline(never): To keep the happy-path cost as minimal as possible, this function is marked as [inline(never)] to outline error handling code.

pub fn opaque<E>(err: E) -> Self

where E: Error + Send + Sync + 'static,

Construct a new ANNError encapsulating err tagged with ANNErrorKind::Opaque.

Errors constructed this way can be retrieved using downcasting.

use diskann::{ANNError, ANNErrorKind};
use std::env::VarError;

let err = ANNError::opaque(VarError::NotPresent);

assert_eq!(err.kind(), ANNErrorKind::Opaque);
let retrieved: VarError = err.downcast::<VarError>().unwrap();

Attributes

• track_caller: Internally, the type err is embedded inside a Located struct, recording the file and line of creation. The [track_caller] attribute allows for precise recording of the caller.

• inline(never): To keep the happy-path cost as minimal as possible, this function is marked as [inline(never)] to outline error handling code.

pub fn message<D>(kind: ANNErrorKind, display: D) -> Self

where D: Display + Debug + Send + Sync + 'static,

Construct a new ANNError with the provided error message.

Note

Errors constructed this way are not necessarily recoverable by using the downcasting API.

Attributes

• track_caller: Internally, the type err is embeded inside a Located struct, recording the file and line of creation. The [track_caller] attribute allows for precise recording of the caller.

• inline(never): To keep the happy-path cost as minimal as possible, this function is marked as [inline(never)] to outline error handling code.

pub fn downcast<E>(self) -> Result<E, Self>

where E: Display + Debug + Send + Sync + 'static,

Attempt to downcast the error object to a concrete type.

pub fn downcast_ref<E>(&self) -> Option<&E>

where E: Display + Debug + Send + Sync + 'static,

Attempt to downcast the error object by reference.

pub fn downcast_mut<E>(&mut self) -> Option<&mut E>

where E: Display + Debug + Send + Sync + 'static,

Attempt to downcast the error object by reference.

pub fn context<C>(self, context: C) -> Self

where C: Display + Debug + Send + Sync + 'static,

Attach the context to Self and return a new error.

pub fn kind(&self) -> ANNErrorKind

Return the kind of the originally constructed error.

pub fn log_index_error<D: Display>(err: D) -> Self

Create, log and return IndexError

pub fn log_file_handle_error<D: Display>(err: D) -> Self

Create, log and return FileHandleError

pub fn log_file_not_found_error(err: String) -> Self

Create, log and return FileNotFoundError

pub fn log_ground_truth_error(err: String) -> Self

Create, log and return GroundTruthError

pub fn log_index_config_error(parameter: String, err: String) -> Self

Create, log and return IndexConfigError

pub fn log_try_from_int_error(err: TryFromIntError) -> Self

Create, log and return TryFromIntError

pub fn log_io_error(err: Error) -> Self

Create, log and return IOError

pub fn log_io_send_error<T: Send + Sync + 'static>(err: SendError<T>) -> Self

Create, log and return IOSendError

pub fn log_disk_io_request_alignment_error(err: String) -> Self

Create, log and return DiskIOAlignmentError

pub fn log_mem_alloc_layout_error(err: LayoutError) -> Self

Create, log and return IOError

pub fn log_lock_poison_error(err: String) -> Self

Create, log and return LockPoisonError

pub fn log_pq_error<D: Display>(err: D) -> Self

Create, log and return PQError

pub fn log_sq_error<E>(err: E) -> Self

where E: Error + Send + Sync + 'static,

Create, log and return SQError

pub fn log_kmeans_error(err: String) -> Self

Create, log and return KMeansError

pub fn log_push_error<E>(err: E) -> Self

where E: Error + Send + Sync + 'static,

Create, log and return KMeansError

pub fn log_try_from_slice_error(err: TryFromSliceError) -> Self

Create, log and return TryFromSliceError

pub fn log_serde_error<D>(operation: String, err: D) -> Self

where D: Display,

Create, log and return Serde error.

pub fn log_get_vertex_data_error(vertex_id: String, data_type: String) -> Self

Create, log and return get vertex data error.

pub fn log_parse_slice_error( parsing_source: String, parsing_target: String, err: String, ) -> Self

Create, log and return parse slice error.

pub fn log_thread_pool_error(err: String) -> Self

pub fn log_invalid_operation_error(err: String) -> Self

pub fn log_async_error<D: Display>(err: D) -> Self

pub fn log_async_index_error<D: Display>(err: D) -> Self

pub fn log_async_shutdown_error<D: Display>(err: D) -> Self

pub fn log_async_runtime_error(err: String) -> Self

pub fn log_dimension_mismatch_error(err: String) -> Self

pub fn log_paged_search_error(err: String) -> Self

pub fn log_profiler_error(err: String) -> Self

pub fn log_pq_schema_registration_error<T>(err: T) -> Self

where T: Display,

pub fn log_invalid_file_format<T>(err: T) -> Self

where T: Display,

pub fn log_build_interrupted<T>(err: T) -> Self

where T: Display,

Trait Implementations

impl Debug for ANNError

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

Formats the value using the given formatter.

impl Display for ANNError

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Error for ANNError

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

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

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

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

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

Provides type-based access to context intended for error reports.

impl From<ConfigError> for ANNError

fn from(error: ConfigError) -> Self

Converts to this type from the input type.

impl From<Error> for ANNError

fn from(err: Error) -> Self

Converts to this type from the input type.

impl<const INT_TO_ID: bool, FromType, ToType> From<IdConversionError<INT_TO_ID, FromType, ToType>> for ANNError

where FromType: TypeStr + Display, ToType: TypeStr,

Allow conversion to ANNError for error propagation.

fn from(err: IdConversionError<INT_TO_ID, FromType, ToType>) -> Self

Converts to this type from the input type.

impl From<Infallible> for ANNError

fn from(_: Infallible) -> Self

Converts to this type from the input type.

impl From<Infallible> for ANNError

fn from(_: Infallible) -> Self

Converts to this type from the input type.

impl From<KnnSearchError> for ANNError

fn from(err: KnnSearchError) -> Self

Converts to this type from the input type.

impl From<LayoutError> for ANNError

fn from(err: LayoutError) -> Self

Converts to this type from the input type.

impl<T, U> From<MetadataError<T, U>> for ANNError

where T: Error + Send + Sync + 'static, U: Error + Send + Sync + 'static,

fn from(err: MetadataError<T, U>) -> Self

Converts to this type from the input type.

impl From<NativeTypeLengthError> for ANNError

fn from(err: NativeTypeLengthError) -> ANNError

Converts to this type from the input type.

impl From<PartitionError> for ANNError

fn from(err: PartitionError) -> Self

Converts to this type from the input type.

impl From<RangeSearchError> for ANNError

fn from(err: RangeSearchError) -> Self

Converts to this type from the input type.

impl From<ReadBinError> for ANNError

fn from(err: ReadBinError) -> Self

Converts to this type from the input type.

impl From<SaveBinError> for ANNError

fn from(err: SaveBinError) -> Self

Converts to this type from the input type.

impl<T> From<SendError<T>> for ANNError

where T: Send + Sync + 'static,

fn from(err: SendError<T>) -> Self

Converts to this type from the input type.

impl<T> From<TryFromError<T>> for ANNError

where T: DenseData,

fn from(err: TryFromError<T>) -> Self

Converts to this type from the input type.

impl From<TryFromErrorLight> for ANNError

fn from(err: TryFromErrorLight) -> Self

Converts to this type from the input type.

impl From<TryFromIntError> for ANNError

fn from(err: TryFromIntError) -> Self

Converts to this type from the input type.

impl From<TryFromSliceError> for ANNError

fn from(err: TryFromSliceError) -> Self

Converts to this type from the input type.

impl ToRanked for ANNError

type Transient = NeverTransient

type Error = ANNError

fn to_ranked(self) -> RankedError<Self::Transient, Self::Error>

Convert self into a RankedError.

fn from_transient(_: NeverTransient) -> Self

Construct Self from its transient variant.

fn from_error(error: Self) -> Self

Construct Self from its error variant.

impl TransientError<ANNError> for NeverTransient

fn acknowledge<D>(self, _: D)

where D: Display,

Consume self, acknowledging the transient error but proceeding with program logic.

fn acknowledge_with<F, D>(self, _: F)

where F: FnOnce() -> D, D: Display,

Consume self, acknowledging the transient error but proceeding with program logic.

fn escalate<D>(self, _: D) -> ANNError

where D: Display,

Report to self that transient errors are not acceptable in the current context and that the transient error is being upgraded to a full error.

fn escalate_with<F, D>(self, _: F) -> ANNError

where F: FnOnce() -> D, D: Display,

Report to self that transient errors are not acceptable in the current context and that the transient error is being upgraded to a full error.