Deduplicate push()/extend() helpers as a default impl on TaggedStructure (#994)

Having these functions generated for every root struct in our
definitions file contributes to significant bloat, in part because
of their massive documentation comments and not containing any
generator-dynamic code or identifiers.

Now that `trait Extends{Root}` was generalized into a single `trait
Extends<Root>` with the root structure as generic argument, it becomes
possible to build on top of that and define a default trait function on
every Vulkan structure.  These functions require the "pushed" type to
derive `Extends<Self>`, hence limiting the function to be called
without ever having to track if the root structure is being extended.

Author: MarijnS95

Changelog.md

@@ -29,6 +29,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `push_next()` has been renamed to `extend()` and marked as `unsafe`. Users are encouraged to call `push()` for singular structs instead. (#909)
 - Changed and renamed `RawPtr::as_raw_ptr(&self)` trait function to a by-value `RawPtr::to_raw_ptr(self)` function. (#965)
 - All `Extends{Root}` traits have been replaced with a single `Extends<Root>` trait using generics. (#971)
+- Moved `push()` and `extend()` methods from individual Vulkan structs (builders) into the `TaggedStructure` trait. (#994)
+  This trait must be imported in scope (`use ash::vk::TaggedStructure as _;`) to use the `push()` and `extend()` methods.
 
 ### Removed
 

ash/src/vk.rs

@@ -49,11 +49,83 @@ pub trait Handle: Sized {
     }
 }
 
+/// Iterates through the pointer chain. Includes the item that is passed into the function. Stops at
+/// the last [`BaseOutStructure`] that has a null [`BaseOutStructure::p_next`] field.
+pub(crate) unsafe fn ptr_chain_iter<'a, T: TaggedStructure<'a>>(
+    ptr: &mut T,
+) -> impl Iterator<Item = *mut BaseOutStructure<'_>> {
+    let ptr = <*mut T>::cast::<BaseOutStructure<'_>>(ptr);
+    (0..).scan(ptr, |p_ptr, _| {
+        if p_ptr.is_null() {
+            return None;
+        }
+        let n_ptr = (**p_ptr).p_next;
+        let old = *p_ptr;
+        *p_ptr = n_ptr;
+        Some(old)
+    })
+}
+
 /// Structures implementing this trait are layout-compatible with [`BaseInStructure`] and
 /// [`BaseOutStructure`]. Such structures have an `s_type` field indicating its type, which must
 /// always match the value of [`TaggedStructure::STRUCTURE_TYPE`].
-pub unsafe trait TaggedStructure {
+pub unsafe trait TaggedStructure<'a>: Sized {
     const STRUCTURE_TYPE: StructureType;
+
+    /// Prepends the given extension struct between the root and the first pointer. This method is
+    /// only available on structs that can be passed to a function directly. Only valid extension
+    /// structs can be pushed into the chain.
+    /// If the chain looks like `A -> B -> C`, and you call `A.push(&mut D)`, then the
+    /// chain will look like `A -> D -> B -> C`.
+    ///
+    /// # Panics
+    /// If `next` contains a pointer chain of its own, this function will panic.  Call `unsafe`
+    /// [`Self::extend()`] to insert this chain instead.
+    fn push<T: Extends<Self> + TaggedStructure<'a>>(mut self, next: &'a mut T) -> Self {
+        // SAFETY: All implementers of `TaggedStructure` are required to have the `BaseOutStructure` layout
+        let slf_base = unsafe { &mut *<*mut _>::cast::<BaseOutStructure<'_>>(&mut self) };
+        // SAFETY: All implementers of `T: TaggedStructure` are required to have the `BaseOutStructure` layout
+        let next_base = unsafe { &mut *<*mut T>::cast::<BaseOutStructure<'_>>(next) };
+        // `next` here can contain a pointer chain.  This function refuses to insert the struct,
+        // in favour of calling unsafe extend().
+        assert!(
+            next_base.p_next.is_null(),
+            "push() expects a struct without an existing p_next pointer chain (equal to NULL)"
+        );
+        next_base.p_next = slf_base.p_next;
+        slf_base.p_next = next_base;
+        self
+    }
+
+    /// Prepends the given extension struct between the root and the first pointer. This method is
+    /// only available on structs that can be passed to a function directly. Only valid extension
+    /// structs can be pushed into the chain.
+    /// If the chain looks like `A -> B -> C` and `D -> E`, and you call `A.extend(&mut D)`,
+    /// then the chain will look like `A -> D -> E -> B -> C`.
+    ///
+    /// # Safety
+    /// This function will walk the [`BaseOutStructure::p_next`] chain of `next`, requiring
+    /// all non-`NULL` pointers to point to a valid Vulkan structure starting with the
+    /// [`BaseOutStructure`] layout.
+    ///
+    /// The last struct in this chain (i.e. the one where `p_next` is `NULL`) must be writable
+    /// memory, as its `p_next` field will be updated with the value of `self.p_next`.
+    unsafe fn extend<T: Extends<Self> + TaggedStructure<'a>>(mut self, next: &'a mut T) -> Self {
+        // `next` here can contain a pointer chain. This means that we must correctly attach he head
+        // to the root and the tail to the rest of the chain For example:
+        //
+        // next = A -> B
+        // Before: `Root -> C -> D -> E`
+        // After: `Root -> A -> B -> C -> D -> E`
+        //                 ^^^^^^
+        //                 next chain
+        let slf_base = unsafe { &mut *<*mut _>::cast::<BaseOutStructure<'_>>(&mut self) };
+        let next_base = <*mut T>::cast::<BaseOutStructure<'_>>(next);
+        let last_next = ptr_chain_iter(next).last().unwrap();
+        (*last_next).p_next = slf_base.p_next;
+        slf_base.p_next = next_base;
+        self
+    }
 }
 
 /// Implemented for every structure that extends base structure `B`. Concretely that means struct
@@ -65,23 +137,6 @@ pub unsafe trait TaggedStructure {
 /// [1]: https://registry.khronos.org/vulkan/specs/latest/styleguide.html#extensions-interactions
 pub unsafe trait Extends<B> {}
 
-/// Iterates through the pointer chain. Includes the item that is passed into the function.
-/// Stops at the last [`BaseOutStructure`] that has a null [`BaseOutStructure::p_next`] field.
-pub(crate) unsafe fn ptr_chain_iter<T: ?Sized>(
-    ptr: &mut T,
-) -> impl Iterator<Item = *mut BaseOutStructure<'_>> {
-    let ptr = <*mut T>::cast::<BaseOutStructure<'_>>(ptr);
-    (0..).scan(ptr, |p_ptr, _| {
-        if p_ptr.is_null() {
-            return None;
-        }
-        let n_ptr = (**p_ptr).p_next;
-        let old = *p_ptr;
-        *p_ptr = n_ptr;
-        Some(old)
-    })
-}
-
 /// Holds 24 bits in the least significant bits of memory,
 /// and 8 bytes in the most significant bits of that memory,
 /// occupying a single [`u32`] in total. This is commonly used in
@@ -211,6 +266,7 @@ pub(crate) fn debug_flags<Value: Into<u64> + Copy>(
 #[cfg(test)]
 mod tests {
     use crate::vk;
+    use crate::vk::TaggedStructure as _;
     use alloc::vec::Vec;
     #[test]
     fn test_ptr_chains() {
@@ -272,21 +328,6 @@ mod tests {
         assert_eq!(chain, chain2);
     }
 
-    #[test]
-    fn test_dynamic_add_to_ptr_chain() {
-        let mut variable_pointers = vk::PhysicalDeviceVariablePointerFeatures::default();
-        let variable_pointers: &mut dyn vk::Extends<vk::DeviceCreateInfo<'_>> =
-            &mut variable_pointers;
-        let chain = alloc::vec![<*mut _>::cast(variable_pointers)];
-        let mut device_create_info = vk::DeviceCreateInfo::default().push(variable_pointers);
-        let chain2: Vec<*mut vk::BaseOutStructure<'_>> = unsafe {
-            vk::ptr_chain_iter(&mut device_create_info)
-                .skip(1)
-                .collect()
-        };
-        assert_eq!(chain, chain2);
-    }
-
     #[test]
     fn test_debug_flags() {
         assert_eq!(