Automatically retain dispatch objects

And merge some high-level binding types with their `ffi` counterparts.

This allows bindings to use nullability information, and unlocks using
dispatch2 types in framework crates.

Part of #77.

Author: madsmtm

crates/dispatch2/CHANGELOG.md

@@ -24,6 +24,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
   (e.g. `DispatchGroup`, `DispatchQueue` and `DispatchOnce`).
 
   Some of the old names are kept (but deprecated) for easier migration.
+- Handle memory management in `ffi` module automatically.
+- Merged some high-level binding types with their `ffi` "_t"/"_s" counterparts.
+  E.g. `dispatch_group_t`, `dispatch_group_s` and `DispatchGroup` are now one
+  type.
 
 ### Removed
 - **BREAKING**: Removed `TargetQueueError` and the error case in

crates/dispatch2/src/data.rs

@@ -0,0 +1,15 @@
+dispatch_object!(
+    /// Dispatch data.
+    #[doc(alias = "dispatch_data_t")]
+    #[doc(alias = "dispatch_data_s")]
+    pub struct DispatchData;
+);
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // Intentionally not Send + Sync, as `DispatchData` can contain things
+    // like `NSData`.
+    static_assertions::assert_not_impl_any!(DispatchData: Send, Sync);
+}

crates/dispatch2/src/ffi.rs

@@ -3,16 +3,20 @@
 #![allow(missing_docs, non_camel_case_types)]
 
 use core::ffi::{c_long, c_uint, c_ulong, c_void};
-use core::ptr::addr_of;
 
 #[cfg(feature = "objc2")]
 use objc2::encode::{Encode, Encoding, RefEncode};
 
 // Try to generate as much as possible.
 pub use crate::generated::*;
+pub(crate) use crate::*;
+
+pub(crate) type dispatch_data_s = DispatchData;
+pub(crate) type dispatch_queue_attr_s = DispatchQueueAttr;
+pub(crate) type dispatch_queue_s = DispatchQueue;
 
 macro_rules! create_opaque_type {
-    ($type_name: ident, $typedef_name: ident) => {
+    ($type_name: ident) => {
         #[repr(C)]
         #[derive(Copy, Clone, Debug)]
         #[allow(missing_docs)]
@@ -21,9 +25,6 @@ macro_rules! create_opaque_type {
             _inner: [u8; 0],
         }
 
-        #[allow(missing_docs)]
-        pub type $typedef_name = *mut $type_name;
-
         #[cfg(feature = "objc2")]
         // SAFETY: Dispatch types are internally objects.
         unsafe impl RefEncode for $type_name {
@@ -66,9 +67,15 @@ macro_rules! enum_with_val {
     }
 }
 
-create_opaque_type!(dispatch_object_s, dispatch_object_t);
-create_opaque_type!(dispatch_data_s, dispatch_data_t);
-create_opaque_type!(dispatch_source_type_s, dispatch_source_type_t);
+create_opaque_type!(dispatch_object_s);
+
+#[allow(missing_docs)]
+pub type dispatch_object_t = *mut dispatch_object_s;
+
+create_opaque_type!(dispatch_source_type_s);
+
+#[allow(missing_docs)]
+pub type dispatch_source_type_t = *mut dispatch_source_type_s;
 
 /// The prototype of functions submitted to dispatch queues.
 ///
@@ -94,29 +101,17 @@ unsafe impl RefEncode for dispatch_time_t {
     const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
 }
 
-create_opaque_type!(dispatch_group_s, dispatch_group_t);
-create_opaque_type!(dispatch_queue_global_s, dispatch_queue_global_t);
-create_opaque_type!(dispatch_queue_serial_s, dispatch_queue_serial_t);
-create_opaque_type!(dispatch_queue_main_s, dispatch_queue_main_t);
-create_opaque_type!(dispatch_queue_concurrent_s, dispatch_queue_concurrent_t);
-create_opaque_type!(dispatch_queue_attr_s, dispatch_queue_attr_t);
-create_opaque_type!(dispatch_semaphore_s, dispatch_semaphore_t);
-create_opaque_type!(dispatch_source_s, dispatch_source_t);
-create_opaque_type!(dispatch_queue_s, dispatch_queue_t);
-create_opaque_type!(dispatch_workloop_s, dispatch_workloop_t);
-create_opaque_type!(dispatch_io_s, dispatch_io_t);
-
 /// A dispatch queue that executes blocks serially in FIFO order.
-pub const DISPATCH_QUEUE_SERIAL: dispatch_queue_attr_t = core::ptr::null_mut();
+pub const DISPATCH_QUEUE_SERIAL: Option<&DispatchQueueAttr> = None;
 /// A dispatch queue that executes blocks concurrently.
-pub static DISPATCH_QUEUE_CONCURRENT: &dispatch_queue_attr_s = {
+pub static DISPATCH_QUEUE_CONCURRENT: Option<&DispatchQueueAttr> = {
     // Safety: immutable external definition
-    unsafe { &_dispatch_queue_attr_concurrent }
+    unsafe { Some(&_dispatch_queue_attr_concurrent) }
 };
 
-pub const DISPATCH_APPLY_AUTO: dispatch_queue_t = core::ptr::null_mut();
-pub const DISPATCH_TARGET_QUEUE_DEFAULT: dispatch_queue_t = core::ptr::null_mut();
-pub const DISPATCH_CURRENT_QUEUE_LABEL: dispatch_queue_t = core::ptr::null_mut();
+pub const DISPATCH_APPLY_AUTO: Option<&DispatchQueue> = None;
+pub const DISPATCH_TARGET_QUEUE_DEFAULT: Option<&DispatchQueue> = None;
+pub const DISPATCH_CURRENT_QUEUE_LABEL: Option<&DispatchQueue> = None;
 
 pub const DISPATCH_TIME_NOW: dispatch_time_t = dispatch_time_t(0);
 pub const DISPATCH_TIME_FOREVER: dispatch_time_t = dispatch_time_t(u64::MAX);
@@ -239,8 +234,8 @@ extern "C" {
 }
 
 // Inline function in the header
-#[allow(unused_unsafe)] // MSRV. Also, we'd like to mark this as `const`
-pub extern "C" fn dispatch_get_main_queue() -> dispatch_queue_main_t {
-    // SAFETY: Always safe to get pointer from static, only needed for MSRV.
-    unsafe { addr_of!(_dispatch_main_q) as dispatch_queue_main_t }
+// TODO: Mark this as `const`
+pub extern "C" fn dispatch_get_main_queue() -> &'static DispatchQueue {
+    // SAFETY: The main queue is safe to access from anywhere.
+    unsafe { &_dispatch_main_q }
 }

crates/dispatch2/src/group.rs

@@ -1,6 +1,5 @@
 use alloc::boxed::Box;
 use core::ffi::c_void;
-use core::ptr::NonNull;
 use core::time::Duration;
 
 use crate::{DispatchObject, DispatchQueue, DispatchRetained};
@@ -10,6 +9,8 @@ use super::{ffi::*, WaitError};
 
 dispatch_object!(
     /// Dispatch group.
+    #[doc(alias = "dispatch_group_t")]
+    #[doc(alias = "dispatch_group_s")]
     pub struct DispatchGroup;
 );
 
@@ -18,13 +19,9 @@ dispatch_object_not_data!(unsafe DispatchGroup);
 impl DispatchGroup {
     /// Creates a new [`DispatchGroup`].
     pub fn new() -> Option<DispatchRetained<Self>> {
-        // Safety: valid to call.
-        let ptr = unsafe { dispatch_group_create() };
-
-        NonNull::new(ptr).map(|ptr| {
-            // SAFETY: The object came from a "create" method.
-            unsafe { DispatchRetained::from_raw(ptr.cast()) }
-        })
+        // SAFETY: Valid to call.
+        // TODO: Properly allow NULL again (`dispatch_group_create` is incorrectly mapped).
+        Some(unsafe { dispatch_group_create() })
     }
 
     /// Submit a function to a [`DispatchQueue`] and associates it with the [`DispatchGroup`].
@@ -38,12 +35,7 @@ impl DispatchGroup {
 
         // Safety: All parameters cannot be null.
         unsafe {
-            dispatch_group_async_f(
-                self.as_raw(),
-                queue.as_raw(),
-                work_boxed,
-                function_wrapper::<F>,
-            );
+            dispatch_group_async_f(self, queue, work_boxed, function_wrapper::<F>);
         }
     }
 
@@ -62,7 +54,7 @@ impl DispatchGroup {
         };
 
         // Safety: object cannot be null and timeout is valid.
-        let result = unsafe { dispatch_group_wait(self.as_raw(), timeout) };
+        let result = unsafe { dispatch_group_wait(self, timeout) };
 
         match result {
             0 => Ok(()),
@@ -79,32 +71,17 @@ impl DispatchGroup {
 
         // Safety: All parameters cannot be null.
         unsafe {
-            dispatch_group_notify_f(
-                self.as_raw(),
-                queue.as_raw(),
-                work_boxed,
-                function_wrapper::<F>,
-            );
+            dispatch_group_notify_f(self, queue, work_boxed, function_wrapper::<F>);
         }
     }
 
     /// Explicitly indicates that the function has entered the [`DispatchGroup`].
     pub fn enter(&self) -> DispatchGroupGuard {
         // Safety: object cannot be null.
-        unsafe { dispatch_group_enter(self.as_raw()) };
+        unsafe { dispatch_group_enter(self) };
 
         DispatchGroupGuard(self.retain())
     }
-
-    /// Get the raw [dispatch_group_t] value.
-    ///
-    /// # Safety
-    ///
-    /// - Object shouldn't be released manually.
-    pub const unsafe fn as_raw(&self) -> dispatch_group_t {
-        let ptr: *const Self = self;
-        ptr as dispatch_group_t
-    }
 }
 
 /// Dispatch group guard.
@@ -122,6 +99,6 @@ impl DispatchGroupGuard {
 impl Drop for DispatchGroupGuard {
     fn drop(&mut self) {
         // SAFETY: Dispatch group cannot be null.
-        unsafe { dispatch_group_leave(self.0.as_raw()) };
+        unsafe { dispatch_group_leave(&self.0) };
     }
 }

crates/dispatch2/src/io.rs

@@ -0,0 +1,8 @@
+dispatch_object!(
+    /// Dispatch IO.
+    #[doc(alias = "dispatch_io_t")]
+    #[doc(alias = "dispatch_io_s")]
+    pub struct DispatchIO;
+);
+
+dispatch_object_not_data!(unsafe DispatchIO);

crates/dispatch2/src/lib.rs

@@ -42,17 +42,20 @@ use core::marker::{PhantomData, PhantomPinned};
 
 use self::ffi::dispatch_qos_class_t;
 
+mod data;
 pub mod ffi;
 #[allow(clippy::undocumented_unsafe_blocks)]
 mod generated;
 mod group;
+mod io;
 #[cfg(feature = "objc2")]
 mod main_thread_bound;
 mod object;
 mod once;
 mod queue;
 mod retained;
 mod semaphore;
+mod source;
 mod utils;
 mod workloop;
 
@@ -100,16 +103,20 @@ impl From<QualityOfServiceClass> for dispatch_qos_class_t {
     }
 }
 
+pub use self::data::DispatchData;
 pub use self::group::{DispatchGroup, DispatchGroupGuard};
+pub use self::io::DispatchIO;
 #[cfg(feature = "objc2")]
 pub use self::main_thread_bound::{run_on_main, MainThreadBound};
 pub use self::object::{DispatchObject, QualityOfServiceClassFloorError};
 pub use self::once::DispatchOnce;
 pub use self::queue::{
-    DispatchQueue, GlobalQueueIdentifier, QueueAfterError, QueueAttribute, QueuePriority,
+    DispatchQueue, DispatchQueueAttr, GlobalQueueIdentifier, QueueAfterError, QueueAttribute,
+    QueuePriority,
 };
 pub use self::retained::DispatchRetained;
 pub use self::semaphore::{DispatchSemaphore, DispatchSemaphoreGuard};
+pub use self::source::DispatchSource;
 pub use self::workloop::{DispatchAutoReleaseFrequency, DispatchWorkloop};
 
 // Helper type

crates/dispatch2/src/object.rs

@@ -62,7 +62,7 @@ pub unsafe trait DispatchObject {
     #[doc(alias = "dispatch_set_target_queue")]
     unsafe fn set_target_queue(&self, queue: &DispatchQueue) {
         // SAFETY: `object` and `queue` cannot be null, rest is upheld by caller.
-        unsafe { dispatch_set_target_queue(self.as_raw(), queue.as_raw()) };
+        unsafe { dispatch_set_target_queue(self.as_raw(), Some(queue)) };
     }
 
     /// Set the QOS class floor on a dispatch queue, source or workloop.
@@ -110,8 +110,7 @@ pub unsafe trait DispatchObject {
     }
 
     #[doc(hidden)]
-    fn as_raw(&self) -> dispatch_object_t {
-        let ptr: *const Self = self;
-        ptr as dispatch_object_t
+    fn as_raw(&self) -> NonNull<dispatch_object_s> {
+        NonNull::from(self).cast()
     }
 }