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
//! Embedded adapter from DataFusion to native GPU execution.
//!
//! The execution lifecycle progresses from [`backend::AlgeonGpuBackend`] through
//! session installation to [`attempt::AlgeonAttempt`]. The backend builder
//! assembles the immutable device envelope, [`session`] installs the native optimizer
//! on a caller-owned session builder, and each attempt plans and executes one
//! invocation before publishing a terminal report. Strict production policy
//! can enforce that no DataFusion CPU execution remains in the final physical
//! plan via [`planner::AlgeonGpuExecutionMode::NativeRequired`].
//!
//! ```no_run
//! use std::time::Duration;
//!
//! use algeon_datafusion::{
//! attempt::AttemptOptions,
//! backend::{
//! AlgeonGpuBackend, AlgeonGpuDeviceConfig, AlgeonGpuDeviceProfile, GpuMemoryOwnership,
//! },
//! };
//! use datafusion::{execution::SessionStateBuilder, prelude::SessionContext};
//! use futures::TryStreamExt;
//!
//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
//! // Ordinal `0` is the first process-visible CUDA device.
//! // `WholeDeviceExclusive` promises process-wide allocator ownership; it
//! // does not allocate device memory by itself.
//! let device = AlgeonGpuDeviceConfig::new(
//! AlgeonGpuDeviceProfile::new(0),
//! GpuMemoryOwnership::WholeDeviceExclusive,
//! );
//! let backend = AlgeonGpuBackend::builder().devices([device]).build()?;
//! let state = backend.install_on(SessionStateBuilder::new_with_default_features())?.build();
//! let ctx = SessionContext::new_with_state(state);
//!
//! let attempt = backend.begin_attempt(AttemptOptions::default())?;
//! // Taking the completion receiver prior to planning ensures the terminal report
//! // remains observable even if planning fails.
//! let completion = attempt.completion();
//! let stream = attempt.sql(&ctx, "SELECT 1 AS value").await?;
//! let _batches = stream.try_collect::<Vec<_>>().await?;
//! let terminal = completion.await;
//! println!("terminal outcome: {:?}", terminal.outcome);
//!
//! // Async shutdown waits for GPU-resource and observation quiescence without
//! // blocking the executor worker.
//! backend.close_and_wait_async(Duration::from_secs(10)).await?;
//! # Ok(())
//! # }
//! ```
//!
//! Applications start from [`backend`], install sessions through [`session`],
//! and execute through [`attempt`]. [`build_info`] reports the version,
//! commit, and enabled engines of this build. Planning-only diagnosis lives in
//! [`gpu_coverage`]; runtime exporter projection lives in [`observability`].
//!
//! Optional engines change plan classification when enabled. Without the
//! `cugraph` feature, cuGraph UDTFs fail closed with a typed
//! capability error. Without `cuvs` or `cuml`, the corresponding SQL family
//! remains discoverable but execution fails before input staging. Without
//! `nvml`, device telemetry reports `FeatureDisabled` for NVML and leaves the
//! NVML values `None`; CUDA telemetry, admission and memory accounting are
//! unchanged. The `bench-support`
//! and `qualification` features serve as internal harnesses; `bench-support`
//! provides application and test support facilities outside the embedded and
//! server report contract, whereas `qualification` closes admission on one live
//! device ledger for the multi-GPU validation tool. Enable `server` to embed
//! the Algeon Flight SQL server alongside the adapter.
extern crate self as algeon_datafusion;