# Automatic Reference Counting [TOC] ## What is ARC? {#what-is} Objective-C memory management is based on reference counting. Historically, managing the reference count was a task given to the developer, but starting with Mac OS X 10.7/iOS 5, additional language support was added to Objective-C to allow the compiler to manage the reference counts given lifetime annotations by the developer. That feature is named “automatic reference counting” and is abbreviated to “ARC”. ARC is enabled via a flag passed to the compiler and thus for Chromium is controlled as a [config](https://source.chromium.org/search?q=config\\(%22enable_arc%22\\)&ss=chromium) for build targets. ARC is enabled by default for Chromium’s Objective-C code, with the exception of a handful of targets that opt-out. For the rest of this document, the term “Objective-C” will be used to mean both pure Objective-C as well as Objective-C++. ### What isn’t handled by ARC {#what-isnt} Be aware that ARC is only used for Objective-C objects (those objects that are a subclass of `NSObject`, declared with `@interface` or `@class`). The ownership of Core Foundation objects (with names often starting with `CF`, with names often ending with `Ref`, and declared using a `typedef` as a pointer to an undefined struct) is not handled by ARC, and `ScopedCFTypeRef<>` must be used to manage their lifetimes. For documentation on how the lifetime of Core Foundation objects works, and when you will need to use a scoper to manage it, see the [Memory Management Programming Guide for Core Foundation](https://developer.apple.com/library/archive/documentation/CoreFoundation/Conceptual/CFMemoryMgmt/CFMemoryMgmt.html#//apple_ref/doc/uid/10000127i). ## The basics of ARC {#basics} (This is necessarily a simplified explanation; reading ARC [documentation](#references) outside of this document is highly recommended.) Reference counting is a technique of managing the lifetime of objects by keeping a count of ownership references (in the conceptual sense of “references”, not in the C++ sense of `&`s). If some code wants an object to remain alive, it can “retain” the object by incrementing the reference count, and when it no longer needs the object to remain alive, it can “release” the object by decrementing the reference count. When the reference count hits zero, that indicates that no code needs the object to remain alive, so it is deallocated. Objective-C objects are accessed via pointer. The most straightforward way of thinking about ARC is that, while in classic manual reference counting, those pointers are raw pointers and the programmer is in charge of writing the appropriate retain and release messages, with ARC, all pointers to Objective-C objects are smart pointers, indicated by the following qualifications: - `__strong` (default): This pointer maintains a strong reference to the object. When an object pointer is assigned to it, that object is sent a retain message, and the object pointer that it used to contain is sent a release message (possibly causing it to be deallocated it if that caused the retain count to hit zero). - Chromium usage note: Even though this is the default, please always explicitly specify it for class members/ivars so that it is clear which pointers are Objective-C object pointers and which are C++ object pointers. - `__weak`: This pointer maintains a weak reference to the object which is kept alive by other `__strong` references. If the last of the strong references is released, and the object is deallocated, this pointer will be set to `nil`. - `__unsafe_unretained`: This is a raw pointer (as in C/C++) which has no automatic capabilities. - Chromium usage note: Do not use this, as it is almost certainly the wrong choice. The `PRESUBMIT` will complain. ARC knows about the standard Objective-C conventions for naming methods on objects that return unretained vs retained objects, and will automatically treat those functions as such. C++ functions that return retained Objective-C objects will need to be explicitly annotated as such with `NS_RETURNS_RETAINED` if in Objective-C code, or `__attribute__((ns_returns_retained))` if in a shared C++ header. Note, though, that for header files that interface with both pure C++ and Objective-C, serious thought will need to be given to that boundary with regards to retain count expectations. Because ARC handles all the reference counting, direct message sends of `-retain`, `-release`, and `-autorelease` are no longer allowed. The compiler automatically inserts them as needed, directed by the ownership annotations. Incorrect annotations will cause incorrect reference counting; annotate the code correctly to fix issues with the compiler-generated reference counting. ## ARC and C++ standard library containers {#cxx-containers} The most important interaction between ARC and C++ is that when you instantiate a template on an Objective-C type, it [implicitly qualifies](https://clang.llvm.org/docs/AutomaticReferenceCounting.html#template-arguments) the Objective-C type with `__strong`. For example, ```objectivecpp std::vector ``` is equivalent to ```objectivecpp std::vector ``` and you need to make sure that you understand the implications of taking strong references to those `NSWindow`s, even if `__strong` was not explicitly written. One might therefore want to explicitly qualify with `__weak`. While that is fine for some C++ standard library containers, like `std::vector`, one must not use `__weak` qualification in any tree or hash-based container, such as `std::map` or `std::set`. First, it's explicitly undefined behavior (UB). Containers that rely on looking up a value by either direct comparison or hash comparison rely on the values that are currently in the container not changing out underneath it. The main feature of `__weak` is that it nils itself out when there are no more strong references to it, and that behavior will break comparison-based containers. Second, at a higher “consider what it means to be a set” level, what would happen if you had a set or map where two entries that started out as different values now both nilled themselves out? That would break the invariant that there be no duplicate entries. The only C++ standard library containers in which it is safe to put `__weak` objects are those that merely move and copy them around, but perform no other processing or lookup on them. Arrays, vectors, and lists are fine; sets and maps are not. ## ARC in Chromium {#conventions} ### When to use ARC {#conventions-when} ARC is enabled by default for Objective-C code in Chromium, and all new Objective-C code in Chromium must be written to use ARC. If there is a good technical reason to not use ARC, you may disable it for a target, but this is expected to be an exceedingly rare situation and you should have a discussion with the relevant platform experts before doing so. ### Header files {#convention-headers} Header files can be: 1. _Shared between C++ and Objective-C._ For these headers, avoid having any Objective-C object pointers in them. Use the techniques in the [Mixing C++ and Objective-C](mixing_cpp_and_objc.md) document to accomplish this. 2. _Only included in Objective-C implementation files compiled with ARC._ Because ARC is the default compilation mode, this will be common. For these headers, qualify the ownership of Objective-C object pointers with `__strong` and `__weak`. 3. _Included in Objective-C implementation files compiled with a mix of ARC and non-ARC._ Because ARC is the default compilation mode, this situation should be rare. For this situation, treat the non-ARC compiled files as if they were C++ and use the techniques from point 1. ## Warning! Dangers! {#dangers} There are some bits of AppKit that are incompatible with ARC. Apple has not updated the documentation to call this out, so a heads-up: When creating an `NSWindow`, you _must_ set the `.releasedWhenClosed` property to `NO`. It’s recommended that you do so immediately after creating it with `alloc`/`init`. If you fail to do so, then closing the window will cause it to release itself, and then when the owning pointer releases it, it will be a double-release. ## Examples of ARC code {#examples} ### Objective-C Classes {#examples-objc-classes} ```objectivec @interface KittyARC : NSObject @property(nonatomic, weak) id delegate; @property(nonatomic, copy) NSArray* childCats; @property(nonatomic, strong) NSURL* vetURL; - (Meow*)meowForBellyRub:(BellyRub*)rub; @end @implementation KittyARC { id __weak _catFactory; NSURL* _lastVisitedCatURL; } @synthesize delegate = _delegate; @synthesize childCats = _childCats; @synthesize vetURL = _vetURL; - (Meow*)meowForBellyRub:(BellyRub*)rub { return [[MeowImpl alloc] initWithBellyRub:rub]; } @end ``` ### C++ classes in Objective-C++ files {#examples-cpp-classes} ```objectivec class Banana : public Fruit { Animal* __strong pet_; Phone* __weak nexus_; Vehicle* __weak car_; // Do not use __unsafe_unretained. } ``` ### Blocks {#examples-blocks} Note: Blocks retain all objects referenced in them. This example is of a block used in an Objective-C method that uses the “weak `self`” idiom to avoid a retain cycle. For blocks used in C++ functions, a retain cycle is not a concern, though the use of a `base::WeakPtr<>` might be needed to avoid stale pointers. ```objectivec typeof(self) __weak weakSelf = self; [performer_ showAuthenticationError:error withCompletion:^{ typeof(self) strongSelf = weakSelf; if (!strongSelf) { return; } [strongSelf setHandlingError:NO]; [strongSelf continueSignin]; }]; ``` ### GN file changes {#examples-gn} All targets compile with ARC as default. For targets that must not compile with ARC, ARC can be disabled as follows: ```gn # Do not compile with ARC because AncientDeps code is not compatible with # being compiled with ARC. configs -= [ "//build/config/compiler:enable_arc" ] ``` Again, ARC must be used for all new code unless there is a good technical reason that the new code cannot use ARC. Please consult with platform experts if you believe that you are in this situation. ## Things that should not be used from ARC code {#changes} There are utility functions and classes that were introduced when Chromium did not compile with ARC, but that are no longer needed with ARC code. Because there are still parts of Chromium that cannot be compiled with ARC, these utilities remain, however they should not (or sometimes cannot) be used from ARC: - `scoped_nsobject<>`/`scoped_nsprotocol<>`: These only exists to handle scoping of Objective-C objects in non-ARC code. They cannot be used in ARC code; use `__strong` instead. - `ScopedNSAutoreleasePool`: Use `@autoreleasepool` instead, and remove any use of `ScopedNSAutoreleasePool` that you encounter, if possible. `ScopedNSAutoreleasePool` was rewritten to be able to work in ARC code, but the C++ class-based nature of `ScopedNSAutoreleasePool` is fundamentally incompatible with the stack-based nature of autorelease pools, and thus it is in the process of [being removed](https://crbug.com/772489). ## Further reading {#references} - Apple documentation about memory management and how both manual reference counting and ARC work: [About Memory Management](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/MemoryMgmt/Articles/MemoryMgmt.html) - Apple documentation from when ARC was new; it’s marked as “outdated” but is still a good read: [Transitioning to ARC Release Notes](https://developer.apple.com/library/archive/releasenotes/ObjectiveC/RN-TransitioningToARC/Introduction/Introduction.html) - Wikipedia overview: [Automatic Reference Counting](https://en.wikipedia.org/wiki/Automatic_Reference_Counting) - Clang documentation (very technical): [Objective-C Automatic Reference Counting (ARC)](https://clang.llvm.org/docs/AutomaticReferenceCounting.html) - There’s a specialized tool named [`NS_VALID_UNTIL_END_OF_SCOPE` (the preferred spelling and available in `.mm` files that use Foundation) a.k.a. `objc_precise_lifetime` (for use otherwise)](https://clang.llvm.org/docs/AutomaticReferenceCounting.html#precise-lifetime-semantics) that might be useful in specific situations where the compiler cannot fully deduce what lifetime is needed for a local variable. It’s not usually needed, but if you have gotten to this point in this document, you should know it exists in case you find yourself in just that situation. ## Documents from Chromium iOS’s ARC transition {#old-docs} Several years ago, Chromium for iOS transitioned to ARC. In the process of doing so, they produced the documents (Google-internal): - [ARC transition](https://goto.google.com/chrome-arc) - [[ARC] How to convert a target](https://goto.google.com/arc-howto) - [ARC FAQ](https://goto.google.com/faq-arc) They described the ARC process as they intended to do it, not necessarily as it ended up being done. All relevant information from them has been moved to this document. However, they can be useful reading for historical context.