oxicuda_memory/
lib.rs

1//! # OxiCUDA Memory
2//!
3//! **Type-safe GPU memory management with Rust ownership semantics.**
4//!
5//! `oxicuda-memory` provides safe, RAII-based wrappers around CUDA memory
6//! allocation and transfer operations.  Every buffer type owns its GPU (or
7//! pinned-host) allocation and automatically frees it on [`Drop`], preventing
8//! leaks without requiring manual cleanup.
9//!
10//! ## Buffer types
11//!
12//! | Type                                  | Location       | Description                              |
13//! |---------------------------------------|----------------|------------------------------------------|
14//! | [`DeviceBuffer<T>`]                   | Device (VRAM)  | Primary GPU-side buffer                  |
15//! | [`DeviceSlice<T>`]                    | Device (VRAM)  | Borrowed sub-range of a device buffer    |
16//! | [`PinnedBuffer<T>`]                   | Host (pinned)  | Page-locked host memory for fast DMA     |
17//! | [`UnifiedBuffer<T>`]                  | Unified/managed| Accessible from both host and device     |
18//! | [`MappedBuffer<T>`] *(stub)*          | Host-mapped    | Zero-copy host memory (future)           |
19//! | `MemoryPool` *(stub, `pool` feat)*    | Device pool    | Stream-ordered allocation (CUDA 11.2+)   |
20//!
21//! ## Freestanding copy helpers
22//!
23//! The [`copy`] module exposes explicit transfer functions that mirror the
24//! CUDA driver `cuMemcpy*` family, with compile-time type safety and
25//! runtime length validation.
26//!
27//! ## Safety philosophy
28//!
29//! All public APIs return [`oxicuda_driver::error::CudaResult`] rather than panicking.  Size
30//! mismatches, zero-length allocations, and out-of-bounds slices are
31//! reported as [`oxicuda_driver::error::CudaError::InvalidValue`].  [`Drop`] implementations log
32//! errors via [`tracing::warn`] instead of panicking.
33//!
34//! ## Feature flags
35//!
36//! | Feature      | Description                                      |
37//! |--------------|--------------------------------------------------|
38//! | `pool`       | Enable stream-ordered memory pool (CUDA 11.2+)   |
39//! | `gpu-tests`  | Enable integration tests that require a real GPU  |
40
41#![warn(missing_docs)]
42#![warn(clippy::all)]
43#![allow(clippy::module_name_repetitions)]
44
45// ---------------------------------------------------------------------------
46// Module declarations
47// ---------------------------------------------------------------------------
48
49pub mod aligned;
50pub mod bandwidth_profiler;
51pub mod buffer_view;
52pub mod copy;
53pub mod copy_2d3d;
54pub mod device_buffer;
55pub mod host_buffer;
56pub mod host_registered;
57pub mod managed_hints;
58pub mod memory_info;
59pub mod peer_copy;
60#[cfg(feature = "pool")]
61pub mod pool;
62pub mod pool_stats;
63pub mod unified;
64pub mod virtual_memory;
65pub mod zero_copy;
66
67// ---------------------------------------------------------------------------
68// Re-exports — primary buffer types
69// ---------------------------------------------------------------------------
70
71pub use bandwidth_profiler::{
72    BandwidthBenchmarkConfig, BandwidthMeasurement, BandwidthProfiler, BandwidthSummary,
73    DirectionSummary, TransferDirection, bandwidth_utilization, describe_bandwidth,
74    estimate_transfer_time, format_bytes, theoretical_peak_bandwidth,
75};
76pub use buffer_view::{BufferView, BufferViewMut};
77pub use copy_2d3d::{Memcpy2DParams, Memcpy3DParams};
78pub use device_buffer::{DeviceBuffer, DeviceSlice};
79pub use host_buffer::PinnedBuffer;
80pub use host_registered::{
81    RegisterFlags, RegisteredMemory, RegisteredMemoryType, RegisteredPointerInfo,
82    query_registered_pointer_info, register, register_slice, register_vec,
83};
84pub use managed_hints::{ManagedMemoryHints, MigrationPolicy, PrefetchPlan};
85pub use memory_info::{MemAdvice, MemoryInfo, mem_advise, mem_prefetch, memory_info};
86pub use unified::UnifiedBuffer;
87pub use virtual_memory::{
88    AccessFlags, PhysicalAllocation, VirtualAddressRange, VirtualMemoryManager,
89};
90pub use zero_copy::MappedBuffer;
91
92pub use aligned::{
93    AlignedBuffer, Alignment, AlignmentInfo, check_alignment, coalesce_alignment,
94    optimal_alignment_for_type, round_up_to_alignment, validate_alignment,
95};
96
97pub use pool_stats::{AllocationHistogram, FragmentationMetrics, PoolReport, PoolStatsTracker};
98
99#[cfg(feature = "pool")]
100pub use pool::{MemoryPool, PoolStats, PooledBuffer};
101
102// ---------------------------------------------------------------------------
103// Prelude — convenient glob import
104// ---------------------------------------------------------------------------
105
106/// Convenient glob import for common OxiCUDA Memory types.
107///
108/// ```rust
109/// use oxicuda_memory::prelude::*;
110/// ```
111pub mod prelude {
112    pub use crate::aligned::{AlignedBuffer, Alignment, AlignmentInfo};
113    pub use crate::buffer_view::{BufferView, BufferViewMut};
114    pub use crate::copy::{
115        copy_dtod, copy_dtod_async, copy_dtoh, copy_dtoh_async_raw, copy_htod, copy_htod_async_raw,
116    };
117    pub use crate::copy_2d3d::{
118        Memcpy2DParams, Memcpy3DParams, copy_2d_dtod, copy_2d_dtoh, copy_2d_htod, copy_3d_dtod,
119    };
120    pub use crate::device_buffer::{DeviceBuffer, DeviceSlice};
121    pub use crate::host_buffer::PinnedBuffer;
122    pub use crate::host_registered::{
123        RegisterFlags, RegisteredMemory, RegisteredMemoryType, RegisteredPointerInfo,
124        query_registered_pointer_info, register, register_slice, register_vec,
125    };
126    pub use crate::managed_hints::{ManagedMemoryHints, MigrationPolicy, PrefetchPlan};
127    pub use crate::memory_info::{MemAdvice, MemoryInfo, mem_advise, mem_prefetch, memory_info};
128    pub use crate::unified::UnifiedBuffer;
129    pub use crate::virtual_memory::{AccessFlags, VirtualAddressRange, VirtualMemoryManager};
130}
131
132// ---------------------------------------------------------------------------
133// Compile-time feature availability
134// ---------------------------------------------------------------------------
135
136/// Compile-time feature availability.
137pub mod features {
138    /// Whether the stream-ordered memory pool API is enabled.
139    pub const HAS_POOL: bool = cfg!(feature = "pool");
140
141    /// Whether GPU integration tests are enabled.
142    pub const HAS_GPU_TESTS: bool = cfg!(feature = "gpu-tests");
143}
oxicuda_memory/lib.rs

oxicuda_memory/
lib.rs
