Skip to main content

oxidelake_compute/
lib.rs

1//! Physical operators (docs/SPEC.md §2.3): the `Gpu*Exec` DataFusion
2//! `ExecutionPlan`s, the backend-agnostic [`GpuOperator`] that runs each batch
3//! on the local backend with CPU fallback, and the conformance suite (in
4//! `tests/`) that pins every operator to the stock DataFusion semantics.
5//!
6//! * [`GpuFilterExec`] — fused filter + projection
7//! * [`GpuHashJoinExec`] — inner hash join on one `Int64` key
8//! * [`GpuAggregateExec`] — `SUM/COUNT/MIN/MAX` grouped by one `Int64` key
9//! * [`GpuVectorDistanceExec`] — L2 / cosine distance column
10//!
11//! Every exec records the *planned* backend (its `EXPLAIN` tag) but selects the
12//! *real* backend at `execute()` time from the local hardware detector, so a
13//! plan shipped to a machine without a GPU still runs correctly.
14//!
15//! Dependency direction: depends on `oxidelake-core`, `oxidelake-memory`, `oxidelake-device`.
16
17pub mod backend;
18pub mod display;
19pub mod exec;
20pub mod operator;
21pub mod udf;
22
23/// Which optional capabilities of this build change what a plan can say, as
24/// a bitmask.
25///
26/// A plan is only executable by an executor that can run every node in it,
27/// and the features decide what a planner will put there — `predict` adds a
28/// UDF the planner will happily reference and an executor without it cannot
29/// resolve. The plan codec folds this into its fingerprint so the mismatch
30/// is refused when the plan is decoded rather than discovered when it runs
31/// (#42), and a cluster scheduler refuses a worker whose fingerprint is not
32/// its own when the worker registers (#92).
33///
34/// Bit 0 `predict`. Bits 1 and 2 were `cuda` and `metal` until 0.3.0 and are
35/// retired, always zero: those features change where an operator runs, not
36/// what a plan says (`GpuNode` and the placement rule's output are the same
37/// with or without them), and counting them refused the heterogeneous
38/// cluster this project describes, a default-build scheduler with CUDA
39/// workers (#92). Append, never renumber: an old executor reading a new mask
40/// must still disagree with it, which it does as long as the bits it knows
41/// keep their places.
42pub const FEATURE_MASK: u32 = cfg!(feature = "predict") as u32;
43
44pub use backend::{init_local_backend, local_backend};
45pub use exec::{
46    GpuAggregateExec, GpuFilterExec, GpuHashJoinExec, GpuVectorDistanceExec,
47    aggregate_output_schema,
48};
49pub use operator::{GpuOperator, JoinBuild, JoinProbe};
50pub use oxidelake_core::params;
51pub use oxidelake_core::params::{
52    AggregateFunction, AggregateSpec, Comparison, DistanceMetric, Literal, Predicate,
53    gpu_eligible_scalar, vector_dimension,
54};
55#[cfg(feature = "predict")]
56pub mod predict;
57#[cfg(feature = "predict")]
58pub use predict::{ACTIVATION_KEY, Activation, Model, ModelSpec, PREDICT, predict_udf};
59
60pub use udf::{
61    COSINE_DISTANCE, L2_DISTANCE, cosine_distance_udf, distance_metric_for, distance_udf_name,
62    l2_distance_udf, literal_query, oxide_udfs, query_literal,
63};