pagedb 0.1.0-beta.4

Encrypted, portable, embedded page store with B+ tree and segment-file surfaces.
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

//! Virtual file-system abstraction: File trait, lock primitives, vectored I/O.
//!
//! A distinct backend is selected per target so each platform uses its best
//! async-I/O primitive (see [`DefaultVfs`] for the mapping). This module wires
//! the cfg matrix; callers use [`open_default`] or the [`DefaultVfs`] alias
//! and never have to spell the cfg themselves.

#[cfg(all(target_os = "android", target_arch = "arm"))]
pub mod android;
#[cfg(not(target_arch = "wasm32"))]
pub(crate) mod blocking;
#[cfg(any(target_os = "macos", target_os = "ios"))]
pub mod gcd;
#[cfg(target_os = "windows")]
pub mod iocp;
#[cfg(any(
    target_os = "linux",
    all(target_os = "android", not(target_arch = "arm")),
))]
pub mod iouring;
pub mod memory;
#[cfg(feature = "opfs")]
pub mod opfs;
#[cfg(not(target_arch = "wasm32"))]
pub mod tokio_backend;
// The backend contract is re-exported from `vfs` itself rather than published
// as a module path. Both files also hold crate-internal machinery — the
// positional-I/O progress rules, path canonicalization — that a public module
// would expose by accident purely because the traits had to live somewhere.
pub(crate) mod traits;
pub(crate) mod types;
pub mod wasi;

#[cfg(all(target_os = "android", target_arch = "arm"))]
pub use android::AndroidVfs;
#[cfg(any(target_os = "macos", target_os = "ios"))]
pub use gcd::GcdVfs;
#[cfg(target_os = "windows")]
pub use iocp::{IocpFile, IocpVfs};
#[cfg(any(
    target_os = "linux",
    all(target_os = "android", not(target_arch = "arm")),
))]
pub use iouring::{IouringFile, IouringVfs};
#[cfg(feature = "opfs")]
pub use opfs::OpfsVfs;
pub use traits::{Vfs, VfsFile};
pub(crate) use traits::{
    checked_read_progress, read_exact_at, read_exact_at_borrowed, write_all_at,
};
pub use types::{OpenMode, ReadReq, WriteReq};
pub use wasi::WasiVfs;

/// The default native VFS backend for the current target. Selected at
/// compile-time per platform to use the best async-I/O primitive available:
///
/// - Linux (and 64-bit Android): `IouringVfs` — `io_uring`.
/// - Windows: `IocpVfs` — IOCP overlapped I/O.
/// - macOS / iOS / iPadOS: `GcdVfs` — `dispatch_io`.
/// - Android (32-bit, legacy): `AndroidVfs` — thread-pool.
/// - Other native (BSDs etc.): `TokioVfs` — thread-pool fallback.
///
/// On `wasm32` targets, embedders construct `OpfsVfs` or `WasiVfs` directly
/// — there is no kernel async primitive to choose between.
#[cfg(any(
    target_os = "linux",
    all(target_os = "android", not(target_arch = "arm")),
))]
pub type DefaultVfs = IouringVfs;

#[cfg(target_os = "windows")]
pub type DefaultVfs = IocpVfs;

#[cfg(any(target_os = "macos", target_os = "ios"))]
pub type DefaultVfs = GcdVfs;

#[cfg(all(target_os = "android", target_arch = "arm"))]
pub type DefaultVfs = AndroidVfs;

#[cfg(all(
    not(target_arch = "wasm32"),
    not(target_os = "linux"),
    not(target_os = "windows"),
    not(target_os = "macos"),
    not(target_os = "ios"),
    not(target_os = "android"),
))]
pub type DefaultVfs = tokio_backend::TokioVfs;

/// Construct the best native VFS for the current target. Callers that don't
/// care which backend they're using (benchmarks, CLI tools, embedders that
/// just want "the right thing") should use this — it picks the platform's
/// fastest async-I/O primitive without leaking `cfg` into call sites.
#[cfg(not(target_arch = "wasm32"))]
pub fn open_default<P: AsRef<std::path::Path>>(path: P) -> crate::Result<DefaultVfs> {
    #[cfg(any(
        all(target_os = "linux", not(target_arch = "wasm32")),
        all(target_os = "android", not(target_arch = "arm")),
    ))]
    {
        IouringVfs::new(path.as_ref())
    }
    #[cfg(target_os = "windows")]
    {
        IocpVfs::new(path.as_ref())
    }
    #[cfg(any(target_os = "macos", target_os = "ios"))]
    {
        Ok(GcdVfs::new(path.as_ref()))
    }
    #[cfg(all(target_os = "android", target_arch = "arm"))]
    {
        Ok(AndroidVfs::new(path.as_ref()))
    }
    #[cfg(all(
        not(target_os = "linux"),
        not(target_os = "windows"),
        not(target_os = "macos"),
        not(target_os = "ios"),
        not(target_os = "android"),
    ))]
    {
        Ok(tokio_backend::TokioVfs::new(path.as_ref()))
    }
}