Purpose¶

The first and primary purpose of this document is to serve as a complete technical specification of Automatic Reference Counting. Given a core Objective-C compiler and runtime, it should be possible to write a compiler and runtime which implements these new semantics.

The secondary purpose is to act as a rationale for why ARC was designed in this way. This should remain tightly focused on the technical design and should not stray into marketing speculation.

Background¶

This document assumes a basic familiarity with C.

Blocks are a C language extension for creating anonymous functions. Users interact with and transfer block objects using block pointers, which are represented like a normal pointer. A block may capture values from local variables; when this occurs, memory must be dynamically allocated. The initial allocation is done on the stack, but the runtime provides a Block_copy function which, given a block pointer, either copies the underlying block object to the heap, setting its reference count to 1 and returning the new block pointer, or (if the block object is already on the heap) increases its reference count by 1. The paired function is Block_release, which decreases the reference count by 1 and destroys the object if the count reaches zero and is on the heap.

Objective-C is a set of language extensions, significant enough to be considered a different language. It is a strict superset of C. The extensions can also be imposed on C++, producing a language called Objective-C++. The primary feature is a single-inheritance object system; we briefly describe the modern dialect.

Objective-C defines a new type kind, collectively called the object pointer types. This kind has two notable builtin members, id and Class; id is the final supertype of all object pointers. The validity of conversions between object pointer types is not checked at runtime. Users may define classes; each class is a type, and the pointer to that type is an object pointer type. A class may have a superclass; its pointer type is a subtype of its superclass’s pointer type. A class has a set of ivars, fields which appear on all instances of that class. For every class T there’s an associated metaclass; it has no fields, its superclass is the metaclass of T’s superclass, and its metaclass is a global class. Every class has a global object whose class is the class’s metaclass; metaclasses have no associated type, so pointers to this object have type Class.

A class declaration (@interface) declares a set of methods. A method has a return type, a list of argument types, and a selector: a name like foo:bar:baz:, where the number of colons corresponds to the number of formal arguments. A method may be an instance method, in which case it can be invoked on objects of the class, or a class method, in which case it can be invoked on objects of the metaclass. A method may be invoked by providing an object (called the receiver) and a list of formal arguments interspersed with the selector, like so:

[receiver foo: fooArg bar: barArg baz: bazArg]

This looks in the dynamic class of the receiver for a method with this name, then in that class’s superclass, etc., until it finds something it can execute. The receiver “expression” may also be the name of a class, in which case the actual receiver is the class object for that class, or (within method definitions) it may be super, in which case the lookup algorithm starts with the static superclass instead of the dynamic class. The actual methods dynamically found in a class are not those declared in the @interface, but those defined in a separate @implementation declaration; however, when compiling a call, typechecking is done based on the methods declared in the @interface.

Method declarations may also be grouped into protocols, which are not inherently associated with any class, but which classes may claim to follow. Object pointer types may be qualified with additional protocols that the object is known to support.

Class extensions are collections of ivars and methods, designed to allow a class’s @interface to be split across multiple files; however, there is still a primary implementation file which must see the @interfaces of all class extensions. Categories allow methods (but not ivars) to be declared post hoc on an arbitrary class; the methods in the category’s @implementation will be dynamically added to that class’s method tables which the category is loaded at runtime, replacing those methods in case of a collision.

In the standard environment, objects are allocated on the heap, and their lifetime is manually managed using a reference count. This is done using two instance methods which all classes are expected to implement: retain increases the object’s reference count by 1, whereas release decreases it by 1 and calls the instance method dealloc if the count reaches 0. To simplify certain operations, there is also an autorelease pool, a thread-local list of objects to call release on later; an object can be added to this pool by calling autorelease on it.

Block pointers may be converted to type id; block objects are laid out in a way that makes them compatible with Objective-C objects. There is a builtin class that all block objects are considered to be objects of; this class implements retain by adjusting the reference count, not by calling Block_copy.

Evolution¶

ARC is under continual evolution, and this document must be updated as the language progresses.

If a change increases the expressiveness of the language, for example by lifting a restriction or by adding new syntax, the change will be annotated with a revision marker, like so:

ARC applies to Objective-C pointer types, block pointer types, and [beginning Apple 8.0, LLVM 3.8] BPTRs declared within extern "BCPL" blocks.

For now, it is sensible to version this document by the releases of its sole implementation (and its host project), clang. “LLVM X.Y” refers to an open-source release of clang from the LLVM project. “Apple X.Y” refers to an Apple-provided release of the Apple LLVM Compiler. Other organizations that prepare their own, separately-versioned clang releases and wish to maintain similar information in this document should send requests to cfe-dev.

If a change decreases the expressiveness of the language, for example by imposing a new restriction, this should be taken as an oversight in the original specification and something to be avoided in all versions. Such changes are generally to be avoided.

Retain count semantics¶

A retainable object pointer is either a null pointer or a pointer to a valid object. Furthermore, if it has block pointer type and is not null then it must actually be a pointer to a block object, and if it has Class type (possibly protocol-qualified) then it must actually be a pointer to a class object. Otherwise ARC does not enforce the Objective-C type system as long as the implementing methods follow the signature of the static type. It is undefined behavior if ARC is exposed to an invalid pointer.

For ARC’s purposes, a valid object is one with “well-behaved” retaining operations. Specifically, the object must be laid out such that the Objective-C message send machinery can successfully send it the following messages:

• retain, taking no arguments and returning a pointer to the object.
• release, taking no arguments and returning void.
• autorelease, taking no arguments and returning a pointer to the object.

The behavior of these methods is constrained in the following ways. The term high-level semantics is an intentionally vague term; the intent is that programmers must implement these methods in a way such that the compiler, modifying code in ways it deems safe according to these constraints, will not violate their requirements. For example, if the user puts logging statements in retain, they should not be surprised if those statements are executed more or less often depending on optimization settings. These constraints are not exhaustive of the optimization opportunities: values held in local variables are subject to additional restrictions, described later in this document.

It is undefined behavior if a computation history featuring a send of retain followed by a send of release to the same object, with no intervening release on that object, is not equivalent under the high-level semantics to a computation history in which these sends are removed. Note that this implies that these methods may not raise exceptions.

It is undefined behavior if a computation history features any use whatsoever of an object following the completion of a send of release that is not preceded by a send of retain to the same object.

The behavior of autorelease must be equivalent to sending release when one of the autorelease pools currently in scope is popped. It may not throw an exception.

When the semantics call for performing one of these operations on a retainable object pointer, if that pointer is null then the effect is a no-op.

All of the semantics described in this document are subject to additional optimization rules which permit the removal or optimization of operations based on local knowledge of data flow. The semantics describe the high-level behaviors that the compiler implements, not an exact sequence of operations that a program will be compiled into.

Retainable object pointers as operands and arguments¶

In general, ARC does not perform retain or release operations when simply using a retainable object pointer as an operand within an expression. This includes:

• loading a retainable pointer from an object with non-weak ownership,
• passing a retainable pointer as an argument to a function or method, and
• receiving a retainable pointer as the result of a function or method call.

The remainder of this section describes exceptions to these rules, how those exceptions are detected, and what those exceptions imply semantically.

void foo(__attribute((ns_consumed)) id x);
- (void) foo: (id) __attribute((ns_consumed)) x;

id foo(void) __attribute((ns_returns_retained));
- (id) foo __attribute((ns_returns_retained));

Restrictions¶

Spelling¶

The names of the ownership qualifiers are reserved for the implementation. A program may not assume that they are or are not implemented with macros, or what those macros expand to.

An ownership qualifier may be written anywhere that any other type qualifier may be written.

If an ownership qualifier appears in the declaration-specifiers, the following rules apply:

• if the type specifier is a retainable object owner type, the qualifier initially applies to that type;
• otherwise, if the outermost non-array declarator is a pointer or block pointer declarator, the qualifier initially applies to that type;
• otherwise the program is ill-formed.
• If the qualifier is so applied at a position in the declaration where the next-innermost declarator is a function declarator, and there is an block declarator within that function declarator, then the qualifier applies instead to that block declarator and this rule is considered afresh beginning from the new position.

If an ownership qualifier appears on the declarator name, or on the declared object, it is applied to the innermost pointer or block-pointer type.

If an ownership qualifier appears anywhere else in a declarator, it applies to the type there.

Semantics¶

There are five managed operations which may be performed on an object of retainable object pointer type. Each qualifier specifies different semantics for each of these operations. It is still undefined behavior to access an object outside of its lifetime.

A load or store with “primitive semantics” has the same semantics as the respective operation would have on an void* lvalue with the same alignment and non-ownership qualification.

Reading occurs when performing a lvalue-to-rvalue conversion on an object lvalue.

• For __weak objects, the current pointee is retained and then released at the end of the current full-expression. This must execute atomically with respect to assignments and to the final release of the pointee.
• For all other objects, the lvalue is loaded with primitive semantics.

Assignment occurs when evaluating an assignment operator. The semantics vary based on the qualification:

• For __strong objects, the new pointee is first retained; second, the lvalue is loaded with primitive semantics; third, the new pointee is stored into the lvalue with primitive semantics; and finally, the old pointee is released. This is not performed atomically; external synchronization must be used to make this safe in the face of concurrent loads and stores.
• For __weak objects, the lvalue is updated to point to the new pointee, unless the new pointee is an object currently undergoing deallocation, in which case the lvalue is updated to a null pointer. This must execute atomically with respect to other assignments to the object, to reads from the object, and to the final release of the new pointee.
• For __unsafe_unretained objects, the new pointee is stored into the lvalue using primitive semantics.
• For __autoreleasing objects, the new pointee is retained, autoreleased, and stored into the lvalue using primitive semantics.

Initialization occurs when an object’s lifetime begins, which depends on its storage duration. Initialization proceeds in two stages:

1. First, a null pointer is stored into the lvalue using primitive semantics. This step is skipped if the object is __unsafe_unretained.
2. Second, if the object has an initializer, that expression is evaluated and then assigned into the object using the usual assignment semantics.

Destruction occurs when an object’s lifetime ends. In all cases it is semantically equivalent to assigning a null pointer to the object, with the proviso that of course the object cannot be legally read after the object’s lifetime ends.

Moving occurs in specific situations where an lvalue is “moved from”, meaning that its current pointee will be used but the object may be left in a different (but still valid) state. This arises with __block variables and rvalue references in C++. For __strong lvalues, moving is equivalent to loading the lvalue with primitive semantics, writing a null pointer to it with primitive semantics, and then releasing the result of the load at the end of the current full-expression. For all other lvalues, moving is equivalent to reading the object.

Restrictions¶

Ownership inference¶

Explicit method family control¶

A method may be annotated with the objc_method_family attribute to precisely control which method family it belongs to. If a method in an @implementation does not have this attribute, but there is a method declared in the corresponding @interface that does, then the attribute is copied to the declaration in the @implementation. The attribute is available outside of ARC, and may be tested for with the preprocessor query __has_attribute(objc_method_family).

The attribute is spelled __attribute__((objc_method_family( family ))). If family is none, the method has no family, even if it would otherwise be considered to have one based on its selector and type. Otherwise, family must be one of alloc, copy, init, mutableCopy, or new, in which case the method is considered to belong to the corresponding family regardless of its selector. It is an error if a method that is explicitly added to a family in this way does not meet the requirements of the family other than the selector naming convention.

Semantics of method families¶

A method’s membership in a method family may imply non-standard semantics for its parameters and return type.

Methods in the alloc, copy, mutableCopy, and new families — that is, methods in all the currently-defined families except init — implicitly return a retained object as if they were annotated with the ns_returns_retained attribute. This can be overridden by annotating the method with either of the ns_returns_autoreleased or ns_returns_not_retained attributes.

Properties also follow same naming rules as methods. This means that those in the alloc, copy, mutableCopy, and new families provide access to retained objects. This can be overridden by annotating the property with ns_returns_not_retained attribute.

Object liveness¶

ARC may not allow a retainable object X to be deallocated at a time T in a computation history if:

• X is the value stored in a __strong object S with precise lifetime semantics, or
• X is the value stored in a __strong object S with imprecise lifetime semantics and, at some point after T but before the next store to S, the computation history features a load from S and in some way depends on the value loaded, or
• X is a value described as being released at the end of the current full-expression and, at some point after T but before the end of the full-expression, the computation history depends on that value.

A computation history depends on a pointer value P if it:

• performs a pointer comparison with P,
• loads from P,
• stores to P,
• depends on a pointer value Q derived via pointer arithmetic from P (including an instance-variable or field access), or
• depends on a pointer value Q loaded from P.

Dependency applies only to values derived directly or indirectly from a particular expression result and does not occur merely because a separate pointer value dynamically aliases P. Furthermore, this dependency is not carried by values that are stored to objects.

No object lifetime extension¶

If, in the formal computation history of the program, an object X has been deallocated by the time of an observable side-effect, then ARC must cause X to be deallocated by no later than the occurrence of that side-effect, except as influenced by the re-ordering of the destruction of objects.

Precise lifetime semantics¶

In general, ARC maintains an invariant that a retainable object pointer held in a __strong object will be retained for the full formal lifetime of the object. Objects subject to this invariant have precise lifetime semantics.

By default, local variables of automatic storage duration do not have precise lifetime semantics. Such objects are simply strong references which hold values of retainable object pointer type, and these values are still fully subject to the optimizations on values under local control.

A local variable of retainable object owner type and automatic storage duration may be annotated with the objc_precise_lifetime attribute to indicate that it should be considered to be an object with precise lifetime semantics.

Special methods¶

@autoreleasepool¶

To simplify the use of autorelease pools, and to bring them under the control of the compiler, a new kind of statement is available in Objective-C. It is written @autoreleasepool followed by a compound-statement, i.e. by a new scope delimited by curly braces. Upon entry to this block, the current state of the autorelease pool is captured. When the block is exited normally, whether by fallthrough or directed control flow (such as return or break), the autorelease pool is restored to the saved state, releasing all the objects in it. When the block is exited with an exception, the pool is not drained.

@autoreleasepool may be used in non-ARC translation units, with equivalent semantics.

A program is ill-formed if it refers to the NSAutoreleasePool class.

Externally-Retained Variables¶

In some situations, variables with strong ownership are considered externally-retained by the implementation. This means that the variable is retained elsewhere, and therefore the implementation can elide retaining and releasing its value. Such a variable is implicitly const for safety. In contrast with __unsafe_unretained, an externally-retained variable still behaves as a strong variable outside of initialization and destruction. For instance, when an externally-retained variable is captured in a block the value of the variable is retained and released on block capture and destruction. It also affects C++ features such as lambda capture, decltype, and template argument deduction.

Implicitly, the implementation assumes that the self parameter in a non-init method and the variable in a for-in loop are externally-retained.

Externally-retained semantics can also be opted into with the objc_externally_retained attribute. This attribute can apply to strong local variables, functions, methods, or blocks:

@class WobbleAmount;

@interface Widget : NSObject
-(void)wobble:(WobbleAmount *)amount;
@end

@implementation Widget

-(void)wobble:(WobbleAmount *)amount
         __attribute__((objc_externally_retained)) {
  // 'amount' and 'alias' aren't retained on entry, nor released on exit.
  __attribute__((objc_externally_retained)) WobbleAmount *alias = amount;
}
@end

Annotating a function with this attribute makes every parameter with strong retainable object pointer type externally-retained, unless the variable was explicitly qualified with __strong. For instance, first_param is externally-retained (and therefore const) below, but not second_param:

__attribute__((objc_externally_retained))
void f(NSArray *first_param, __strong NSArray *second_param) {
  // ...
}

You can test if your compiler has support for objc_externally_retained with __has_attribute:

#if __has_attribute(objc_externally_retained)
// Use externally retained...
#endif

self¶

The self parameter variable of an non-init Objective-C method is considered externally-retained by the implementation. It is undefined behavior, or at least dangerous, to cause an object to be deallocated during a message send to that object. In an init method, self follows the :ref:init family rules <arc.family.semantics.init>.

Fast enumeration iteration variables¶

If a variable is declared in the condition of an Objective-C fast enumeration loop, and the variable has no explicit ownership qualifier, then it is implicitly externally-retained so that objects encountered during the enumeration are not actually retained and released.

Blocks¶

The implicit const capture variables created when evaluating a block literal expression have the same ownership semantics as the local variables they capture. The capture is performed by reading from the captured variable and initializing the capture variable with that value; the capture variable is destroyed when the block literal is, i.e. at the end of the enclosing scope.

The inference rules apply equally to __block variables, which is a shift in semantics from non-ARC, where __block variables did not implicitly retain during capture.

__block variables of retainable object owner type are moved off the stack by initializing the heap copy with the result of moving from the stack copy.

With the exception of retains done as part of initializing a __strong parameter variable or reading a __weak variable, whenever these semantics call for retaining a value of block-pointer type, it has the effect of a Block_copy. The optimizer may remove such copies when it sees that the result is used only as an argument to a call.

Exceptions¶

By default in Objective C, ARC is not exception-safe for normal releases:

• It does not end the lifetime of __strong variables when their scopes are abnormally terminated by an exception.
• It does not perform releases which would occur at the end of a full-expression if that full-expression throws an exception.

A program may be compiled with the option -fobjc-arc-exceptions in order to enable these, or with the option -fno-objc-arc-exceptions to explicitly disable them, with the last such argument “winning”.

In Objective-C++, -fobjc-arc-exceptions is enabled by default.

ARC does end the lifetimes of __weak objects when an exception terminates their scope unless exceptions are disabled in the compiler.

Interior pointers¶

An Objective-C method returning a non-retainable pointer may be annotated with the objc_returns_inner_pointer attribute to indicate that it returns a handle to the internal data of an object, and that this reference will be invalidated if the object is destroyed. When such a message is sent to an object, the object’s lifetime will be extended until at least the earliest of:

• the last use of the returned pointer, or any pointer derived from it, in the calling function or
• the autorelease pool is restored to a previous state.

As an exception, no extension is required if the receiver is loaded directly from a __strong object with precise lifetime semantics.

C retainable pointer types¶

A type is a C retainable pointer type if it is a pointer to (possibly qualified) void or a pointer to a (possibly qualifier) struct or class type.

#pragma clang arc_cf_code_audited begin
...
#pragma clang arc_cf_code_audited end

id objc_autorelease(id value);¶

Precondition: value is null or a pointer to a valid object.

If value is null, this call has no effect. Otherwise, it adds the object to the innermost autorelease pool exactly as if the object had been sent the autorelease message.

Always returns value.

void objc_autoreleasePoolPop(void *pool);¶

Precondition: pool is the result of a previous call to objc_autoreleasePoolPush on the current thread, where neither pool nor any enclosing pool have previously been popped.

Releases all the objects added to the given autorelease pool and any autorelease pools it encloses, then sets the current autorelease pool to the pool directly enclosing pool.

void *objc_autoreleasePoolPush(void);¶

Creates a new autorelease pool that is enclosed by the current pool, makes that the current pool, and returns an opaque “handle” to it.

id objc_autoreleaseReturnValue(id value);¶

Precondition: value is null or a pointer to a valid object.

If value is null, this call has no effect. Otherwise, it makes a best effort to hand off ownership of a retain count on the object to a call to objc_retainAutoreleasedReturnValue for the same object in an enclosing call frame. If this is not possible, the object is autoreleased as above.

Always returns value.

void objc_copyWeak(id *dest, id *src);¶

Precondition: src is a valid pointer which either contains a null pointer or has been registered as a __weak object. dest is a valid pointer which has not been registered as a __weak object.

dest is initialized to be equivalent to src, potentially registering it with the runtime. Equivalent to the following code:

void objc_copyWeak(id *dest, id *src) {
  objc_release(objc_initWeak(dest, objc_loadWeakRetained(src)));
}

Must be atomic with respect to calls to objc_storeWeak on src.

void objc_destroyWeak(id *object);¶

Precondition: object is a valid pointer which either contains a null pointer or has been registered as a __weak object.

object is unregistered as a weak object, if it ever was. The current value of object is left unspecified; otherwise, equivalent to the following code:

void objc_destroyWeak(id *object) {
  objc_storeWeak(object, nil);
}

Does not need to be atomic with respect to calls to objc_storeWeak on object.

id objc_initWeak(id *object, id value);¶

Precondition: object is a valid pointer which has not been registered as a __weak object. value is null or a pointer to a valid object.

If value is a null pointer or the object to which it points has begun deallocation, object is zero-initialized. Otherwise, object is registered as a __weak object pointing to value. Equivalent to the following code:

id objc_initWeak(id *object, id value) {
  *object = nil;
  return objc_storeWeak(object, value);
}

Returns the value of object after the call.

Does not need to be atomic with respect to calls to objc_storeWeak on object.

id objc_loadWeak(id *object);¶

Precondition: object is a valid pointer which either contains a null pointer or has been registered as a __weak object.

If object is registered as a __weak object, and the last value stored into object has not yet been deallocated or begun deallocation, retains and autoreleases that value and returns it. Otherwise returns null. Equivalent to the following code:

id objc_loadWeak(id *object) {
  return objc_autorelease(objc_loadWeakRetained(object));
}

Must be atomic with respect to calls to objc_storeWeak on object.

id objc_loadWeakRetained(id *object);¶

Precondition: object is a valid pointer which either contains a null pointer or has been registered as a __weak object.

If object is registered as a __weak object, and the last value stored into object has not yet been deallocated or begun deallocation, retains that value and returns it. Otherwise returns null.

Must be atomic with respect to calls to objc_storeWeak on object.

void objc_moveWeak(id *dest, id *src);¶

Precondition: src is a valid pointer which either contains a null pointer or has been registered as a __weak object. dest is a valid pointer which has not been registered as a __weak object.

dest is initialized to be equivalent to src, potentially registering it with the runtime. src may then be left in its original state, in which case this call is equivalent to objc_copyWeak, or it may be left as null.

Must be atomic with respect to calls to objc_storeWeak on src.

void objc_release(id value);¶

Precondition: value is null or a pointer to a valid object.

If value is null, this call has no effect. Otherwise, it performs a release operation exactly as if the object had been sent the release message.

id objc_retain(id value);¶

Precondition: value is null or a pointer to a valid object.

If value is null, this call has no effect. Otherwise, it performs a retain operation exactly as if the object had been sent the retain message.

Always returns value.

id objc_retainAutorelease(id value);¶

Precondition: value is null or a pointer to a valid object.

If value is null, this call has no effect. Otherwise, it performs a retain operation followed by an autorelease operation. Equivalent to the following code:

id objc_retainAutorelease(id value) {
  return objc_autorelease(objc_retain(value));
}

Always returns value.

id objc_retainAutoreleaseReturnValue(id value);¶

Precondition: value is null or a pointer to a valid object.

If value is null, this call has no effect. Otherwise, it performs a retain operation followed by the operation described in objc_autoreleaseReturnValue. Equivalent to the following code:

id objc_retainAutoreleaseReturnValue(id value) {
  return objc_autoreleaseReturnValue(objc_retain(value));
}

Always returns value.

id objc_retainAutoreleasedReturnValue(id value);¶

Precondition: value is null or a pointer to a valid object.

If value is null, this call has no effect. Otherwise, it attempts to accept a hand off of a retain count from a call to objc_autoreleaseReturnValue on value in a recently-called function or something it calls. If that fails, it performs a retain operation exactly like objc_retain.

Always returns value.

id objc_retainBlock(id value);¶

Precondition: value is null or a pointer to a valid block object.

If value is null, this call has no effect. Otherwise, if the block pointed to by value is still on the stack, it is copied to the heap and the address of the copy is returned. Otherwise a retain operation is performed on the block exactly as if it had been sent the retain message.

void objc_storeStrong(id *object, id value);¶

Precondition: object is a valid pointer to a __strong object which is adequately aligned for a pointer. value is null or a pointer to a valid object.

Performs the complete sequence for assigning to a __strong object of non-block type [*]. Equivalent to the following code:

void objc_storeStrong(id *object, id value) {
  id oldValue = *object;
  value = [value retain];
  *object = value;
  [oldValue release];
}

id objc_storeWeak(id *object, id value);¶

Precondition: object is a valid pointer which either contains a null pointer or has been registered as a __weak object. value is null or a pointer to a valid object.

If value is a null pointer or the object to which it points has begun deallocation, object is assigned null and unregistered as a __weak object. Otherwise, object is registered as a __weak object or has its registration updated to point to value.

Returns the value of object after the call.