Add documented test for using structs after temporarily being part of a mutable pointer chain

This test is based on the trybuild failure test where the root structure
is still being alive and used when one of its pointer-chain members is
being accessed, violating mutable borrow rules.

Note that this pattern still doesn't apply mutable borrow rules to
*longer pointer chains where multiple structs* are pushed to the same
*root struct*, resulting in those structs now referencing each other
via `pNext` even after the root struct goes out of scope.  This is
implicitly handled - though not explicitly documented - by all Vulkan
function calls remaining `unsafe` and by `push()` asserting that
incoming structures have `pNext` set to `NULL`.

Unless those structs were pushed into each other manually while
preserving existing `pNext` pointers via `unsafe` `extend()`, which
commonly isn't even possible for arbitrary extension structures that
are not a root structure themselves (i.e. no other structure lists the
extension structure in a `structextends`).

Author: MarijnS95

ash/src/vk.rs

@@ -328,6 +328,25 @@ mod tests {
         assert_eq!(chain, chain2);
     }
 
+    #[test]
+    fn test_use_struct_after_pointer_chain() {
+        // The negative case of this test, where `pdev_props` stays alive by being
+        // used at the end of this function while `api` is invalidly accessed first
+        // (resulting in an immutable borrow while mutably borrowed error), exists in
+        // `tests/fail/long_lived_root_struct_borrow.rs`.  This test demonstrates the expected usage
+        // pattern of dropping `pdev_props` so that `api` no longer becomes mutably borrowed and the
+        // properties read from Vulkan can now be accessed by the caller.
+
+        let mut layers = vec![];
+        let mut api =
+            vk::PhysicalDeviceLayeredApiPropertiesListKHR::default().layered_apis(&mut layers);
+        let _pdev_props = vk::PhysicalDeviceProperties2::default().push(&mut api);
+
+        // Access to either variable is allowed because `pdev_props` is no longer used
+        dbg!(&api);
+        dbg!(&layers);
+    }
+
     #[test]
     fn test_debug_flags() {
         assert_eq!(

ash/tests/fail/long_lived_root_struct_borrow.rs

@@ -1,6 +1,9 @@
 use ash::vk::{self, TaggedStructure as _};
 
 fn main() {
+    // src/vk.rs holds a positive version of this test, demonstrating that `api` can be adequately
+    // accessed when `pdev_props` is no longer live.
+
     let mut layers = vec![];
     let mut api =
         vk::PhysicalDeviceLayeredApiPropertiesListKHR::default().layered_apis(&mut layers);

ash/tests/fail/long_lived_root_struct_borrow.stderr

@@ -1,23 +1,23 @@
 error[E0502]: cannot borrow `api` as immutable because it is also borrowed as mutable
-  --> tests/fail/long_lived_root_struct_borrow.rs:10:10
+  --> tests/fail/long_lived_root_struct_borrow.rs:13:10
    |
-7  |     let pdev_props = vk::PhysicalDeviceProperties2::default().push(&mut api);
+10 |     let pdev_props = vk::PhysicalDeviceProperties2::default().push(&mut api);
    |                                                                    -------- mutable borrow occurs here
 ...
-10 |     dbg!(&api);
+13 |     dbg!(&api);
    |          ^^^^ immutable borrow occurs here
 ...
-13 |     dbg!(pdev_props); // Holds a borrow on api and layers
+16 |     dbg!(pdev_props); // Holds a borrow on api and layers
    |          ---------- mutable borrow later used here
 
 error[E0502]: cannot borrow `layers` as immutable because it is also borrowed as mutable
-  --> tests/fail/long_lived_root_struct_borrow.rs:11:10
+  --> tests/fail/long_lived_root_struct_borrow.rs:14:10
    |
-6  |         vk::PhysicalDeviceLayeredApiPropertiesListKHR::default().layered_apis(&mut layers);
+9  |         vk::PhysicalDeviceLayeredApiPropertiesListKHR::default().layered_apis(&mut layers);
    |                                                                               ----------- mutable borrow occurs here
 ...
-11 |     dbg!(&layers);
+14 |     dbg!(&layers);
    |          ^^^^^^^ immutable borrow occurs here
-12 |
-13 |     dbg!(pdev_props); // Holds a borrow on api and layers
+15 |
+16 |     dbg!(pdev_props); // Holds a borrow on api and layers
    |          ---------- mutable borrow later used here