cugraph/
lib.rs

1#![warn(clippy::undocumented_unsafe_blocks)]
2
3//! Workspace-internal safe libcugraph execution component for Algeon.
4//!
5//! Published as an Algeon implementation dependency. Applications use
6//! [`algeon-datafusion`](https://docs.rs/algeon-datafusion); workspace code
7//! uses this crate for its component contracts. See the
8//! [API documentation boundary](https://algeon.dev/design#api-documentation).
9//!
10//! Algeon integrations enter through a runtime-bound [`ResourceHandle`], use
11//! the prepared transfer contracts in [`cudf_interop`], and retain explicit
12//! producer readiness and consumer completion ordering. Native failures are
13//! preserved as structured [`Error`] values.
14//!
15//! # Key concepts
16//!
17//! - **[`cudf_interop`]**: canonical prepared cuDF graph ingress and result
18//!   egress for the Algeon engine.
19//! - **[`ResourceHandle`]**: long-lived owner of GPU execution provenance
20//!   (bound device, retained runtime, cuGraph resource handle). Not
21//!   thread-safe.
22//! - **[`EnteredContext`]**: short-lived execution session created by
23//!   [`ResourceHandle::enter`]. GPU-capable APIs require this token.
24//! - **[`DeviceArray<T>`]**: owning GPU array with compile-time element type.
25//!   Freed on drop. Create views via [`DeviceArray::view()`].
26//! - **[`GraphBuilder`]**: low-level builder for constructing a [`Graph`] from
27//!   pre-materialized device edge lists. Validates inputs before crossing the
28//!   FFI boundary.
29//! - **[`Graph<T>`]**: graph container parameterized by transposition state
30//!   ([`Forward`] or [`Transposed`]). Algorithm methods are constrained by the
31//!   required layout.
32//!
33//! # Type-state encoding
34//!
35//! The [`Graph<T>`] type parameter encodes whether storage is in forward or
36//! transposed layout. Algorithms enforce their required layout at compile time:
37//!
38//! - **[`Forward`]**: required by [`Graph::bfs`] and [`Graph::louvain`]
39//! - **[`Transposed`]**: required by [`Graph::pagerank`],
40//!   [`Graph::in_degrees`], [`Graph::degrees`]
41//! - **Generic** (`T: Transposition`): [`Graph::betweenness_centrality`],
42//!   [`Graph::force_atlas2`], [`Graph::out_degrees`]
43//!
44//! # cudf interop
45//!
46//! The [`cudf_interop`] module owns single-GPU prepared graph construction
47//! from cudf tables and result-to-DataFrame conversion. The prepared export
48//! contract is the canonical Algeon ingress path.
49
50pub mod array;
51pub mod centrality;
52pub mod community;
53mod cuda;
54pub mod cudf_interop;
55pub mod error;
56pub mod graph;
57pub mod handle;
58pub mod labeling;
59pub mod layout;
60pub mod params;
61pub mod random;
62pub mod sampling;
63pub mod similarity;
64pub mod structure;
65pub mod traversal;
66pub mod tree;
67pub mod types;
68
69// ═══════════════════════════════════════════════════════════════════════════
70// Crate-root re-exports; foundational cross-cutting types only
71// ═══════════════════════════════════════════════════════════════════════════
72
73// Arrays
74pub use array::{DeviceArray, DeviceArrayView};
75// Error handling
76pub use error::{AllocationFailureSource, AllocationSource, Error, ErrorKind, ErrorStatus};
77// Graph construction and type-state
78pub use graph::{Forward, Graph, GraphBuilder, ParkedGraph, Transposed, Transposition};
79// Infrastructure
80pub use handle::{EnteredContext, ResourceHandle};
81// Unified cross-module vertex input model
82pub use structure::VertexSelection;
cugraph/lib.rs

cugraph/
lib.rs
