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 compression;
53pub mod copy;
54pub mod copy_2d3d;
55pub mod device_buffer;
56pub mod host_buffer;
57pub mod host_registered;
58pub mod managed_hints;
59pub mod memory_info;
60pub mod numa;
61pub mod peer_copy;
62#[cfg(feature = "pool")]
63pub mod pool;
64pub mod pool_pressure;
65pub mod pool_stats;
66pub mod unified;
67pub mod virtual_memory;
68pub mod zero_copy;
69
70// ---------------------------------------------------------------------------
71// Re-exports — primary buffer types
72// ---------------------------------------------------------------------------
73
74pub use bandwidth_profiler::{
75    BandwidthBenchmarkConfig, BandwidthMeasurement, BandwidthProfiler, BandwidthSummary,
76    DirectionSummary, TransferDirection, bandwidth_utilization, describe_bandwidth,
77    estimate_transfer_time, format_bytes, theoretical_peak_bandwidth,
78};
79pub use buffer_view::{BufferView, BufferViewMut};
80pub use compression::{
81    CompressedDeviceBuffer, CompressionPlan, CompressionSupport, CompressionType,
82    DEFAULT_COMPRESSION_GRANULARITY,
83};
84pub use copy_2d3d::{Memcpy2DParams, Memcpy3DParams};
85pub use device_buffer::{DeviceBuffer, DeviceSlice};
86pub use host_buffer::PinnedBuffer;
87pub use host_registered::{
88    RegisterFlags, RegisteredMemory, RegisteredMemoryType, RegisteredPointerInfo,
89    query_registered_pointer_info, register, register_slice, register_vec,
90};
91pub use managed_hints::{ManagedMemoryHints, MigrationPolicy, PrefetchPlan};
92pub use memory_info::{MemAdvice, MemoryInfo, mem_advise, mem_prefetch, memory_info};
93pub use numa::{
94    LOCAL_NUMA_DISTANCE, NumaAllocTracker, NumaBuffer, NumaTopology, closest_node_to_gpu,
95};
96pub use pool_pressure::{
97    MemoryPressureMonitor, PressureLevel, PressureSample, validate_thresholds,
98};
99pub use unified::UnifiedBuffer;
100pub use virtual_memory::{
101    AccessFlags, PhysicalAllocation, VirtualAddressRange, VirtualMemoryManager,
102};
103pub use zero_copy::MappedBuffer;
104
105pub use aligned::{
106    AlignedBuffer, Alignment, AlignmentInfo, check_alignment, coalesce_alignment,
107    optimal_alignment_for_type, round_up_to_alignment, validate_alignment,
108};
109
110pub use pool_stats::{AllocationHistogram, FragmentationMetrics, PoolReport, PoolStatsTracker};
111
112#[cfg(feature = "pool")]
113pub use pool::{MemoryPool, PoolStats, PooledBuffer};
114
115// ---------------------------------------------------------------------------
116// Prelude — convenient glob import
117// ---------------------------------------------------------------------------
118
119/// Convenient glob import for common OxiCUDA Memory types.
120///
121/// ```rust
122/// use oxicuda_memory::prelude::*;
123/// ```
124pub mod prelude {
125    pub use crate::aligned::{AlignedBuffer, Alignment, AlignmentInfo};
126    pub use crate::buffer_view::{BufferView, BufferViewMut};
127    pub use crate::compression::{CompressedDeviceBuffer, CompressionSupport, CompressionType};
128    pub use crate::copy::{
129        copy_dtod, copy_dtod_async, copy_dtoh, copy_dtoh_async_raw, copy_dtoh_region_async,
130        copy_htod, copy_htod_async_raw, copy_htod_region_async,
131    };
132    pub use crate::copy_2d3d::{
133        Memcpy2DParams, Memcpy3DParams, copy_2d_dtod, copy_2d_dtoh, copy_2d_htod, copy_3d_dtod,
134    };
135    pub use crate::device_buffer::{DeviceBuffer, DeviceSlice};
136    pub use crate::host_buffer::PinnedBuffer;
137    pub use crate::host_registered::{
138        RegisterFlags, RegisteredMemory, RegisteredMemoryType, RegisteredPointerInfo,
139        query_registered_pointer_info, register, register_slice, register_vec,
140    };
141    pub use crate::managed_hints::{ManagedMemoryHints, MigrationPolicy, PrefetchPlan};
142    pub use crate::memory_info::{MemAdvice, MemoryInfo, mem_advise, mem_prefetch, memory_info};
143    pub use crate::numa::{NumaAllocTracker, NumaBuffer, NumaTopology};
144    pub use crate::pool_pressure::{MemoryPressureMonitor, PressureLevel};
145    pub use crate::unified::UnifiedBuffer;
146    pub use crate::virtual_memory::{AccessFlags, VirtualAddressRange, VirtualMemoryManager};
147}
148
149// ---------------------------------------------------------------------------
150// Compile-time feature availability
151// ---------------------------------------------------------------------------
152
153/// Compile-time feature availability.
154pub mod features {
155    /// Whether the stream-ordered memory pool API is enabled.
156    pub const HAS_POOL: bool = cfg!(feature = "pool");
157
158    /// Whether GPU integration tests are enabled.
159    pub const HAS_GPU_TESTS: bool = cfg!(feature = "gpu-tests");
160}
oxicuda_memory/lib.rs

oxicuda_memory/
lib.rs
