Design
Algeon adds native GPU execution to DataFusion sessions. DataFusion provides SQL parsing, catalog management, and physical planning; Algeon lowers supported physical subtrees into GPU operations and emits Arrow record batches. These pages refer to that GPU path as native execution.
A query through the system
A native query executes filter, join, and aggregation kernels on GPU columns while the CPU handles planning, metadata reads, and task submission. The host application's Tokio runtime drives CPU coordination, while GPU kernels run on dedicated per-device runtimes (Runtimes and threads). Each query attempt executes on one GPU. Embedded applications and the Flight SQL server share this execution stack.
Priorities
The engine architecture follows three core constraints:
- The engine owns physical plan selection. The optimizer rule decides which candidates lower to native execution and which fragments remain on DataFusion CPU execution.
- Failed attempts return structured errors. Native failures retain typed codes across DataFusion and Flight boundaries with evidence for retry decisions. GPU execution does not fall back to CPU replay once started.
- Admission bounds device memory. Each attempt receives an immutable grant committed against the per-device ledger. Allocations exceeding the grant fail without reclaiming memory from concurrent attempts.
Module boundaries
The intermediate representation (IR) describes sources, operations and their dependencies. Ownership across the query crates is:
The adapter imports each query crate directly. The engine imports planning
and runtime. Runtime imports planning. These three query crates have no
DataFusion dependency. Imports come from the crate that owns the item.
algeon-iceberg imports the adapter and iceberg-rust; only algeon-server
imports it, behind its iceberg feature.
Below them, the GPU component crates provide Rust APIs over NVIDIA's RAPIDS libraries:
The adapter, runtime and engine call the components they need directly. Component APIs bind operations to a CUDA stream and memory resource. Native RAPIDS libraries perform the work. Shared interop contracts preserve buffer ownership across library boundaries. The cuDF binding design shows how one binding meets these rules: its layers, handle ownership, stream provenance and memory domains.
API documentation
algeon-datafusion is the application-facing Rust crate; the query and GPU
component crates, interop and build support are implementation dependencies
published with it. Visible adapter APIs, and the workspace-owned types they
expose, carry rustdoc at the defining item. The
API documentation boundary
defines that scope, and the documentation checks enforce it.
Runtimes and threads
Three Tokio runtimes serve a query.
The library builds no host runtime. The host's runtime needs the time driver
for admission waits and deadlines. The pool uses Tokio as a fixed-width thread
pool that keeps synchronous GPU calls off the host runtime. A job is an async
block with a synchronous GPU body and holds its worker until the body returns.
Query execution jobs take at most worker_count - 1 workers, which leaves one
for context setup and release cleanup. Chunk lane jobs and source reads use the
blocking lane of the same runtime.
A submission acquires a job-class permit immediately. When a class is
saturated, the service returns service_overloaded. Bounded waiting occurs
only within the admission queue. A pool worker waiting on asynchronous
completion parks in block_until without blocking the host runtime. A job
submitted from inside the same pool executes inline. Host-side spawn_blocking
covers backend close, server shutdown drains, the query-stats lease and
password verification.
Threads Algeon creates
An atexit hook joins registered CUDA-capable workers before libcudart tears
down.