pearl/
lib.rs

1#![deny(missing_docs)]
2#![deny(missing_debug_implementations)]
3#![warn(clippy::all)]
4// #![warn(clippy::nursery)]
5// #![warn(clippy::pedantic)]
6// #![warn(clippy::cargo)]
7
8//! # pearl
9//!
10//! The `pearl` library is an asyncronous Append only key-value blob storage on disk.
11//! Crate `pearl` provides [`Futures 0.3`] interface. Tokio runtime required.
12//! Storage follows no harm policy, which means that it won't delete or change any of the stored data.
13//!
14//! [`Futures 0.3`]: https://rust-lang-nursery.github.io/futures-api-docs#latest
15//!
16//! # Examples
17//! The following example shows a storage building and initialization.
18//! For more advanced usage see the benchmark tool as the example
19//!
20//! ```no_run
21//! use pearl::{Storage, Builder, ArrayKey, BlobRecordTimestamp};
22//!
23//! #[tokio::main]
24//! async fn main() {
25//!     let mut storage: Storage<ArrayKey<8>> = Builder::new()
26//!         .work_dir("/tmp/pearl/")
27//!         .max_blob_size(1_000_000)
28//!         .max_data_in_blob(1_000_000_000)
29//!         .blob_file_name_prefix("pearl-test")
30//!         .allow_duplicates()
31//!         .build()
32//!         .unwrap();
33//!     storage.init().await.unwrap();
34//!     let key = ArrayKey::<8>::default();
35//!     let data = b"Hello World!".to_vec();
36//!     let timestamp = BlobRecordTimestamp::now();
37//!     storage.write(key, data.into(), timestamp).await.unwrap();
38//! }
39//! ```
40
41#[macro_use]
42extern crate log;
43#[macro_use]
44extern crate serde_derive;
45#[macro_use]
46extern crate anyhow;
47
48extern crate bytes;
49
50/// Basic info about current build.
51pub mod build_info;
52
53mod blob;
54/// Types representing various errors that can occur in pearl.
55pub mod error;
56mod io;
57pub use io::IoDriver;
58mod record;
59mod storage;
60
61/// bloom filter for faster check record contains in blob
62pub mod filter;
63pub use filter::{Bloom, BloomDataProvider, BloomProvider, Config as BloomConfig, FilterResult};
64
65/// tools to interact with pearl structures
66pub mod tools;
67
68pub use blob::Entry;
69pub use error::{Error, Kind as ErrorKind};
70pub use record::Meta;
71pub use storage::{ArrayKey, BlobRecordTimestamp, Builder, Key, ReadResult, RefKey, Storage};
72
73mod prelude {
74    use crc::{Crc, CRC_32_ISCSI};
75    pub const CRC32C: Crc<u32> = Crc::<u32>::new(&CRC_32_ISCSI);
76
77    pub(crate) use super::*;
78    pub(crate) use std::collections::BTreeMap;
79
80    pub(crate) use anyhow::{Context as ErrorContexts, Result};
81    pub(crate) use bincode::{deserialize, serialize, serialize_into, serialized_size};
82    pub(crate) use blob::{self, Blob, BlobConfig, IndexConfig};
83    pub(crate) use filter::{Bloom, BloomProvider, Config as BloomConfig, HierarchicalFilters};
84    pub(crate) use futures::{stream::futures_unordered::FuturesUnordered};
85    pub(crate) use record::{Header as RecordHeader, Record, RECORD_MAGIC_BYTE};
86
87    pub(crate) use io::{File, WritableData, WritableDataCreator};
88
89    pub(crate) use std::{
90        cmp::Ordering as CmpOrdering,
91        collections::HashMap,
92        convert::TryInto,
93        fmt::{Debug, Display, Formatter, Result as FmtResult},
94        fs::File as StdFile,
95        io::Error as IOError,
96        io::ErrorKind as IOErrorKind,
97        io::Result as IOResult,
98        marker::PhantomData,
99        path::{Path, PathBuf},
100        sync::{
101            atomic::{AtomicUsize, Ordering},
102            Arc,
103        },
104    };
105    pub(crate) use thiserror::Error as ThisError;
106    pub(crate) use tokio::{
107        fs::{read_dir, DirEntry},
108        sync::{RwLock, Semaphore},
109        time::{Instant, Duration},
110    };
111    pub(crate) use tokio_stream::StreamExt;
112    pub(crate) use error::IntoBincodeIfUnexpectedEofTrait;
113}
pearl/lib.rs

pearl/
lib.rs
