Document resources as unretained

And mark `commandBufferWithUnretainedReferences` as safe.

Author: madsmtm

crates/header-translator/src/rust_type.rs

@@ -1175,6 +1175,18 @@ impl PointeeTy {
                 // `MTLFence` (GPU side).
                 [(protocol, _)] if protocol.is_subprotocol_of("MTLResource") => {
                     let safety = TypeSafety::unknown_in_argument("may need to be synchronized");
+
+                    // Additionally, resources in a command buffer must be
+                    // kept alive by the application for as long as they're
+                    // used. If this is not done, it is possible to encounter
+                    // use-after-frees with:
+                    // - `MTLCommandBufferDescriptor::setRetainedReferences(false)`.
+                    // - `MTLCommandQueue::commandBufferWithUnretainedReferences()`.
+                    // - All `MTL4CommandBuffer`s.
+                    let safety = safety.merge(TypeSafety::unknown_in_argument(
+                        "may be unretained, you must ensure it is kept alive while in use",
+                    ));
+
                     // `MTLBuffer` is effectively a `Box<[u8]>` stored on the
                     // GPU (and depending on the storage mode, optionally also
                     // on the CPU). Type-safety of the contents is left

framework-crates/objc2-metal/src/lib.rs

@@ -32,7 +32,9 @@
 //!
 //! ## Shaders
 //!
-//! Loading shaders (via `MTLLibrary`, function stitching etc.) is perfectly
+//! Shaders are (often) written in an unsafe C-like language.
+//!
+//! Loading them (via `MTLLibrary`, function stitching etc.) is perfectly
 //! safe, it is similar to dynamic linking. The restrictions that e.g.
 //! `libloading::Library::new` labours under do not apply, since there are no
 //! ctors in [the Metal Shading Language][msl-spec] (see section 4.2).
@@ -56,17 +58,23 @@
 //!
 //! ## Synchronization
 //!
-//! `MTLResource` subclasses such as `MTLBuffer` require synchronization
-//! between the CPU and the GPU, or between different threads on the GPU
-//! itself, so APIs taking these are often unsafe.
+//! `MTLResource` subclasses such as `MTLBuffer` and `MTLTexture` require
+//! synchronization between the CPU and the GPU, or between different threads
+//! on the GPU itself, so APIs taking these are often unsafe.
+//!
+//! ## Memory management and lifetimes
 //!
-//! ## Resource allocation and memory management
+//! Resources used in `MTL4CommandBuffer`s or command buffers with created
+//! with one of:
+//! - `MTLCommandBufferDescriptor::setRetainedReferences(false)`.
+//! - `MTLCommandQueue::commandBufferWithUnretainedReferences()`.
 //!
-//! TODO.
+//! Must be kept alive for as long as they're used.
 //!
 //! ## Type safety
 //!
-//! TODO.
+//! `MTLBuffer` is untyped (in a similar manner as a `[u8]` slice), you must
+//! ensure that any usage of it is done with valid types.
 #![recursion_limit = "256"]
 #![allow(non_snake_case)]
 #![no_std]

framework-crates/objc2-metal/translation-config.toml

@@ -190,10 +190,15 @@ protocol.MTLResource.methods.makeAliasable.unsafe = true
 # TODO(breaking): Mark this as unsafe?
 class.MTLHeapDescriptor.methods."setType:".unsafe = false
 
-# These affect lifetime safety, and can cause use-after-free if used incorrectly.
-class.MTLCommandBufferDescriptor.methods."setRetainedReferences:".unsafe = true
-protocol.MTLCommandQueue.methods.commandBufferWithUnretainedReferences.unsafe = true
-protocol.MTLIOCommandQueue.methods.commandBufferWithUnretainedReferences.unsafe = true
+# SAFETY: We could consider marking these as unsafe, since they affect
+# lifetime safety, and can cause use-after-free if used incorrectly.
+#
+# Unretained references are the only option for `MTL4CommandBuffer`s though,
+# and we already mark `MTLResource`s as unsafe, so we choose to move the
+# unsafety of this to the resources instead.
+# class.MTLCommandBufferDescriptor.methods."setRetainedReferences:".unsafe = true
+# protocol.MTLCommandQueue.methods.commandBufferWithUnretainedReferences.unsafe = true
+# protocol.MTLIOCommandQueue.methods.commandBufferWithUnretainedReferences.unsafe = true
 
 # Must be a multiple of 4.
 class.MTLVertexBufferLayoutDescriptor.methods."setStride:".unsafe = true