Add Id::retain_autoreleased

An optimized version of `Id::retain` for when the previous caller returns an autoreleased value

objc2-foundation/tests/objc_id_retain_autoreleased.rs

@@ -0,0 +1,49 @@
+use std::ffi::c_void;
+use std::ptr::NonNull;
+
+use objc2::msg_send;
+use objc2::rc::{autoreleasepool, Id, Shared};
+use objc2_foundation::{INSObject, NSData};
+
+fn retain_count(obj: &NSData) -> usize {
+    unsafe { msg_send![obj, retainCount] }
+}
+
+fn create_data(bytes: &[u8]) -> Id<NSData, Shared> {
+    let bytes_ptr = bytes.as_ptr() as *const c_void;
+    unsafe {
+        // All code between the `msg_send!` and the `retain_autoreleased` must
+        // be able to be optimized away for this to work.
+        let obj: *mut NSData = msg_send![
+            NSData::class(),
+            dataWithBytes: bytes_ptr,
+            length: bytes.len(),
+        ];
+        Id::retain_autoreleased(NonNull::new_unchecked(obj))
+    }
+}
+
+#[test]
+fn test_retain_autoreleased() {
+    autoreleasepool(|_| {
+        let data = create_data(b"12");
+        // The autorelease-return-mechanism has to "warm up" somehow? At least
+        // for some reason the first time this is used it fails.
+        assert_eq!(retain_count(&data), 2);
+
+        // When compiled in release mode / with optimizations enabled,
+        // subsequent usage of `retain_autoreleased` will succeed in retaining
+        // the autoreleased value!
+        let expected_retain_count = if cfg!(debug_assertions) { 2 } else { 1 };
+
+        let data = create_data(b"34");
+        assert_eq!(retain_count(&data), expected_retain_count);
+
+        let data = create_data(b"56");
+        assert_eq!(retain_count(&data), expected_retain_count);
+
+        // Here we manually clean up the autorelease, so it will always be 1.
+        let data = autoreleasepool(|_| create_data(b"78"));
+        assert_eq!(retain_count(&data), 1);
+    });
+}

objc2/src/rc/id.rs

@@ -266,6 +266,23 @@ impl<T: Message, O: Ownership> Id<T, O> {
         NonNull::new(ptr).map(|ptr| unsafe { Id::retain(ptr) })
     }
 
+    /// TODO
+    #[doc(alias = "objc_retainAutoreleasedReturnValue")]
+    #[cfg_attr(not(debug_assertions), inline)]
+    pub unsafe fn retain_autoreleased(ptr: NonNull<T>) -> Id<T, O> {
+        // SAFETY: Same as `retain`, `objc_retainAutoreleasedReturnValue` is
+        // just an optimization.
+
+        let ptr = ptr.as_ptr() as *mut objc_sys::objc_object;
+        let res = unsafe { objc_sys::objc_retainAutoreleasedReturnValue(ptr) };
+        debug_assert_eq!(
+            res, ptr,
+            "objc_retainAutoreleasedReturnValue did not return the same pointer"
+        );
+        let res = unsafe { NonNull::new_unchecked(res as *mut T) };
+        unsafe { Self::new(res) }
+    }
+
     #[cfg_attr(not(debug_assertions), inline)]
     fn autorelease_inner(self) -> *mut T {
         // Note that this (and the actual `autorelease`) is not an associated
@@ -284,7 +301,6 @@ impl<T: Message, O: Ownership> Id<T, O> {
         res as *mut T
     }
 
-    // TODO: objc_retainAutoreleasedReturnValue
     // TODO: objc_autoreleaseReturnValue
     // TODO: objc_retainAutorelease
     // TODO: objc_retainAutoreleaseReturnValue