rudb_vector/lib.rs
1//! Vectors, physical forms, validity, selection vectors and the string representation.
2//!
3//! Rank 1 in the layer rule. See `xtask/layers.toml` and `spec/18-package-layout.md`.
4//!
5//! This is the interface `spec/07-execution.md` section 7.1 calls the widest one in the system.
6//! Every operator in every later crate is written against it, which is why it is specified before
7//! the first operator exists and changed by RFC afterwards rather than by whoever needs it changed.
8//!
9//! Four pieces:
10//!
11//! - [`Vector`], a typed run of at most [`VECTOR_SIZE`] values in one of four physical forms.
12//! - [`Validity`], which is three cases rather than a bitmap, because knowing there are no nulls is
13//! worth a measurable amount and costs one branch per vector to know.
14//! - [`Selection`], which is what a filter produces instead of compacting.
15//! - [`StringView`] and [`StringColumn`], the 16 byte string with the 4 byte prefix.
16//!
17//! # What is deliberately not here
18//!
19//! Encoded vectors are M3 work, not because they are hard but because they only pay off alongside
20//! the specialization contract that decides when to decode. Borrowed buffers are M2 work, because
21//! there is no buffer manager to borrow from. Nested storage is M2 work for the same reason. Each
22//! of these is a place the interface will grow, and each one is named here so that growing it is a
23//! decision somebody makes rather than something that happens.
24//!
25//! # Unsafe
26//!
27//! This crate is on the list in `spec/16-testing.md` section 16.7 that is allowed `unsafe`, and it
28//! does not use any yet. The safe version is the baseline every unsafe version has to beat on a
29//! benchmark before it lands, so writing it first is not a detour.
30//!
31//! The lint below is `deny` rather than `forbid` for exactly that reason. Denied means an unsafe
32//! block needs an `allow` written next to it, which is a line a reviewer sees. Forbidden would mean
33//! the first genuinely faster kernel has to start by editing this file, and a rule that gets
34//! deleted the first time it is inconvenient was never a rule.
35
36#![deny(unsafe_code)]
37
38pub mod selection;
39pub mod string;
40pub mod validity;
41pub mod vector;
42
43pub use selection::Selection;
44pub use string::{INLINE_LIMIT, StringColumn, StringView};
45pub use validity::{Bitmap, Validity};
46pub use vector::{Data, Form, VECTOR_SIZE, Vector};