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.

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.

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.

Automatic Reference Counting implements automatic memory management for Objective-C objects and blocks, freeing the programmer from the need to explicitly insert retains and releases. It does not provide a cycle collector; users must explicitly manage the lifetime of their objects, breaking cycles manually or with weak or unsafe references.

ARC may be explicitly enabled with the compiler flag -fobjc-arc. It may also be explicitly disabled with the compiler flag -fno-objc-arc. The last of these two flags appearing on the compile line "wins".

If ARC is enabled, __has_feature(objc_arc) will expand to 1 in the preprocessor. For more information about __has_feature, see the :ref:`language extensions <langext-__has_feature-__has_extension>` document.

This section describes retainable object pointers, their basic operations, and the restrictions imposed on their use under ARC. Note in particular that it covers the rules for pointer values (patterns of bits indicating the location of a pointed-to object), not pointer objects (locations in memory which store pointer values). The rules for objects are covered in the next section.

A retainable object pointer (or "retainable pointer") is a value of a retainable object pointer type ("retainable type"). There are three kinds of retainable object pointer types:

• block pointers (formed by applying the caret (^) declarator sigil to a function type)
• Objective-C object pointers (id, Class, NSFoo*, etc.)
• typedefs marked with __attribute__((NSObject))

Other pointer types, such as int* and CFStringRef, are not subject to ARC's semantics and restrictions.

The use of __attribute__((NSObject)) typedefs is not recommended. If it's absolutely necessary to use this attribute, be very explicit about using the typedef, and do not assume that it will be preserved by language features like __typeof and C++ template argument substitution.

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 :ref:`optimization rules <arc.optimization>` 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.

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 :ref:`ownership <arc.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.

A function or method parameter of retainable object pointer type may be marked as consumed, signifying that the callee expects to take ownership of a +1 retain count. This is done by adding the ns_consumed attribute to the parameter declaration, like so:

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

This attribute is part of the type of the function or method, not the type of the parameter. It controls only how the argument is passed and received.

When passing such an argument, ARC retains the argument prior to making the call.

When receiving such an argument, ARC releases the argument at the end of the function, subject to the usual optimizations for local values.

The implicit self parameter of a method may be marked as consumed by adding __attribute__((ns_consumes_self)) to the method declaration. Methods in the init :ref:`family <arc.method-families>` are treated as if they were implicitly marked with this attribute.

It is undefined behavior if an Objective-C message send to a method with ns_consumed parameters (other than self) is made with a null receiver. It is undefined behavior if the method to which an Objective-C message send statically resolves to has a different set of ns_consumed parameters than the method it dynamically resolves to. It is undefined behavior if a block or function call is made through a static type with a different set of ns_consumed parameters than the implementation of the called block or function.

A function or method which returns a retainable object pointer type may be marked as returning a retained value, signifying that the caller expects to take ownership of a +1 retain count. This is done by adding the ns_returns_retained attribute to the function or method declaration, like so:

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

This attribute is part of the type of the function or method.

When returning from such a function or method, ARC retains the value at the point of evaluation of the return statement, before leaving all local scopes.

When receiving a return result from such a function or method, ARC releases the value at the end of the full-expression it is contained within, subject to the usual optimizations for local values.

Methods in the alloc, copy, init, mutableCopy, and new :ref:`families <arc.method-families>` are implicitly marked __attribute__((ns_returns_retained)). This may be suppressed by explicitly marking the method __attribute__((ns_returns_not_retained)).

It is undefined behavior if the method to which an Objective-C message send statically resolves has different retain semantics on its result from the method it dynamically resolves to. It is undefined behavior if a block or function call is made through a static type with different retain semantics on its result from the implementation of the called block or function.

A method or function which returns a retainable object type but does not return a retained value must ensure that the object is still valid across the return boundary.

When returning from such a function or method, ARC retains the value at the point of evaluation of the return statement, then leaves all local scopes, and then balances out the retain while ensuring that the value lives across the call boundary. In the worst case, this may involve an autorelease, but callers must not assume that the value is actually in the autorelease pool.

ARC performs no extra mandatory work on the caller side, although it may elect to do something to shorten the lifetime of the returned value.

A method or function may be marked with __attribute__((ns_returns_autoreleased)) to indicate that it returns a pointer which is guaranteed to be valid at least as long as the innermost autorelease pool. There are no additional semantics enforced in the definition of such a method; it merely enables optimizations in callers.

A bridged cast is a C-style cast annotated with one of three keywords:

• (__bridge T) op casts the operand to the destination type T. If T is a retainable object pointer type, then op must have a non-retainable pointer type. If T is a non-retainable pointer type, then op must have a retainable object pointer type. Otherwise the cast is ill-formed. There is no transfer of ownership, and ARC inserts no retain operations.
• (__bridge_retained T) op casts the operand, which must have retainable object pointer type, to the destination type, which must be a non-retainable pointer type. ARC retains the value, subject to the usual optimizations on local values, and the recipient is responsible for balancing that +1.
• (__bridge_transfer T) op casts the operand, which must have non-retainable pointer type, to the destination type, which must be a retainable object pointer type. ARC will release the value at the end of the enclosing full-expression, subject to the usual optimizations on local values.

These casts are required in order to transfer objects in and out of ARC control; see the rationale in the section on :ref:`conversion of retainable object pointers <arc.objects.restrictions.conversion>`.

Using a __bridge_retained or __bridge_transfer cast purely to convince ARC to emit an unbalanced retain or release, respectively, is poor form.

In general, a program which attempts to implicitly or explicitly convert a value of retainable object pointer type to any non-retainable type, or vice-versa, is ill-formed. For example, an Objective-C object pointer shall not be converted to void*. As an exception, cast to intptr_t is allowed because such casts are not transferring ownership. The :ref:`bridged casts <arc.objects.operands.casts>` may be used to perform these conversions where necessary.

However, the following exceptions apply.

[beginning Apple 4.0, LLVM 3.1] These exceptions have been greatly expanded; they previously applied only to a much-reduced subset which is difficult to categorize but which included null pointers, message sends (under the given rules), and the various global constants.

An unbridged conversion to a retainable object pointer type from a type other than a retainable object pointer type is ill-formed, as discussed above, unless the operand of the cast has a syntactic form which is known retained, known unretained, or known retain-agnostic.

An expression is known retain-agnostic if it is:

• an Objective-C string literal,
• a load from a const system global variable of :ref:`C retainable pointer type <arc.misc.c-retainable>`, or
• a null pointer constant.

An expression is known unretained if it is an rvalue of :ref:`C retainable pointer type <arc.misc.c-retainable>` and it is:

• a direct call to a function, and either that function has the cf_returns_not_retained attribute or it is an :ref:`audited <arc.misc.c-retainable.audit>` function that does not have the cf_returns_retained attribute and does not follow the create/copy naming convention,
• a message send, and the declared method either has the cf_returns_not_retained attribute or it has neither the cf_returns_retained attribute nor a :ref:`selector family <arc.method-families>` that implies a retained result, or
• [beginning LLVM 3.6] a load from a const non-system global variable.

An expression is known retained if it is an rvalue of :ref:`C retainable pointer type <arc.misc.c-retainable>` and it is:

• a message send, and the declared method either has the cf_returns_retained attribute, or it does not have the cf_returns_not_retained attribute but it does have a :ref:`selector family <arc.method-families>` that implies a retained result.

Furthermore:

• a comma expression is classified according to its right-hand side,
• a statement expression is classified according to its result expression, if it has one,
• an lvalue-to-rvalue conversion applied to an Objective-C property lvalue is classified according to the underlying message send, and
• a conditional operator is classified according to its second and third operands, if they agree in classification, or else the other if one is known retain-agnostic.

If the cast operand is known retained, the conversion is treated as a __bridge_transfer cast. If the cast operand is known unretained or known retain-agnostic, the conversion is treated as a __bridge cast.

[beginning Apple 4.0, LLVM 3.1]

If an expression of retainable object pointer type is explicitly cast to a :ref:`C retainable pointer type <arc.misc.c-retainable>`, the program is ill-formed as discussed above unless the result is immediately used:

• to initialize a parameter in an Objective-C message send where the parameter is not marked with the cf_consumed attribute, or
• to initialize a parameter in a direct call to an :ref:`audited <arc.misc.c-retainable.audit>` function where the parameter is not marked with the cf_consumed attribute.

This section describes the behavior of objects of retainable object pointer type; that is, locations in memory which store retainable object pointers.

A type is a retainable object owner type if it is a retainable object pointer type or an array type whose element type is a retainable object owner type.

An ownership qualifier is a type qualifier which applies only to retainable object owner types. An array type is ownership-qualified according to its element type, and adding an ownership qualifier to an array type so qualifies its element type.

A program is ill-formed if it attempts to apply an ownership qualifier to a type which is already ownership-qualified, even if it is the same qualifier. There is a single exception to this rule: an ownership qualifier may be applied to a substituted template type parameter, which overrides the ownership qualifier provided by the template argument.

When forming a function type, the result type is adjusted so that any top-level ownership qualifier is deleted.

Except as described under the :ref:`inference rules <arc.ownership.inference>`, a program is ill-formed if it attempts to form a pointer or reference type to a retainable object owner type which lacks an ownership qualifier.

There are four ownership qualifiers:

• __autoreleasing
• __strong
• __unsafe_unretained
• __weak

A type is nontrivially ownership-qualified if it is qualified with __autoreleasing, __strong, or __weak.

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.

A property of retainable object pointer type may have ownership. If the property's type is ownership-qualified, then the property has that ownership. If the property has one of the following modifiers, then the property has the corresponding ownership. A property is ill-formed if it has conflicting sources of ownership, or if it has redundant ownership modifiers, or if it has __autoreleasing ownership.

• assign implies __unsafe_unretained ownership.
• copy implies __strong ownership, as well as the usual behavior of copy semantics on the setter.
• retain implies __strong ownership.
• strong implies __strong ownership.
• unsafe_unretained implies __unsafe_unretained ownership.
• weak implies __weak ownership.

With the exception of weak, these modifiers are available in non-ARC modes.

A property's specified ownership is preserved in its metadata, but otherwise the meaning is purely conventional unless the property is synthesized. If a property is synthesized, then the associated instance variable is the instance variable which is named, possibly implicitly, by the @synthesize declaration. If the associated instance variable already exists, then its ownership qualification must equal the ownership of the property; otherwise, the instance variable is created with that ownership qualification.

A property of retainable object pointer type which is synthesized without a source of ownership has the ownership of its associated instance variable, if it already exists; otherwise, [beginning Apple 3.1, LLVM 3.1] its ownership is implicitly strong. Prior to this revision, it was ill-formed to synthesize such a property.

Applying __attribute__((NSObject)) to a property not of retainable object pointer type has the same behavior it does outside of ARC: it requires the property type to be some sort of pointer and permits the use of modifiers other than assign. These modifiers only affect the synthesized getter and setter; direct accesses to the ivar (even if synthesized) still have primitive semantics, and the value in the ivar will not be automatically released during deallocation.

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.

It is explicitly permitted for Objective-C classes to not support __weak references. It is undefined behavior to perform an operation with weak assignment semantics with a pointer to an Objective-C object whose class does not support __weak references.

A class may indicate that it does not support weak references by providing the objc_arc_weak_reference_unavailable attribute on the class's interface declaration. A retainable object pointer type is weak-unavailable if is a pointer to an (optionally protocol-qualified) Objective-C class T where T or one of its superclasses has the objc_arc_weak_reference_unavailable attribute. A program is ill-formed if it applies the __weak ownership qualifier to a weak-unavailable type or if the value operand of a weak assignment operation has a weak-unavailable type.

A program is ill-formed if it declares an __autoreleasing object of non-automatic storage duration. A program is ill-formed if it captures an __autoreleasing object in a block or, unless by reference, in a C++11 lambda.

It is undefined behavior if a non-null pointer is assigned to an __autoreleasing object while an autorelease pool is in scope and then that object is read after the autorelease pool's scope is left.

A program is ill-formed if an expression of type T* is converted, explicitly or implicitly, to the type U*, where T and U have different ownership qualification, unless:

• T is qualified with __strong, __autoreleasing, or __unsafe_unretained, and U is qualified with both const and __unsafe_unretained; or
• either T or U is cv void, where cv is an optional sequence of non-ownership qualifiers; or
• the conversion is requested with a reinterpret_cast in Objective-C++; or
• the conversion is a well-formed :ref:`pass-by-writeback <arc.ownership.restrictions.pass_by_writeback>`.

The analogous rule applies to T& and U& in Objective-C++.

It is undefined behavior to access an ownership-qualified object through an lvalue of a differently-qualified type, except that any non-__weak object may be read through an __unsafe_unretained lvalue.

It is undefined behavior if the storage of a __strong or __weak object is not properly initialized before the first managed operation is performed on the object, or if the storage of such an object is freed or reused before the object has been properly deinitialized. Storage for a __strong or __weak object may be properly initialized by filling it with the representation of a null pointer, e.g. by acquiring the memory with calloc or using bzero to zero it out. A __strong or __weak object may be properly deinitialized by assigning a null pointer into it. A __strong object may also be properly initialized by copying into it (e.g. with memcpy) the representation of a different __strong object whose storage has been properly initialized; doing this properly deinitializes the source object and causes its storage to no longer be properly initialized. A __weak object may not be representation-copied in this way.

These requirements are followed automatically for objects whose initialization and deinitialization are under the control of ARC:

• objects of static, automatic, and temporary storage duration
• instance variables of Objective-C objects
• elements of arrays where the array object's initialization and deinitialization are under the control of ARC
• fields of Objective-C struct types where the struct object's initialization and deinitialization are under the control of ARC
• non-static data members of Objective-C++ non-union class types
• Objective-C++ objects and arrays of dynamic storage duration created with the new or new[] operators and destroyed with the corresponding delete or delete[] operator

They are not followed automatically for these objects:

• objects of dynamic storage duration created in other memory, such as that returned by malloc
• union members

Note that dynamically-allocated Objective-C++ arrays of nontrivially-ownership-qualified type are not ABI-compatible with non-ARC code because the non-ARC code will consider the element type to be POD. Such arrays that are new[]'d in ARC translation units cannot be delete[]'d in non-ARC translation units and vice-versa.

If the argument passed to a parameter of type T __autoreleasing * has type U oq *, where oq is an ownership qualifier, then the argument is a candidate for pass-by-writeback` if:

• oq is __strong or __weak, and
• it would be legal to initialize a T __strong * with a U __strong *.

For purposes of overload resolution, an implicit conversion sequence requiring a pass-by-writeback is always worse than an implicit conversion sequence not requiring a pass-by-writeback.

The pass-by-writeback is ill-formed if the argument expression does not have a legal form:

• &var, where var is a scalar variable of automatic storage duration with retainable object pointer type
• a conditional expression where the second and third operands are both legal forms
• a cast whose operand is a legal form
• a null pointer constant

A pass-by-writeback is evaluated as follows:

1. The argument is evaluated to yield a pointer p of type U oq *.
2. If p is a null pointer, then a null pointer is passed as the argument, and no further work is required for the pass-by-writeback.
3. Otherwise, a temporary of type T __autoreleasing is created and initialized to a null pointer.
4. If the parameter is not an Objective-C method parameter marked out, then *p is read, and the result is written into the temporary with primitive semantics.
5. The address of the temporary is passed as the argument to the actual call.
6. After the call completes, the temporary is loaded with primitive semantics, and that value is assigned into *p.

A program is ill-formed if it declares a member of a C struct or union to have a nontrivially ownership-qualified type.

This restriction does not apply in Objective-C++. However, nontrivally ownership-qualified types are considered non-POD: in C++11 terms, they are not trivially default constructible, copy constructible, move constructible, copy assignable, move assignable, or destructible. It is a violation of C++'s One Definition Rule to use a class outside of ARC that, under ARC, would have a nontrivially ownership-qualified member.

If an object is declared with retainable object owner type, but without an explicit ownership qualifier, its type is implicitly adjusted to have __strong qualification.

As a special case, if the object's base type is Class (possibly protocol-qualified), the type is adjusted to have __unsafe_unretained qualification instead.

If a function or method parameter has type T*, where T is an ownership-unqualified retainable object pointer type, then:

• if T is const-qualified or Class, then it is implicitly qualified with __unsafe_unretained;
• otherwise, it is implicitly qualified with __autoreleasing.

Such a type written anywhere else would be ill-formed by the general rule requiring ownership qualifiers.

This rule does not apply in Objective-C++ if a parameter's type is dependent in a template pattern and is only instantiated to a type which would be a pointer to an unqualified retainable object pointer type. Such code is still ill-formed.

If a template argument for a template type parameter is an retainable object owner type that does not have an explicit ownership qualifier, it is adjusted to have __strong qualification. This adjustment occurs regardless of whether the template argument was deduced or explicitly specified.

An Objective-C method may fall into a method family, which is a conventional set of behaviors ascribed to it by the Cocoa conventions.

A method is in a certain method family if:

• it has a objc_method_family attribute placing it in that family; or if not that,
• it does not have an objc_method_family attribute placing it in a different or no family, and
• its selector falls into the corresponding selector family, and
• its signature obeys the added restrictions of the method family.

A selector is in a certain selector family if, ignoring any leading underscores, the first component of the selector either consists entirely of the name of the method family or it begins with that name followed by a character other than a lowercase letter. For example, _perform:with: and performWith: would fall into the perform family (if we recognized one), but performing:with would not.

The families and their added restrictions are:

• alloc methods must return a retainable object pointer type.

• copy methods must return a retainable object pointer type.

• mutableCopy methods must return a retainable object pointer type.

• new methods must return a retainable object pointer type.

• init methods must be instance methods and must return an Objective-C pointer type. Additionally, a program is ill-formed if it declares or contains a call to an init method whose return type is neither id nor a pointer to a super-class or sub-class of the declaring class (if the method was declared on a class) or the static receiver type of the call (if it was declared on a protocol).

  Rationale

  There are a fair number of existing methods with init-like selectors which nonetheless don't follow the init conventions. Typically these are either accidental naming collisions or helper methods called during initialization. Because of the peculiar retain/release behavior of init methods, it's very important not to treat these methods as init methods if they aren't meant to be. It was felt that implicitly defining these methods out of the family based on the exact relationship between the return type and the declaring class would be much too subtle and fragile. Therefore we identify a small number of legitimate-seeming return types and call everything else an error. This serves the secondary purpose of encouraging programmers not to accidentally give methods names in the init family.

  Note that a method with an init-family selector which returns a non-Objective-C type (e.g. void) is perfectly well-formed; it simply isn't in the init family.

A program is ill-formed if a method's declarations, implementations, and overrides do not all have the same method family.

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.

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 :ref:`return a retained object <arc.object.operands.retained-return-values>` 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 :ref:`retained objects <arc.object.operands.retained-return-values>`. This can be overridden by annotating the property with ns_returns_not_retained attribute.

Methods in the init family implicitly :ref:`consume <arc.objects.operands.consumed>` their self parameter and :ref:`return a retained object <arc.object.operands.retained-return-values>`. Neither of these properties can be altered through attributes.

A call to an init method with a receiver that is either self (possibly parenthesized or casted) or super is called a delegate init call. It is an error for a delegate init call to be made except from an init method, and excluding blocks within such methods.

As an exception to the :ref:`usual rule <arc.misc.self>`, the variable self is mutable in an init method and has the usual semantics for a __strong variable. However, it is undefined behavior and the program is ill-formed, no diagnostic required, if an init method attempts to use the previous value of self after the completion of a delegate init call. It is conventional, but not required, for an init method to return self.

It is undefined behavior for a program to cause two or more calls to init methods on the same object, except that each init method invocation may perform at most one delegate init call.

Certain methods are candidates to have related result types:

• class methods in the alloc and new method families
• instance methods in the init family
• the instance method self
• outside of ARC, the instance methods retain and autorelease

If the formal result type of such a method is id or protocol-qualified id, or a type equal to the declaring class or a superclass, then it is said to have a related result type. In this case, when invoked in an explicit message send, it is assumed to return a type related to the type of the receiver:

• if it is a class method, and the receiver is a class name T, the message send expression has type T*; otherwise
• if it is an instance method, and the receiver has type T, the message send expression has type T; otherwise
• the message send expression has the normal result type of the method.

This is a new rule of the Objective-C language and applies outside of ARC.

Within this section, the word function will be used to refer to any structured unit of code, be it a C function, an Objective-C method, or a block.

This specification describes ARC as performing specific retain and release operations on retainable object pointers at specific points during the execution of a program. These operations make up a non-contiguous subsequence of the computation history of the program. The portion of this sequence for a particular retainable object pointer for which a specific function execution is directly responsible is the formal local retain history of the object pointer. The corresponding actual sequence executed is the dynamic local retain history.

However, under certain circumstances, ARC is permitted to re-order and eliminate operations in a manner which may alter the overall computation history beyond what is permitted by the general "as if" rule of C/C++ and the :ref:`restrictions <arc.objects.retains>` on the implementation of retain and release.

id x = _ivar;
[x foo];

ARC makes no guarantees about the execution of a computation history which contains undefined behavior. In particular, ARC makes no guarantees in the presence of race conditions.

ARC may assume that any retainable object pointers it receives or generates are instantaneously valid from that point until a point which, by the concurrency model of the host language, happens-after the generation of the pointer and happens-before a release of that object (possibly via an aliasing pointer or indirectly due to destruction of a different object).

ARC may assume that non-ARC code engages in sensible balancing behavior and does not rely on exact or minimum retain count values except as guaranteed by __strong object invariants or +1 transfer conventions. For example, if an object is provably double-retained and double-released, ARC may eliminate the inner retain and release; it does not need to guard against code which performs an unbalanced release followed by a "balancing" retain.

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 :ref:`precise lifetime semantics <arc.optimization.precise>`, 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.

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.

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.

A program is ill-formed if it contains a method definition, message send, or @selector expression for any of the following selectors:

• autorelease
• release
• retain
• retainCount

A program is ill-formed if it contains a message send or @selector expression for the selector dealloc.

A class may provide a method definition for an instance method named dealloc. This method will be called after the final release of the object but before it is deallocated or any of its instance variables are destroyed. The superclass's implementation of dealloc will be called automatically when the method returns.

The instance variables for an ARC-compiled class will be destroyed at some point after control enters the dealloc method for the root class of the class. The ordering of the destruction of instance variables is unspecified, both within a single class and between subclasses and superclasses.

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.

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 :ref:`self parameter in a non-init method <arc.misc.self>` and the :ref:`variable in a for-in loop <arc.misc.enumeration>` 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

The self parameter variable of an non-init Objective-C method is considered :ref:`externally-retained <arc.misc.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>.

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 :ref:`externally-retained <arc.misc.externally_retained>` so that objects encountered during the enumeration are not actually retained and released.

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 :ref:`inference <arc.ownership.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.

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.

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 :ref:`precise lifetime semantics <arc.optimization.precise>`.

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.

[beginning Apple 4.0, LLVM 3.1]

A C function may be marked with the cf_audited_transfer attribute to express that, except as otherwise marked with attributes, it obeys the parameter (consuming vs. non-consuming) and return (retained vs. non-retained) conventions for a C function of its name, namely:

• A parameter of C retainable pointer type is assumed to not be consumed unless it is marked with the cf_consumed attribute, and
• A result of C retainable pointer type is assumed to not be returned retained unless the function is either marked cf_returns_retained or it follows the create/copy naming convention and is not marked cf_returns_not_retained.

A function obeys the create/copy naming convention if its name contains as a substring:

• either "Create" or "Copy" not followed by a lowercase letter, or
• either "create" or "copy" not followed by a lowercase letter and not preceded by any letter, whether uppercase or lowercase.

A second attribute, cf_unknown_transfer, signifies that a function's transfer semantics cannot be accurately captured using any of these annotations. A program is ill-formed if it annotates the same function with both cf_audited_transfer and cf_unknown_transfer.

A pragma is provided to facilitate the mass annotation of interfaces:

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

All C functions declared within the extent of this pragma are treated as if annotated with the cf_audited_transfer attribute unless they otherwise have the cf_unknown_transfer attribute. The pragma is accepted in all language modes. A program is ill-formed if it attempts to change files, whether by including a file or ending the current file, within the extent of this pragma.

It is possible to test for all the features in this section with __has_feature(arc_cf_code_audited).

This section describes the interaction between the ARC runtime and the code generated by the ARC compiler. This is not part of the ARC language specification; instead, it is effectively a language-specific ABI supplement, akin to the "Itanium" generic ABI for C++.

Ownership qualification does not alter the storage requirements for objects, except that it is undefined behavior if a __weak object is inadequately aligned for an object of type id. The other qualifiers may be used on explicitly under-aligned memory.

The runtime tracks __weak objects which holds non-null values. It is undefined behavior to direct modify a __weak object which is being tracked by the runtime except through an :ref:`objc_storeWeak <arc.runtime.objc_storeWeak>`, :ref:`objc_destroyWeak <arc.runtime.objc_destroyWeak>`, or :ref:`objc_moveWeak <arc.runtime.objc_moveWeak>` call.

The runtime must provide a number of new entrypoints which the compiler may emit, which are described in the remainder of this section.

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.

Precondition: pool is the result of a previous call to :ref:`objc_autoreleasePoolPush <arc.runtime.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.

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

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 :ref:`objc_retainAutoreleasedReturnValue <arc.runtime.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.

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.

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.

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.

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.

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.

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 :ref:`objc_copyWeak <arc.runtime.objc_copyWeak>`, or it may be left as null.

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

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.

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.

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.

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 :ref:`objc_autoreleaseReturnValue <arc.runtime.objc_autoreleaseReturnValue>`. Equivalent to the following code:

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

Always returns 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 :ref:`objc_autoreleaseReturnValue <arc.runtime.objc_autoreleaseReturnValue>` on value in a recently-called function or something it calls. If that fails, it performs a retain operation exactly like :ref:`objc_retain <arc.runtime.objc_retain>`.

Always returns 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.

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];
}

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.