objc2/rc/mod.rs
1//! # Reference counting utilities.
2//!
3//! The types in this module provide roughly the same benefits as ARC
4//! (Automatic Reference Counting) does to Objective-C.
5//!
6//! Most importantly, a smart pointer [`Retained`] is provided to ensure that
7//! objects are correctly retained and released when created and dropped,
8//! respectively.
9//!
10//! Weak references may be created using the [`Weak`] struct; these will not
11//! retain the object, but one can attempt to load them and obtain an `Retained`, or
12//! safely fail if the object has been deallocated.
13//!
14//! See [the clang documentation][clang-arc] and [the Apple article on memory
15//! management][mem-mgmt] (similar document exists [for Core Foundation][cf])
16//! for more information on automatic and manual reference counting.
17//!
18//! It can also be useful to [enable Malloc Debugging][mem-debug] if you're trying
19//! to figure out if/where your application has memory errors and leaks.
20//!
21//! [clang-arc]: https://clang.llvm.org/docs/AutomaticReferenceCounting.html
22//! [mem-mgmt]: https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/MemoryMgmt/Articles/MemoryMgmt.html
23//! [cf]: https://developer.apple.com/library/archive/documentation/CoreFoundation/Conceptual/CFMemoryMgmt/CFMemoryMgmt.html
24//! [mem-debug]: https://developer.apple.com/library/archive/documentation/Performance/Conceptual/ManagingMemory/Articles/MallocDebug.html
25//!
26//!
27//! ## Example
28//!
29//! ```
30//! use objc2::rc::{autoreleasepool, Retained, Weak};
31//! use objc2::runtime::NSObject;
32//!
33//! // Allocate and initialize a new `NSObject`.
34//! // `Retained` will release the object when dropped.
35//! let obj: Retained<NSObject> = NSObject::new();
36//!
37//! // Cloning retains the object an additional time
38//! let cloned = obj.clone();
39//! autoreleasepool(|pool| {
40//! // Autorelease consumes the Retained, but won't actually
41//! // release it until the end of the autoreleasepool
42//! // SAFETY: The given is the innermost pool.
43//! let obj_ref: &NSObject = unsafe { Retained::autorelease(cloned, pool) };
44//! });
45//!
46//! // Weak references won't retain the object
47//! let weak = Weak::from_retained(&obj);
48//! drop(obj);
49//! assert!(weak.load().is_none());
50//! ```
51
52mod allocated_partial_init;
53mod autorelease;
54mod retained;
55mod retained_forwarding_impls;
56mod retained_traits;
57#[cfg(test)]
58mod test_object;
59mod weak;
60
61pub use self::allocated_partial_init::{Allocated, PartialInit};
62pub use self::autorelease::{
63 autoreleasepool, autoreleasepool_leaking, AutoreleasePool, AutoreleaseSafe,
64};
65// Re-export `Id` for backwards compatibility, but still mark it as deprecated.
66#[allow(deprecated)]
67pub use self::retained::Id;
68pub use self::retained::Retained;
69pub use self::retained_traits::{DefaultRetained, RetainedFromIterator, RetainedIntoIterator};
70#[cfg(test)]
71pub(crate) use self::test_object::{RcTestObject, ThreadTestData};
72pub use self::weak::Weak;
73// Same as above.
74#[allow(deprecated)]
75pub use self::weak::WeakId;