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//! | [`StagingBuffer`]                     | Host (pinned)  | Reused H2D/D2H staging for hot paths     |
21//!
22//! ## Freestanding copy helpers
23//!
24//! The [`copy`] module exposes explicit transfer functions that mirror the
25//! CUDA driver `cuMemcpy*` family, with compile-time type safety and
26//! runtime length validation.
27//!
28//! ## Safety philosophy
29//!
30//! All public APIs return [`oxicuda_driver::error::CudaResult`] rather than panicking.  Size
31//! mismatches, zero-length allocations, and out-of-bounds slices are
32//! reported as [`oxicuda_driver::error::CudaError::InvalidValue`].  [`Drop`] implementations log
33//! errors via [`tracing::warn`] instead of panicking.
34//!
35//! ## Feature flags
36//!
37//! | Feature      | Description                                      |
38//! |--------------|--------------------------------------------------|
39//! | `pool`       | Enable stream-ordered memory pool (CUDA 11.2+)   |
40//! | `gpu-tests`  | Enable integration tests that require a real GPU  |
41//! | `half`       | `StagingPod` impls for `half::f16` / `half::bf16` |
42
43#![warn(missing_docs)]
44#![warn(clippy::all)]
45#![allow(clippy::module_name_repetitions)]
46
47// ---------------------------------------------------------------------------
48// Module declarations
49// ---------------------------------------------------------------------------
50
51pub mod aligned;
52pub mod bandwidth_profiler;
53pub mod buffer_view;
54pub mod compression;
55pub mod copy;
56pub mod copy_2d3d;
57pub mod device_buffer;
58pub mod host_buffer;
59pub mod host_registered;
60pub mod managed_hints;
61pub mod memory_info;
62pub mod numa;
63pub mod peer_copy;
64#[cfg(feature = "pool")]
65pub mod pool;
66pub mod pool_pressure;
67pub mod pool_stats;
68pub mod staging;
69pub mod unified;
70pub mod virtual_memory;
71pub mod zero_copy;
72
73// ---------------------------------------------------------------------------
74// Re-exports — primary buffer types
75// ---------------------------------------------------------------------------
76
77pub use bandwidth_profiler::{
78    BandwidthBenchmarkConfig, BandwidthMeasurement, BandwidthProfiler, BandwidthSummary,
79    DirectionSummary, TransferDirection, bandwidth_utilization, describe_bandwidth,
80    estimate_transfer_time, format_bytes, theoretical_peak_bandwidth,
81};
82pub use buffer_view::{BufferView, BufferViewMut};
83pub use compression::{
84    CompressedDeviceBuffer, CompressionPlan, CompressionSupport, CompressionType,
85    DEFAULT_COMPRESSION_GRANULARITY,
86};
87pub use copy_2d3d::{Memcpy2DParams, Memcpy3DParams};
88pub use device_buffer::{DeviceBuffer, DeviceSlice};
89pub use host_buffer::PinnedBuffer;
90pub use host_registered::{
91    RegisterFlags, RegisteredMemory, RegisteredMemoryType, RegisteredPointerInfo,
92    query_registered_pointer_info, register, register_slice, register_vec,
93};
94pub use managed_hints::{ManagedMemoryHints, MigrationPolicy, PrefetchPlan};
95pub use memory_info::{MemAdvice, MemoryInfo, mem_advise, mem_prefetch, memory_info};
96pub use numa::{
97    LOCAL_NUMA_DISTANCE, NumaAllocTracker, NumaBuffer, NumaTopology, closest_node_to_gpu,
98};
99pub use pool_pressure::{
100    MemoryPressureMonitor, PressureLevel, PressureSample, validate_thresholds,
101};
102pub use unified::UnifiedBuffer;
103pub use virtual_memory::{
104    AccessFlags, PhysicalAllocation, VirtualAddressRange, VirtualMemoryManager,
105};
106pub use zero_copy::MappedBuffer;
107
108pub use aligned::{
109    AlignedBuffer, Alignment, AlignmentInfo, check_alignment, coalesce_alignment,
110    optimal_alignment_for_type, round_up_to_alignment, validate_alignment,
111};
112
113pub use pool_stats::{AllocationHistogram, FragmentationMetrics, PoolReport, PoolStatsTracker};
114
115pub use staging::{DEFAULT_AUTO_STAGE_MAX_BYTES, StagingBuffer, StagingPod, StagingStats};
116
117#[cfg(feature = "pool")]
118pub use pool::{MemoryPool, PoolStats, PooledBuffer};
119
120// ---------------------------------------------------------------------------
121// Prelude — convenient glob import
122// ---------------------------------------------------------------------------
123
124/// Convenient glob import for common OxiCUDA Memory types.
125///
126/// ```rust
127/// use oxicuda_memory::prelude::*;
128/// ```
129pub mod prelude {
130    pub use crate::aligned::{AlignedBuffer, Alignment, AlignmentInfo};
131    pub use crate::buffer_view::{BufferView, BufferViewMut};
132    pub use crate::compression::{CompressedDeviceBuffer, CompressionSupport, CompressionType};
133    pub use crate::copy::{
134        copy_dtod, copy_dtod_async, copy_dtoh, copy_dtoh_async_raw, copy_dtoh_region_async,
135        copy_htod, copy_htod_async_raw, copy_htod_region_async,
136    };
137    pub use crate::copy_2d3d::{
138        Memcpy2DParams, Memcpy3DParams, copy_2d_dtod, copy_2d_dtoh, copy_2d_htod, copy_3d_dtod,
139    };
140    pub use crate::device_buffer::{DeviceBuffer, DeviceSlice};
141    pub use crate::host_buffer::PinnedBuffer;
142    pub use crate::host_registered::{
143        RegisterFlags, RegisteredMemory, RegisteredMemoryType, RegisteredPointerInfo,
144        query_registered_pointer_info, register, register_slice, register_vec,
145    };
146    pub use crate::managed_hints::{ManagedMemoryHints, MigrationPolicy, PrefetchPlan};
147    pub use crate::memory_info::{MemAdvice, MemoryInfo, mem_advise, mem_prefetch, memory_info};
148    pub use crate::numa::{NumaAllocTracker, NumaBuffer, NumaTopology};
149    pub use crate::pool_pressure::{MemoryPressureMonitor, PressureLevel};
150    pub use crate::unified::UnifiedBuffer;
151    pub use crate::virtual_memory::{AccessFlags, VirtualAddressRange, VirtualMemoryManager};
152}
153
154// ---------------------------------------------------------------------------
155// Compile-time feature availability
156// ---------------------------------------------------------------------------
157
158/// Compile-time feature availability.
159pub mod features {
160    /// Whether the stream-ordered memory pool API is enabled.
161    pub const HAS_POOL: bool = cfg!(feature = "pool");
162
163    /// Whether GPU integration tests are enabled.
164    pub const HAS_GPU_TESTS: bool = cfg!(feature = "gpu-tests");
165}
oxicuda_memory/lib.rs

oxicuda_memory/
lib.rs
