Make the insides of AllocationHandle private (vulkano-rs#2332)

* Make the insides of `AllocationHandle` private

* Fix naming

vulkano/src/memory/allocator/mod.rs

@@ -717,26 +717,60 @@ pub struct MemoryAlloc {
 }
 
 /// An opaque handle identifying an allocation inside an allocator.
-#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
-#[repr(transparent)]
-pub struct AllocationHandle(pub *mut ());
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+#[cfg_attr(not(doc), repr(transparent))]
+pub struct AllocationHandle(*mut ());
 
 unsafe impl Send for AllocationHandle {}
 unsafe impl Sync for AllocationHandle {}
 
 impl AllocationHandle {
-    /// Stores a index inside an `AllocationHandle`.
+    /// Creates a null `AllocationHandle`.
+    ///
+    /// Use this if you don't have anything that you need to associate with the allocation.
+    #[inline]
+    pub const fn null() -> Self {
+        AllocationHandle(ptr::null_mut())
+    }
+
+    /// Stores a pointer in an `AllocationHandle`.
+    ///
+    /// Use this if you want to associate an allocation with some (host) heap allocation.
+    #[inline]
+    pub const fn from_ptr(ptr: *mut ()) -> Self {
+        AllocationHandle(ptr)
+    }
+
+    /// Stores an index inside an `AllocationHandle`.
+    ///
+    /// Use this if you want to associate an allocation with some index.
     #[allow(clippy::useless_transmute)]
     #[inline]
     pub const fn from_index(index: usize) -> Self {
         // SAFETY: `usize` and `*mut ()` have the same layout.
         AllocationHandle(unsafe { mem::transmute::<usize, *mut ()>(index) })
     }
 
+    /// Retrieves a previously-stored pointer from the `AllocationHandle`.
+    ///
+    /// If this handle hasn't been created using [`from_ptr`] then this will return an invalid
+    /// pointer, dereferencing which is undefined behavior.
+    ///
+    /// [`from_ptr`]: Self::from_ptr
+    #[inline]
+    pub const fn as_ptr(self) -> *mut () {
+        self.0
+    }
+
     /// Retrieves a previously-stored index from the `AllocationHandle`.
+    ///
+    /// If this handle hasn't been created using [`from_index`] then this will return a bogus
+    /// result.
+    ///
+    /// [`from_index`]: Self::from_index
     #[allow(clippy::transmutes_expressible_as_ptr_casts)]
     #[inline]
-    pub const fn into_index(self) -> usize {
+    pub const fn as_index(self) -> usize {
         // SAFETY: `usize` and `*mut ()` have the same layout.
         unsafe { mem::transmute::<*mut (), usize>(self.0) }
     }
@@ -1414,7 +1448,7 @@ unsafe impl<S: Suballocator + Send + 'static> MemoryAllocator for GenericMemoryA
         Ok(MemoryAlloc {
             device_memory,
             suballocation: None,
-            allocation_handle: AllocationHandle(ptr::null_mut()),
+            allocation_handle: AllocationHandle::null(),
         })
     }
 
@@ -1544,7 +1578,7 @@ impl<S: Suballocator> Block<S> {
         Ok(MemoryAlloc {
             device_memory: self.device_memory.clone(),
             suballocation: Some(suballocation),
-            allocation_handle: AllocationHandle(self as *mut Block<S> as _),
+            allocation_handle: AllocationHandle::from_ptr(self as *mut Block<S> as _),
         })
     }
 

vulkano/src/memory/allocator/suballocator.rs

@@ -24,7 +24,6 @@ use std::{
     cmp,
     error::Error,
     fmt::{self, Debug, Display},
-    ptr,
 };
 
 /// Suballocators are used to divide a *region* into smaller *suballocations*.
@@ -499,7 +498,7 @@ unsafe impl Suballocator for FreeListAllocator {
     unsafe fn deallocate(&self, suballocation: Suballocation) {
         // SAFETY: The caller must guarantee that `suballocation` refers to a currently allocated
         // allocation of `self`.
-        let node_id = SlotId::new(suballocation.handle.into_index());
+        let node_id = SlotId::new(suballocation.handle.as_index());
 
         let state = unsafe { &mut *self.state.get() };
         let node = state.nodes.get_mut(node_id);
@@ -974,7 +973,7 @@ unsafe impl Suballocator for BuddyAllocator {
     #[inline]
     unsafe fn deallocate(&self, suballocation: Suballocation) {
         let mut offset = suballocation.offset;
-        let order = suballocation.handle.into_index();
+        let order = suballocation.handle.as_index();
 
         let min_order = order;
         let state = unsafe { &mut *self.state.get() };
@@ -1159,7 +1158,7 @@ unsafe impl Suballocator for BumpAllocator {
             offset,
             size,
             allocation_type,
-            handle: AllocationHandle(ptr::null_mut()),
+            handle: AllocationHandle::null(),
         })
     }
 

vulkano/src/memory/mod.rs

@@ -109,7 +109,7 @@ use std::{
     mem::ManuallyDrop,
     num::NonZeroU64,
     ops::{Bound, Range, RangeBounds, RangeTo},
-    ptr::{self, NonNull},
+    ptr::NonNull,
     sync::Arc,
 };
 
@@ -155,7 +155,7 @@ impl ResourceMemory {
             offset: 0,
             size: device_memory.allocation_size(),
             allocation_type: AllocationType::Unknown,
-            allocation_handle: AllocationHandle(ptr::null_mut()),
+            allocation_handle: AllocationHandle::null(),
             suballocation_handle: None,
             allocator: None,
             device_memory: ManuallyDrop::new(DeviceOwnedDebugWrapper(device_memory)),