vecdb 0.10.1

High-performance mutable persistent vectors built on rawdb
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138

use std::{fmt, fs, io, result, time};

use thiserror::Error;

use crate::{Format, Stamp, Version};

pub type Result<T, E = Error> = result::Result<T, E>;

/// Error types for vecdb operations.
#[derive(Debug, Error)]
pub enum Error {
    #[error(transparent)]
    IO(#[from] io::Error),
    #[error(transparent)]
    Format(#[from] fmt::Error),
    #[error("Couldn't lock file. It must be already opened by another process.")]
    TryLockError(#[from] fs::TryLockError),
    #[cfg(feature = "zerocopy")]
    #[error("ZeroCopy error")]
    ZeroCopyError,
    #[error(transparent)]
    SystemTimeError(#[from] time::SystemTimeError),
    #[cfg(feature = "pco")]
    #[error(transparent)]
    PCO(#[from] pco::errors::PcoError),
    #[cfg(feature = "lz4")]
    #[error(transparent)]
    LZ4(#[from] lz4_flex::block::DecompressError),
    #[error(transparent)]
    RawDB(#[from] rawdb::Error),
    #[cfg(feature = "serde_json")]
    #[error(transparent)]
    SerdeJSON(#[from] serde_json::Error),
    #[cfg(feature = "sonic-rs")]
    #[error(transparent)]
    SonicRS(#[from] sonic_rs::Error),

    #[error("Wrong length: received: {received:?}, expected: {expected:?}")]
    WrongLength { received: usize, expected: usize },
    #[error("Wrong endian")]
    WrongEndian,
    #[error("Iterator ended")]
    IteratorEnded,
    #[error("Different version received: {received:?}, expected: {expected:?}")]
    DifferentVersion {
        received: Version,
        expected: Version,
    },
    #[error("Index too high: index: {index}, len: {len}, name: {name}")]
    IndexTooHigh {
        index: usize,
        len: usize,
        name: String,
    },
    #[error("Unexpected index: expected {expected}, got {got} ({name})")]
    UnexpectedIndex {
        expected: usize,
        got: usize,
        name: String,
    },
    #[error("Expect vec to have index")]
    ExpectVecToHaveIndex,
    #[error("Failed to convert key to usize")]
    FailedKeyTryIntoUsize,
    #[error("Different format received: {received:?}, expected: {expected:?}")]
    DifferentFormat { received: Format, expected: Format },
    #[error("Version cannot be zero, can't verify endianness otherwise")]
    VersionCannotBeZero,
    #[error("Stamp mismatch: file stamp {file:?} != vec stamp {vec:?}")]
    StampMismatch { file: Stamp, vec: Stamp },
    #[error("Corrupted region: invalid length {region_len}")]
    CorruptedRegion { name: String, region_len: usize },
    #[error("Decompression mismatch: expected {expected_len} values, got {actual_len}")]
    DecompressionMismatch {
        expected_len: usize,
        actual_len: usize,
    },
    #[error("Cannot remove PcodecVec: pages still referenced")]
    PagesStillReferenced,
    #[error("Invalid format byte: {0}")]
    InvalidFormat(u8),
    #[error("Invalid argument: {0}")]
    InvalidArgument(&'static str),
    #[error("Arithmetic overflow")]
    Overflow,
    #[error("Arithmetic underflow")]
    Underflow,
}

impl Error {
    /// Returns true if this error is due to a file lock (another process has the database open).
    /// Lock errors are transient and should not trigger data deletion.
    pub fn is_lock_error(&self) -> bool {
        matches!(self, Error::TryLockError(_))
    }

    /// Returns true if this error indicates data corruption or version incompatibility.
    /// These errors may require resetting/deleting the data to recover.
    pub fn is_data_error(&self) -> bool {
        match self {
            Error::IO(io_err) => is_io_data_error(io_err),
            Error::RawDB(rawdb::Error::IO(io_err)) => is_io_data_error(io_err),
            Error::RawDB(rawdb::Error::CorruptedMetadata(_)) => true,
            Error::RawDB(rawdb::Error::InvalidMetadataSize { .. }) => true,
            Error::RawDB(rawdb::Error::EmptyMetadata) => true,
            Error::DifferentVersion { .. }
            | Error::DifferentFormat { .. }
            | Error::StampMismatch { .. }
            | Error::CorruptedRegion { .. }
            | Error::DecompressionMismatch { .. }
            | Error::WrongEndian
            | Error::WrongLength { .. }
            | Error::InvalidFormat(_) => true,
            _ => false,
        }
    }
}

fn is_io_data_error(io_err: &io::Error) -> bool {
    matches!(
        io_err.kind(),
        io::ErrorKind::IsADirectory | io::ErrorKind::NotADirectory
    )
}

#[cfg(feature = "zerocopy")]
impl<A, B, C> From<zerocopy::error::ConvertError<A, B, C>> for Error {
    fn from(_: zerocopy::error::ConvertError<A, B, C>) -> Self {
        Self::ZeroCopyError
    }
}

#[cfg(feature = "zerocopy")]
impl<A, B> From<zerocopy::error::SizeError<A, B>> for Error {
    fn from(_: zerocopy::error::SizeError<A, B>) -> Self {
        Self::ZeroCopyError
    }
}