objc_sys/
rc.rs

1//! ARC functions.
2//!
3//! These are documented in Clang's [documentation][ARC], and available since
4//! macOS `10.7` unless otherwise noted, so they are safe to rely on.
5//!
6//! Defined in:
7//! - Apple: `objc-internal.h`
8//! - GNUStep: `objc-arc.h`
9//! - ObjFW: `runtime/arc.m`
10//!
11//! [ARC]: https://clang.llvm.org/docs/AutomaticReferenceCounting.html#runtime-support
12use core::ffi::c_void;
13
14#[cfg(any(
15    doc,
16    all(
17        target_vendor = "apple",
18        not(all(target_os = "macos", target_arch = "x86"))
19    )
20))]
21use crate::objc_class;
22use crate::objc_object;
23
24// All of these very rarely unwind, but may if the user defined methods
25// `retain`, `release`, `autorelease` or `dealloc` do.
26extern_c_unwind! {
27    // Autoreleasepool
28    // ObjFW: Defined in `autorelease.h`, not available with libobjfw-rt!
29
30    #[cfg(any(doc, not(feature = "unstable-objfw")))]
31    pub fn objc_autoreleasePoolPop(pool: *mut c_void);
32    #[cfg(any(doc, not(feature = "unstable-objfw")))]
33    pub fn objc_autoreleasePoolPush() -> *mut c_void;
34
35    // Autorelease
36
37    pub fn objc_autorelease(value: *mut objc_object) -> *mut objc_object;
38    pub fn objc_autoreleaseReturnValue(value: *mut objc_object) -> *mut objc_object;
39
40    // Weak pointers
41
42    pub fn objc_copyWeak(to: *mut *mut objc_object, from: *mut *mut objc_object);
43    pub fn objc_destroyWeak(addr: *mut *mut objc_object);
44    pub fn objc_initWeak(addr: *mut *mut objc_object, value: *mut objc_object) -> *mut objc_object;
45    // Defined in runtime.h
46    pub fn objc_loadWeak(addr: *mut *mut objc_object) -> *mut objc_object;
47    pub fn objc_loadWeakRetained(addr: *mut *mut objc_object) -> *mut objc_object;
48    pub fn objc_moveWeak(to: *mut *mut objc_object, from: *mut *mut objc_object);
49
50    // Retain / release
51
52    pub fn objc_release(value: *mut objc_object);
53    pub fn objc_retain(value: *mut objc_object) -> *mut objc_object;
54    pub fn objc_retainAutorelease(value: *mut objc_object) -> *mut objc_object;
55    pub fn objc_retainAutoreleaseReturnValue(value: *mut objc_object) -> *mut objc_object;
56    pub fn objc_retainAutoreleasedReturnValue(value: *mut objc_object) -> *mut objc_object;
57    // Defined in objc-abi.h
58    pub fn objc_retainBlock(value: *mut objc_object) -> *mut objc_object;
59
60    // Storing values
61
62    pub fn objc_storeStrong(addr: *mut *mut objc_object, value: *mut objc_object);
63    // Defined in runtime.h
64    pub fn objc_storeWeak(addr: *mut *mut objc_object, value: *mut objc_object)
65        -> *mut objc_object;
66
67    // TODO: Decide about nonstandard extensions like these:
68    // #[cfg(any(doc, feature = "gnustep-1-7"))]
69    // pub fn objc_delete_weak_refs(obj: *mut objc_object) -> BOOL;
70
71    // Fast paths for certain selectors.
72    //
73    // These are not defined in the ARC documentation, but are emitted by
74    // `clang` and included (and intended to be included) in the final
75    // binary, so very likely safe to use.
76    //
77    // TODO: Unsure why these are not available in the old fragile runtime,
78    // the headers seem to indicate that they are.
79    //
80    // <https://github.com/llvm/llvm-project/blob/llvmorg-17.0.5/clang/include/clang/Basic/ObjCRuntime.h#L229>
81
82    // Available since macOS 10.9.
83    #[cfg(any(doc, all(target_vendor = "apple", not(all(target_os = "macos", target_arch = "x86")))))]
84    pub fn objc_alloc(value: *const objc_class) -> *mut objc_object;
85
86    // Available since macOS 10.9.
87    #[cfg(any(doc, all(target_vendor = "apple", not(all(target_os = "macos", target_arch = "x86")))))]
88    pub fn objc_allocWithZone(value: *const objc_class) -> *mut objc_object;
89
90    // TODO: objc_alloc_init once supported
91}
objc_sys/rc.rs

objc_sys/
rc.rs
