From 6c48a8c4ee78f97ec68507513234f95e7c177e5b Mon Sep 17 00:00:00 2001 From: Dmitri Gribenko Date: Thu, 13 Dec 2012 16:04:37 +0000 Subject: [PATCH] Documentation: convert AutomaticReferenceCounting.html to reST Patch by Anastasi Voitova with with small fixes by me. llvm-svn: 170132 --- clang/docs/AutomaticReferenceCounting.html | 2226 ---------------------------- clang/docs/AutomaticReferenceCounting.rst | 2061 +++++++++++++++++++++++++ 2 files changed, 2061 insertions(+), 2226 deletions(-) delete mode 100644 clang/docs/AutomaticReferenceCounting.html create mode 100644 clang/docs/AutomaticReferenceCounting.rst diff --git a/clang/docs/AutomaticReferenceCounting.html b/clang/docs/AutomaticReferenceCounting.html deleted file mode 100644 index 5354f8a..0000000 --- a/clang/docs/AutomaticReferenceCounting.html +++ /dev/null @@ -1,2226 +0,0 @@ - - - -Objective-C Automatic Reference Counting (ARC) - - - - - - - - - - -
-

Automatic Reference Counting

- -
-
- -
-

About this document

- -
-

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.

- -
- -
- -
-

General

- -

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 language -extensions document.

- -
- -
-

Retainable object pointers

- -

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.

- -
- -

Rationale: We are not at liberty to require -all code to be recompiled with ARC; therefore, ARC must interoperate -with Objective-C code which manages retains and releases manually. In -general, there are three requirements in order for a -compiler-supported reference-count system to provide reliable -interoperation:

- -
    -
  • The type system must reliably identify which objects are to be -managed. An int* might be a pointer to a malloc'ed -array, or it might be an interior pointer to such an array, or it might -point to some field or local variable. In contrast, values of the -retainable object pointer types are never interior.
  • -
  • The type system must reliably indicate how to -manage objects of a type. This usually means that the type must imply -a procedure for incrementing and decrementing retain counts. -Supporting single-ownership objects requires a lot more explicit -mediation in the language.
  • -
  • There must be reliable conventions for whether and -when ownership is passed between caller and callee, for both -arguments and return values. Objective-C methods follow such a -convention very reliably, at least for system libraries on Mac OS X, -and functions always pass objects at +0. The C-based APIs for Core -Foundation objects, on the other hand, have much more varied transfer -semantics.
  • -
-
- -

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.

- -

Rationale: any compiler operation which -incidentally strips type sugar from a type will yield a type -without the attribute, which may result in unexpected -behavior.

- -
-

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.
  • -
- -

Rationale: while this might seem -uncontroversial, it is actually unsafe when multiple expressions are -evaluated in parallel, as with binary operators and calls, -because (for example) one expression might load from an object while -another writes to it. However, C and C++ already call this undefined -behavior because the evaluations are unsequenced, and ARC simply -exploits that here to avoid needing to retain arguments across a large -number of calls.

- -

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

- -
-

Consumed parameters

- -

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.

- -

Rationale: this formalizes direct transfers -of ownership from a caller to a callee. The most common scenario here -is passing the self parameter to init, but it is -useful to generalize. Typically, local optimization will remove any -extra retains and releases: on the caller side the retain will be -merged with a +1 source, and on the callee side the release will be -rolled into the initialization of the parameter.

- -

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 -family 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.

- -

Rationale: consumed parameters with null -receiver are a guaranteed leak. Mismatches with consumed parameters -will cause over-retains or over-releases, depending on the direction. -The rule about function calls is really just an application of the -existing C/C++ rule about calling functions through an incompatible -function type, but it's useful to state it explicitly.

- -
- -
-

Retained return values

- -

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.

- -

Rationale: this formalizes direct transfers of -ownership from a callee to a caller. The most common scenario this -models is the retained return from init, alloc, -new, and copy methods, but there are other cases in -the frameworks. After optimization there are typically no extra -retains and releases required.

- -

Methods in -the alloc, copy, init, mutableCopy, -and new 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.

- -

Rationale: Mismatches with returned results -will cause over-retains or over-releases, depending on the direction. -Again, the rule about function calls is really just an application of -the existing C/C++ rule about calling functions through an -incompatible function type.

- -
- -
-

Unretained return values

- -

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.

- -

Rationale: it is common in non-ARC code to not -return an autoreleased value; therefore the convention does not force -either path. It is convenient to not be required to do unnecessary -retains and autoreleases; this permits optimizations such as eliding -retain/autoreleases when it can be shown that the original pointer -will still be valid at the point of return.

- -

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.

- -
- -
-

Bridged casts

- -

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 conversion of retainable -object pointers.

- -

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

- -
- -
- -
-

Restrictions

- -
-

Conversion of retainable object pointers

- -

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 bridged -casts may be used to perform these conversions where -necessary.

- -

Rationale: we cannot ensure the correct -management of the lifetime of objects if they may be freely passed -around as unmanaged types. The bridged casts are provided so that the -programmer may explicitly describe whether the cast transfers control -into or out of ARC.

- -

However, the following exceptions apply.

- -
- -
-

Conversion to retainable object pointer type of - expressions with known semantics

- -

[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 -C retainable pointer type, or
  • -
  • a null pointer constant.
  • -
- -

An expression is known unretained if it -is an rvalue of C retainable -pointer type and it is:

-
    -
  • a direct call to a function, and either that function has the - cf_returns_not_retained attribute or it is an - audited 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 - selector family that implies a retained - result.
  • -
- -

An expression is known retained if it is -an rvalue of C retainable pointer type -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 - selector family 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.

- -

Rationale: Bridging casts are annoying. -Absent the ability to completely automate the management of CF -objects, however, we are left with relatively poor attempts to reduce -the need for a glut of explicit bridges. Hence these rules.

- -

We've so far consciously refrained from implicitly turning retained -CF results from function calls into __bridge_transfer casts. -The worry is that some code patterns — for example, creating a -CF value, assigning it to an ObjC-typed local, and then -calling CFRelease when done — are a bit too likely to -be accidentally accepted, leading to mysterious behavior.

- -
- -
-

Conversion from retainable object pointer type in certain contexts

- -

[beginning Apple - 4.0, LLVM 3.1]

- -

If an expression of retainable object pointer type is explicitly -cast to a C retainable pointer type, -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 audited function where the -parameter is not marked with the cf_consumed attribute.
  • -
- -

Rationale: Consumed parameters are left out -because ARC would naturally balance them with a retain, which was -judged too treacherous. This is in part because several of the most -common consuming functions are in the Release family, and it -would be quite unfortunate for explicit releases to be silently -balanced out in this way.

- -
- -
- -
- -
-

Ownership qualification

- -

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.

- -

Except as described under -the inference rules, 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.

- -

Rationale: these rules, together with the -inference rules, ensure that all objects and lvalues of retainable -object pointer type have an ownership qualifier. The ability to override an ownership qualifier during template substitution is required to counteract the inference of __strong for template type arguments.

- -

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.

- -
-

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 applies to that type;
  • -
  • if the outermost non-array part of the declarator is a pointer or -block pointer, the qualifier applies to that type;
  • -
  • otherwise the program is ill-formed.
  • -
- -

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

- -

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

- -
-

Property declarations

- -

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.

- -

Rationale: using strong by default -is safe and consistent with the generic ARC rule about -inferring ownership. It -is, unfortunately, inconsistent with the non-ARC rule which states -that such properties are implicitly assign. However, that -rule is clearly untenable in ARC, since it leads to default-unsafe -code. The main merit to banning the properties is to avoid confusion -with non-ARC practice, which did not ultimately strike us as -sufficient to justify requiring extra syntax and (more importantly) -forcing novices to understand ownership rules just to declare a -property when the default is so reasonable. Changing the rule away -from non-ARC practice was acceptable because we had conservatively -banned the synthesis in order to give ourselves exactly this -leeway.

- -

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.

- -
- -
- -
-

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. -
  3. Second, if the object has an initializer, that expression is -evaluated and then assigned into the object using the usual assignment -semantics.
  4. -
- -

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

- -
-

Weak-unavailable types

- -

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.

- -

Rationale: historically, it has been -possible for a class to provide its own reference-count implementation -by overriding retain, release, etc. However, weak -references to an object require coordination with its class's -reference-count implementation because, among other things, weak loads -and stores must be atomic with respect to the final release. -Therefore, existing custom reference-count implementations will -generally not support weak references without additional effort. This -is unavoidable without breaking binary compatibility.

- -

A class may indicate that it does not support weak references by -providing the objc_arc_weak_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_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.

-
- -
-

Storage duration of __autoreleasing objects

- -

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.

- -

Rationale: autorelease pools are tied to the -current thread and scope by their nature. While it is possible to -have temporary objects whose instance variables are filled with -autoreleased objects, there is no way that ARC can provide any sort of -safety guarantee there.

- -

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.

- -
- -
-

Conversion of pointers to ownership-qualified types

- -

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 pass-by-writeback.
  • -
- -

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

- -

Rationale: these rules provide a reasonable -level of type-safety for indirect pointers, as long as the underlying -memory is not deallocated. The conversion to const -__unsafe_unretained is permitted because the semantics of reads -are equivalent across all these ownership semantics, and that's a very -useful and common pattern. The interconversion with void* is -useful for allocating memory or otherwise escaping the type system, -but use it carefully. reinterpret_cast is considered to be -an obvious enough sign of taking responsibility for any -problems.

- -

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 a managed operation is performed on -a __strong or __weak object without a guarantee that -it contains a primitive zero bit-pattern, or if the storage for such -an object is freed or reused without the object being first assigned a -null pointer.

- -

Rationale: ARC cannot differentiate between -an assignment operator which is intended to initialize dynamic -memory and one which is intended to potentially replace a value. -Therefore the object's pointer must be valid before letting ARC at it. -Similarly, C and Objective-C do not provide any language hooks for -destroying objects held in dynamic memory, so it is the programmer's -responsibility to avoid leaks (__strong objects) and -consistency errors (__weak objects).

- -

These requirements are followed automatically in Objective-C++ when -creating objects of retainable object owner type with new -or new[] and destroying them with delete, -delete[], or a pseudo-destructor expression. Note that -arrays of nontrivially-ownership-qualified type are not ABI compatible -with non-ARC code because the element type is non-POD: such arrays -that are new[]'d in ARC translation units cannot -be delete[]'d in non-ARC translation units and -vice-versa.

- -
- -
-

Passing to an out parameter by writeback

- -

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
  • -
- -

Rationale: the restriction in the form of -the argument serves two purposes. First, it makes it impossible to -pass the address of an array to the argument, which serves to protect -against an otherwise serious risk of mis-inferring an array -argument as an out-parameter. Second, it makes it much less likely -that the user will see confusing aliasing problems due to the -implementation, below, where their store to the writeback temporary is -not immediately seen in the original argument variable.

- -

A pass-by-writeback is evaluated as follows:

-
    -
  1. The argument is evaluated to yield a pointer p of - type U oq *.
  2. -
  3. 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.
  4. -
  5. Otherwise, a temporary of type T __autoreleasing is - created and initialized to a null pointer.
  6. -
  7. 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.
  8. -
  9. The address of the temporary is passed as the argument to the - actual call.
  10. -
  11. After the call completes, the temporary is loaded with primitive - semantics, and that value is assigned into *p.
  12. -
- -

Rationale: this is all admittedly -convoluted. In an ideal world, we would see that a local variable is -being passed to an out-parameter and retroactively modify its type to -be __autoreleasing rather than __strong. This would -be remarkably difficult and not always well-founded under the C type -system. However, it was judged unacceptably invasive to require -programmers to write __autoreleasing on all the variables -they intend to use for out-parameters. This was the least bad -solution.

- -
- -
-

Ownership-qualified fields of structs and unions

- -

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

- -

Rationale: the resulting type would be -non-POD in the C++ sense, but C does not give us very good language -tools for managing the lifetime of aggregates, so it is more -convenient to simply forbid them. It is still possible to manage this -with a void* or an __unsafe_unretained -object.

- -

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.

- -

Rationale: unlike in C, we can express all -the necessary ARC semantics for ownership-qualified subobjects as -suboperations of the (default) special member functions for the class. -These functions then become non-trivial. This has the non-obvious -result that the class will have a non-trivial copy constructor and -non-trivial destructor; if this would not normally be true outside of -ARC, objects of the type will be passed and returned in an -ABI-incompatible manner.

- -
- -
- -
-

Ownership inference

- -
-

Objects

- -

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.

- -
- -
-

Indirect parameters

- -

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.
  • -
- -

Rationale: __autoreleasing exists -mostly for this case, the Cocoa convention for out-parameters. Since -a pointer to const is obviously not an out-parameter, we -instead use a type more useful for passing arrays. If the user -instead intends to pass in a mutable array, inferring -__autoreleasing is the wrong thing to do; this directs some -of the caution in the following rules about writeback.

- -

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.

- -

Rationale: the convention is very unlikely -to be intentional in template code.

- -
- -
-

Template arguments

- -

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.

- -

Rationale: __strong is a useful default for containers (e.g., std::vector<id>), which would otherwise require explicit qualification. Moreover, unqualified retainable object pointer types are unlikely to be useful within templates, since they generally need to have a qualifier applied to the before being used.

- -
-
-
- - -
-

Method families

- -

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.

- -
-

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.

- -

Rationale: the rules codified in this document -describe the standard conventions of Objective-C. However, as these -conventions have not heretofore been enforced by an unforgiving -mechanical system, they are only imperfectly kept, especially as they -haven't always even been precisely defined. While it is possible to -define low-level ownership semantics with attributes like -ns_returns_retained, this attribute allows the user to -communicate semantic intent, which is of use both to ARC (which, e.g., -treats calls to init specially) and the static analyzer.

-
- -
-

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.

- -
-

Semantics of init

-

Methods in the init family implicitly -consume their self -parameter and return a -retained object. 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 usual rule, 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.

- -
- -
-

Related result types

- -

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.

- -

Rationale: ARC's automatic code emission is -more prone than most code to signature errors, i.e. errors where a -call was emitted against one method signature, but the implementing -method has an incompatible signature. Having more precise type -information helps drastically lower this risk, as well as catching -a number of latent bugs.

- -
-
-
- -
-

Optimization

- -

ARC applies aggressive rules for the optimization of local -behavior. These rules are based around a core assumption of -local balancing: that other code will -perform retains and releases as necessary (and only as necessary) for -its own safety, and so the optimizer does not need to consider global -properties of the retain and release sequence. For example, if a -retain and release immediately bracket a call, the optimizer can -delete the retain and release on the assumption that the called -function will not do a constant number of unmotivated releases -followed by a constant number of balancing retains, such that -the local retain/release pair is the only thing preventing the called -function from ending up with a dangling reference.

- -

The optimizer assumes that when a new value enters local control, -e.g. from a load of a non-local object or as the result of a function -call, it is instaneously valid. Subsequently, a retain and release of -a value are necessary on a computation path only if there is a use of -that value before the release and after any operation which might -cause a release of the value (including indirectly or non-locally), -and only if the value is not demonstrably already retained.

- -

The complete optimization rules are quite complicated, but it would -still be useful to document them here.

- -
-

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.

- -

Rationale: applying these precise-lifetime -semantics strictly would be prohibitive. Many useful optimizations -that might theoretically decrease the lifetime of an object would be -rendered impossible. Essentially, it promises too much.

- -

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.

- -

Rationale: nonetheless, it is sometimes -useful to be able to force an object to be released at a precise time, -even if that object does not appear to be used. This is likely to be -uncommon enough that the syntactic weight of explicitly requesting -these semantics will not be burdensome, and may even make the code -clearer.

- -
- -
- -
-

Miscellaneous

- -
-

Special methods

- -
-

Memory management methods

- -

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
  • -
- -

Rationale: retainCount is banned -because ARC robs it of consistent semantics. The others were banned -after weighing three options for how to deal with message sends:

- -

Honoring them would work out very poorly if a programmer -naively or accidentally tried to incorporate code written for manual -retain/release code into an ARC program. At best, such code would do -twice as much work as necessary; quite frequently, however, ARC and -the explicit code would both try to balance the same retain, leading -to crashes. The cost is losing the ability to perform unrooted -retains, i.e. retains not logically corresponding to a strong -reference in the object graph.

- -

Ignoring them would badly violate user expectations about their -code. While it would make it easier to develop code simultaneously -for ARC and non-ARC, there is very little reason to do so except for -certain library developers. ARC and non-ARC translation units share -an execution model and can seamlessly interoperate. Within a -translation unit, a developer who faithfully maintains their code in -non-ARC mode is suffering all the restrictions of ARC for zero -benefit, while a developer who isn't testing the non-ARC mode is -likely to be unpleasantly surprised if they try to go back to it.

- -

Banning them has the disadvantage of making it very awkward -to migrate existing code to ARC. The best answer to that, given a -number of other changes and restrictions in ARC, is to provide a -specialized tool to assist users in that migration.

- -

Implementing these methods was banned because they are too integral -to the semantics of ARC; many tricks which worked tolerably under -manual reference counting will misbehave if ARC performs an ephemeral -extra retain or two. If absolutely required, it is still possible to -implement them in non-ARC code, for example in a category; the -implementations must obey the semantics -laid out elsewhere in this document.

- -
-
- -
-

dealloc

- -

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

- -

Rationale: there are no legitimate reasons -to call dealloc directly.

- -

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.

- -

Rationale: even though ARC destroys instance -variables automatically, there are still legitimate reasons to write -a dealloc method, such as freeing non-retainable resources. -Failing to call [super dealloc] in such a method is nearly -always a bug. Sometimes, the object is simply trying to prevent -itself from being destroyed, but dealloc is really far too -late for the object to be raising such objections. Somewhat more -legitimately, an object may have been pool-allocated and should not be -deallocated with free; for now, this can only be supported -with a dealloc implementation outside of ARC. Such an -implementation must be very careful to do all the other work -that NSObject's dealloc would, which is outside the -scope of this document to describe.

- -

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.

- -

Rationale: the traditional, non-ARC pattern -for destroying instance variables is to destroy them immediately -before calling [super dealloc]. Unfortunately, message -sends from the superclass are quite capable of reaching methods in the -subclass, and those methods may well read or write to those instance -variables. Making such message sends from dealloc is generally -discouraged, since the subclass may well rely on other invariants that -were broken during dealloc, but it's not so inescapably -dangerous that we felt comfortable calling it undefined behavior. -Therefore we chose to delay destroying the instance variables to a -point at which message sends are clearly disallowed: the point at -which the root class's deallocation routines take over.

- -

In most code, the difference is not observable. It can, however, -be observed if an instance variable holds a strong reference to an -object whose deallocation will trigger a side-effect which must be -carefully ordered with respect to the destruction of the super class. -Such code violates the design principle that semantically important -behavior should be explicit. A simple fix is to clear the instance -variable manually during dealloc; a more holistic solution is -to move semantically important side-effects out of -dealloc and into a separate teardown phase which can rely on -working with well-formed objects.

- -
- -
- -
-

@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.

- -

Rationale: autorelease pools are clearly -important for the compiler to reason about, but it is far too much to -expect the compiler to accurately reason about control dependencies -between two calls. It is also very easy to accidentally forget to -drain an autorelease pool when using the manual API, and this can -significantly inflate the process's high-water-mark. The introduction -of a new scope is unfortunate but basically required for sane -interaction with the rest of the language. Not draining the pool -during an unwind is apparently required by the Objective-C exceptions -implementation.

- -
- -
-

self

- -

The self parameter variable of an Objective-C method is -never actually 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.

- -

To make this safe, for Objective-C instance methods self is -implicitly const unless the method is in the init family. Further, self -is always implicitly const within a class method.

- -

Rationale: the cost of -retaining self in all methods was found to be prohibitive, as -it tends to be live across calls, preventing the optimizer from -proving that the retain and release are unnecessary — for good -reason, as it's quite possible in theory to cause an object to be -deallocated during its execution without this retain and release. -Since it's extremely uncommon to actually do so, even unintentionally, -and since there's no natural way for the programmer to remove this -retain/release pair otherwise (as there is for other parameters by, -say, making the variable __unsafe_unretained), we chose to -make this optimizing assumption and shift some amount of risk to the -user.

- -
- -
-

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 qualified with const __strong and -objects encountered during the enumeration are not actually -retained.

- -

Rationale: this is an optimization made -possible because fast enumeration loops promise to keep the objects -retained during enumeration, and the collection itself cannot be -synchronously modified. It can be overridden by explicitly qualifying -the variable with __strong, which will make the variable -mutable again and cause the loop to retain the objects it -encounters.

- -
- -
-

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.

- -

Rationale: the standard Cocoa convention is -that exceptions signal programmer error and are not intended to be -recovered from. Making code exceptions-safe by default would impose -severe runtime and code size penalties on code that typically does not -actually care about exceptions safety. Therefore, ARC-generated code -leaks by default on exceptions, which is just fine if the process is -going to be immediately terminated anyway. Programs which do care -about recovering from exceptions should enable the option.

- -

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

- -

Rationale: C++ already introduces pervasive -exceptions-cleanup code of the sort that ARC introduces. C++ -programmers who have not already disabled exceptions are much more -likely to actual require exception-safety.

- -

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

- -

Rationale: the consequence of a -local __weak object not being destroyed is very likely to be -corruption of the Objective-C runtime, so we want to be safer here. -Of course, potentially massive leaks are about as likely to take down -the process as this corruption is if the program does try to recover -from exceptions.

- -
- -
-

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.
  • -
- -

Rationale: not all memory and resources are -managed with reference counts; it is common for objects to manage -private resources in their own, private way. Typically these -resources are completely encapsulated within the object, but some -classes offer their users direct access for efficiency. If ARC is not -aware of methods that return such interior pointers, its -optimizations can cause the owning object to be reclaimed too soon. -This attribute informs ARC that it must tread lightly.

- -

The extension rules are somewhat intentionally vague. The -autorelease pool limit is there to permit a simple implementation to -simply retain and autorelease the receiver. The other limit permits -some amount of optimization. The phrase derived from is -intended to encompass the results both of pointer transformations, -such as casts and arithmetic, and of loading from such derived -pointers; furthermore, it applies whether or not such derivations are -applied directly in the calling code or by other utility code (for -example, the C library routine strchr). However, the -implementation never need account for uses after a return from the -code which calls the method returning an interior pointer.

- -

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

- -

Rationale: implicit autoreleases carry the -risk of significantly inflating memory use, so it's important to -provide users a way of avoiding these autoreleases. Tying this to -precise lifetime semantics is ideal, as for local variables this -requires a very explicit annotation, which allows ARC to trust the -user with good cheer.

- -
- -
-

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.

- -

Rationale: ARC does not manage pointers of -CoreFoundation type (or any of the related families of retainable C -pointers which interoperate with Objective-C for retain/release -operation). In fact, ARC does not even know how to distinguish these -types from arbitrary C pointer types. The intent of this concept is -to filter out some obviously non-object types while leaving a hook for -later tightening if a means of exhaustively marking CF types is made -available.

- -
-

Auditing of C retainable pointer interfaces

- -

[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).

- -

Rationale: A significant inconvenience in -ARC programming is the necessity of interacting with APIs based around -C retainable pointers. These features are designed to make it -relatively easy for API authors to quickly review and annotate their -interfaces, in turn improving the fidelity of tools such as the static -analyzer and ARC. The single-file restriction on the pragma is -designed to eliminate the risk of accidentally annotating some other -header's interfaces.

- -
- -
- -
- -
-

Runtime support

- -

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 -objc_storeWeak, -objc_destroyWeak, -or 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.

- -

Rationale: Several of these functions are -semantically equivalent to a message send; we emit calls to C -functions instead because:

-
    -
  • the machine code to do so is significantly smaller,
  • -
  • it is much easier to recognize the C functions in the ARC optimizer, and
  • -
  • a sufficient sophisticated runtime may be able to avoid the -message send in common cases.
  • -
- -

Several other of these functions are fused operations which -can be described entirely in terms of other operations. We use the -fused operations primarily as a code-size optimization, although in -some cases there is also a real potential for avoiding redundant -operations in the runtime.

- -
- -
-

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.

- -

Rationale: while the interface is described -as an explicit hierarchy of pools, the rules allow the implementation -to just keep a stack of objects, using the stack depth as the opaque -pool handle.

- -
- -
-

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.

-
Rationale: loading weak references would be -inherently prone to race conditions without the retain.
-
- -
-

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.

-
- -
-

id 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:

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

Always returns value.

-
- -
-

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.

-
- -
-
- - diff --git a/clang/docs/AutomaticReferenceCounting.rst b/clang/docs/AutomaticReferenceCounting.rst new file mode 100644 index 0000000..5c1e7d3 --- /dev/null +++ b/clang/docs/AutomaticReferenceCounting.rst @@ -0,0 +1,2061 @@ +.. sectnum:: +.. contents:: + :local: + +.. FIXME: move to the stylesheet or Sphinx plugin + +.. raw:: html + + + +.. role:: arc-term +.. role:: revision +.. role:: when-revised + +.. title:: Objective-C Automatic Reference Counting (ARC) + +.. _arc.meta: + +=================== +About this document +=================== + +.. _arc.meta.purpose: + +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. + +.. _arc.meta.background: + +Background +========== + +This document assumes a basic familiarity with C. + +:arc-term:`Blocks` are a C language extension for creating anonymous functions. +Users interact with and transfer block objects using :arc-term:`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 :arc-term:`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 :arc-term:`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 +:arc-term:`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 :arc-term:`methods`. A +method has a return type, a list of argument types, and a :arc-term:`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 :arc-term:`receiver`) and a list of formal +arguments interspersed with the selector, like so: + +.. code-block:: objc + + [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 :arc-term:`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. + +:arc-term:`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 +``@interface``\ s of all class extensions. :arc-term:`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 :arc-term:`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.meta.evolution: + +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 + :when-revised:`[beginning Apple 8.0, LLVM 3.8]` :revision:`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. + +.. _arc.general: + +======= +General +======= + +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 ` document. + +.. _arc.objects: + +========================== +Retainable object pointers +========================== + +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 :arc-term:`retainable object pointer` (or "retainable pointer") is a value of +a :arc-term:`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. + +.. admonition:: Rationale + + We are not at liberty to require all code to be recompiled with ARC; + therefore, ARC must interoperate with Objective-C code which manages retains + and releases manually. In general, there are three requirements in order for + a compiler-supported reference-count system to provide reliable + interoperation: + + * The type system must reliably identify which objects are to be managed. An + ``int*`` might be a pointer to a ``malloc``'ed array, or it might be an + interior pointer to such an array, or it might point to some field or local + variable. In contrast, values of the retainable object pointer types are + never interior. + + * The type system must reliably indicate how to manage objects of a type. + This usually means that the type must imply a procedure for incrementing + and decrementing retain counts. Supporting single-ownership objects + requires a lot more explicit mediation in the language. + + * There must be reliable conventions for whether and when "ownership" is + passed between caller and callee, for both arguments and return values. + Objective-C methods follow such a convention very reliably, at least for + system libraries on Mac OS X, and functions always pass objects at +0. The + C-based APIs for Core Foundation objects, on the other hand, have much more + varied transfer semantics. + +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. + +.. admonition:: Rationale + + Any compiler operation which incidentally strips type "sugar" from a type + will yield a type without the attribute, which may result in unexpected + behavior. + +.. _arc.objects.retains: + +Retain count semantics +====================== + +A retainable object pointer is either a :arc-term:`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 +:arc-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 ` 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. + +.. _arc.objects.operands: + +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 :ref:`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. + +.. admonition:: Rationale + + While this might seem uncontroversial, it is actually unsafe when multiple + expressions are evaluated in "parallel", as with binary operators and calls, + because (for example) one expression might load from an object while another + writes to it. However, C and C++ already call this undefined behavior + because the evaluations are unsequenced, and ARC simply exploits that here to + avoid needing to retain arguments across a large number of calls. + +The remainder of this section describes exceptions to these rules, how those +exceptions are detected, and what those exceptions imply semantically. + +.. _arc.objects.operands.consumed: + +Consumed parameters +------------------- + +A function or method parameter of retainable object pointer type may be marked +as :arc-term:`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: + +.. code-block:: objc + + 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. + +.. admonition:: Rationale + + This formalizes direct transfers of ownership from a caller to a callee. The + most common scenario here is passing the ``self`` parameter to ``init``, but + it is useful to generalize. Typically, local optimization will remove any + extra retains and releases: on the caller side the retain will be merged with + a +1 source, and on the callee side the release will be rolled into the + initialization of the parameter. + +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 ` 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. + +.. admonition:: Rationale + + Consumed parameters with null receiver are a guaranteed leak. Mismatches + with consumed parameters will cause over-retains or over-releases, depending + on the direction. The rule about function calls is really just an + application of the existing C/C++ rule about calling functions through an + incompatible function type, but it's useful to state it explicitly. + +.. _arc.object.operands.retained-return-values: + +Retained return values +---------------------- + +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: + +.. code-block:: objc + + 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. + +.. admonition:: Rationale + + This formalizes direct transfers of ownership from a callee to a caller. The + most common scenario this models is the retained return from ``init``, + ``alloc``, ``new``, and ``copy`` methods, but there are other cases in the + frameworks. After optimization there are typically no extra retains and + releases required. + +Methods in the ``alloc``, ``copy``, ``init``, ``mutableCopy``, and ``new`` +:ref:`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. + +.. admonition:: Rationale + + Mismatches with returned results will cause over-retains or over-releases, + depending on the direction. Again, the rule about function calls is really + just an application of the existing C/C++ rule about calling functions + through an incompatible function type. + +.. _arc.objects.operands.unretained-returns: + +Unretained return values +------------------------ + +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. + +.. admonition:: Rationale + + It is common in non-ARC code to not return an autoreleased value; therefore + the convention does not force either path. It is convenient to not be + required to do unnecessary retains and autoreleases; this permits + optimizations such as eliding retain/autoreleases when it can be shown that + the original pointer will still be valid at the point of return. + +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. + +.. _arc.objects.operands.casts: + +Bridged casts +------------- + +A :arc-term:`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 `. + +Using a ``__bridge_retained`` or ``__bridge_transfer`` cast purely to convince +ARC to emit an unbalanced retain or release, respectively, is poor form. + +.. _arc.objects.restrictions: + +Restrictions +============ + +.. _arc.objects.restrictions.conversion: + +Conversion of retainable object pointers +---------------------------------------- + +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 ` may be used to perform these conversions +where necessary. + +.. admonition:: Rationale + + We cannot ensure the correct management of the lifetime of objects if they + may be freely passed around as unmanaged types. The bridged casts are + provided so that the programmer may explicitly describe whether the cast + transfers control into or out of ARC. + +However, the following exceptions apply. + +.. _arc.objects.restrictions.conversion.with.known.semantics: + +Conversion to retainable object pointer type of expressions with known semantics +-------------------------------------------------------------------------------- + +:when-revised:`[beginning Apple 4.0, LLVM 3.1]` +:revision:`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 :arc-term:`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 `, or +* a null pointer constant. + +An expression is :arc-term:`known unretained` if it is an rvalue of :ref:`C +retainable pointer type ` 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 + ` 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 + ` that implies a retained result. + +An expression is :arc-term:`known retained` if it is an rvalue of :ref:`C +retainable pointer type ` 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 ` 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. + +.. admonition:: Rationale + + Bridging casts are annoying. Absent the ability to completely automate the + management of CF objects, however, we are left with relatively poor attempts + to reduce the need for a glut of explicit bridges. Hence these rules. + + We've so far consciously refrained from implicitly turning retained CF + results from function calls into ``__bridge_transfer`` casts. The worry is + that some code patterns --- for example, creating a CF value, assigning it + to an ObjC-typed local, and then calling ``CFRelease`` when done --- are a + bit too likely to be accidentally accepted, leading to mysterious behavior. + +.. _arc.objects.restrictions.conversion-exception-contextual: + +Conversion from retainable object pointer type in certain contexts +------------------------------------------------------------------ + +:when-revised:`[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 `, 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 ` function where the parameter is + not marked with the ``cf_consumed`` attribute. + +.. admonition:: Rationale + + Consumed parameters are left out because ARC would naturally balance them + with a retain, which was judged too treacherous. This is in part because + several of the most common consuming functions are in the ``Release`` family, + and it would be quite unfortunate for explicit releases to be silently + balanced out in this way. + +.. _arc.ownership: + +======================= +Ownership qualification +======================= + +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 :arc-term:`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 :arc-term:`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. + +Except as described under the :ref:`inference rules `, +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. + +.. admonition:: Rationale + + These rules, together with the inference rules, ensure that all objects and + lvalues of retainable object pointer type have an ownership qualifier. The + ability to override an ownership qualifier during template substitution is + required to counteract the :ref:`inference of __strong for template type + arguments `. + +There are four ownership qualifiers: + +* ``__autoreleasing`` +* ``__strong`` +* ``__unsafe_unretained`` +* ``__weak`` + +A type is :arc-term:`nontrivially ownership-qualified` if it is qualified with +``__autoreleasing``, ``__strong``, or ``__weak``. + +.. _arc.ownership.spelling: + +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 + applies to that type; +* if the outermost non-array part of the declarator is a pointer or block + pointer, the qualifier applies to that type; +* otherwise the program is ill-formed. + +If an ownership qualifier appears on the declarator name, or on the declared +object, it is applied to outermost pointer or block-pointer type. + +If an ownership qualifier appears anywhere else in a declarator, it applies to +the type there. + +.. _arc.ownership.spelling.property: + +Property declarations +--------------------- + +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 :arc-term:`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, :when-revised:`[beginning Apple 3.1, LLVM 3.1]` +:revision:`its ownership is implicitly` ``strong``. Prior to this revision, it +was ill-formed to synthesize such a property. + +.. admonition:: Rationale + + Using ``strong`` by default is safe and consistent with the generic ARC rule + about :ref:`inferring ownership `. It is, + unfortunately, inconsistent with the non-ARC rule which states that such + properties are implicitly ``assign``. However, that rule is clearly + untenable in ARC, since it leads to default-unsafe code. The main merit to + banning the properties is to avoid confusion with non-ARC practice, which did + not ultimately strike us as sufficient to justify requiring extra syntax and + (more importantly) forcing novices to understand ownership rules just to + declare a property when the default is so reasonable. Changing the rule away + from non-ARC practice was acceptable because we had conservatively banned the + synthesis in order to give ourselves exactly this leeway. + +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. + +.. _arc.ownership.semantics: + +Semantics +========= + +There are five :arc-term:`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. + +:arc-term:`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. + +:arc-term:`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. + +:arc-term:`Initialization` occurs when an object's lifetime begins, which +depends on its storage duration. Initialization proceeds in two stages: + +#. First, a null pointer is stored into the lvalue using primitive semantics. + This step is skipped if the object is ``__unsafe_unretained``. +#. Second, if the object has an initializer, that expression is evaluated and + then assigned into the object using the usual assignment semantics. + +:arc-term:`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. + +:arc-term:`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. + +.. _arc.ownership.restrictions: + +Restrictions +============ + +.. _arc.ownership.restrictions.weak: + +Weak-unavailable types +---------------------- + +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. + +.. admonition:: Rationale + + Historically, it has been possible for a class to provide its own + reference-count implementation by overriding ``retain``, ``release``, etc. + However, weak references to an object require coordination with its class's + reference-count implementation because, among other things, weak loads and + stores must be atomic with respect to the final release. Therefore, existing + custom reference-count implementations will generally not support weak + references without additional effort. This is unavoidable without breaking + binary compatibility. + +A class may indicate that it does not support weak references by providing the +``objc_arc_weak_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_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. + +.. _arc.ownership.restrictions.autoreleasing: + +Storage duration of ``__autoreleasing`` objects +----------------------------------------------- + +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. + +.. admonition:: Rationale + + Autorelease pools are tied to the current thread and scope by their nature. + While it is possible to have temporary objects whose instance variables are + filled with autoreleased objects, there is no way that ARC can provide any + sort of safety guarantee there. + +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. + +.. _arc.ownership.restrictions.conversion.indirect: + +Conversion of pointers to ownership-qualified types +--------------------------------------------------- + +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 + `. + +The analogous rule applies to ``T&`` and ``U&`` in Objective-C++. + +.. admonition:: Rationale + + These rules provide a reasonable level of type-safety for indirect pointers, + as long as the underlying memory is not deallocated. The conversion to + ``const __unsafe_unretained`` is permitted because the semantics of reads are + equivalent across all these ownership semantics, and that's a very useful and + common pattern. The interconversion with ``void*`` is useful for allocating + memory or otherwise escaping the type system, but use it carefully. + ``reinterpret_cast`` is considered to be an obvious enough sign of taking + responsibility for any problems. + +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 a managed operation is performed on a ``__strong`` +or ``__weak`` object without a guarantee that it contains a primitive zero +bit-pattern, or if the storage for such an object is freed or reused without the +object being first assigned a null pointer. + +.. admonition:: Rationale + + ARC cannot differentiate between an assignment operator which is intended to + "initialize" dynamic memory and one which is intended to potentially replace + a value. Therefore the object's pointer must be valid before letting ARC at + it. Similarly, C and Objective-C do not provide any language hooks for + destroying objects held in dynamic memory, so it is the programmer's + responsibility to avoid leaks (``__strong`` objects) and consistency errors + (``__weak`` objects). + +These requirements are followed automatically in Objective-C++ when creating +objects of retainable object owner type with ``new`` or ``new[]`` and destroying +them with ``delete``, ``delete[]``, or a pseudo-destructor expression. Note +that arrays of nontrivially-ownership-qualified type are not ABI compatible with +non-ARC code because the element type is non-POD: such arrays that are +``new[]``'d in ARC translation units cannot be ``delete[]``'d in non-ARC +translation units and vice-versa. + +.. _arc.ownership.restrictions.pass_by_writeback: + +Passing to an out parameter by writeback +---------------------------------------- + +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 :arc-term:`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 + +.. admonition:: Rationale + + The restriction in the form of the argument serves two purposes. First, it + makes it impossible to pass the address of an array to the argument, which + serves to protect against an otherwise serious risk of mis-inferring an + "array" argument as an out-parameter. Second, it makes it much less likely + that the user will see confusing aliasing problems due to the implementation, + below, where their store to the writeback temporary is not immediately seen + in the original argument variable. + +A pass-by-writeback is evaluated as follows: + +#. The argument is evaluated to yield a pointer ``p`` of type ``U oq *``. +#. 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. +#. Otherwise, a temporary of type ``T __autoreleasing`` is created and + initialized to a null pointer. +#. 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. +#. The address of the temporary is passed as the argument to the actual call. +#. After the call completes, the temporary is loaded with primitive + semantics, and that value is assigned into ``*p``. + +.. admonition:: Rationale + + This is all admittedly convoluted. In an ideal world, we would see that a + local variable is being passed to an out-parameter and retroactively modify + its type to be ``__autoreleasing`` rather than ``__strong``. This would be + remarkably difficult and not always well-founded under the C type system. + However, it was judged unacceptably invasive to require programmers to write + ``__autoreleasing`` on all the variables they intend to use for + out-parameters. This was the least bad solution. + +.. _arc.ownership.restrictions.records: + +Ownership-qualified fields of structs and unions +------------------------------------------------ + +A program is ill-formed if it declares a member of a C struct or union to have +a nontrivially ownership-qualified type. + +.. admonition:: Rationale + + The resulting type would be non-POD in the C++ sense, but C does not give us + very good language tools for managing the lifetime of aggregates, so it is + more convenient to simply forbid them. It is still possible to manage this + with a ``void*`` or an ``__unsafe_unretained`` object. + +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. + +.. admonition:: Rationale + + Unlike in C, we can express all the necessary ARC semantics for + ownership-qualified subobjects as suboperations of the (default) special + member functions for the class. These functions then become non-trivial. + This has the non-obvious result that the class will have a non-trivial copy + constructor and non-trivial destructor; if this would not normally be true + outside of ARC, objects of the type will be passed and returned in an + ABI-incompatible manner. + +.. _arc.ownership.inference: + +Ownership inference +=================== + +.. _arc.ownership.inference.variables: + +Objects +------- + +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. + +.. _arc.ownership.inference.indirect_parameters: + +Indirect parameters +------------------- + +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``. + +.. admonition:: Rationale + + ``__autoreleasing`` exists mostly for this case, the Cocoa convention for + out-parameters. Since a pointer to ``const`` is obviously not an + out-parameter, we instead use a type more useful for passing arrays. If the + user instead intends to pass in a *mutable* array, inferring + ``__autoreleasing`` is the wrong thing to do; this directs some of the + caution in the following rules about writeback. + +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. + +.. admonition:: Rationale + + The convention is very unlikely to be intentional in template code. + +.. _arc.ownership.inference.template.arguments: + +Template arguments +------------------ + +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. + +.. admonition:: Rationale + + ``__strong`` is a useful default for containers (e.g., ``std::vector``), + which would otherwise require explicit qualification. Moreover, unqualified + retainable object pointer types are unlikely to be useful within templates, + since they generally need to have a qualifier applied to the before being + used. + +.. _arc.method-families: + +=============== +Method families +=============== + +An Objective-C method may fall into a :arc-term:`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). + + .. admonition:: 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. + +.. _arc.family.attribute: + +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. + +.. admonition:: Rationale + + The rules codified in this document describe the standard conventions of + Objective-C. However, as these conventions have not heretofore been enforced + by an unforgiving mechanical system, they are only imperfectly kept, + especially as they haven't always even been precisely defined. While it is + possible to define low-level ownership semantics with attributes like + ``ns_returns_retained``, this attribute allows the user to communicate + semantic intent, which is of use both to ARC (which, e.g., treats calls to + ``init`` specially) and the static analyzer. + +.. _arc.family.semantics: + +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 :ref:`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 :ref:`retained objects `. This +can be overridden by annotating the property with ``ns_returns_not_retained`` +attribute. + +.. _arc.family.semantics.init: + +Semantics of ``init`` +--------------------- + +Methods in the ``init`` family implicitly :ref:`consume +` their ``self`` parameter and :ref:`return a +retained object `. 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 :arc-term:`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 `, 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. + +.. _arc.family.semantics.result_type: + +Related result types +-------------------- + +Certain methods are candidates to have :arc-term:`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. + +.. admonition:: Rationale + + ARC's automatic code emission is more prone than most code to signature + errors, i.e. errors where a call was emitted against one method signature, + but the implementing method has an incompatible signature. Having more + precise type information helps drastically lower this risk, as well as + catching a number of latent bugs. + +.. _arc.optimization: + +============ +Optimization +============ + +ARC applies aggressive rules for the optimization of local behavior. These +rules are based around a core assumption of :arc-term:`local balancing`: that +other code will perform retains and releases as necessary (and only as +necessary) for its own safety, and so the optimizer does not need to consider +global properties of the retain and release sequence. For example, if a retain +and release immediately bracket a call, the optimizer can delete the retain and +release on the assumption that the called function will not do a constant +number of unmotivated releases followed by a constant number of "balancing" +retains, such that the local retain/release pair is the only thing preventing +the called function from ending up with a dangling reference. + +The optimizer assumes that when a new value enters local control, e.g. from a +load of a non-local object or as the result of a function call, it is +instaneously valid. Subsequently, a retain and release of a value are +necessary on a computation path only if there is a use of that value before the +release and after any operation which might cause a release of the value +(including indirectly or non-locally), and only if the value is not +demonstrably already retained. + +The complete optimization rules are quite complicated, but it would still be +useful to document them here. + +.. _arc.optimization.precise: + +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 :arc-term:`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. + +.. admonition:: Rationale + + Applying these precise-lifetime semantics strictly would be prohibitive. + Many useful optimizations that might theoretically decrease the lifetime of + an object would be rendered impossible. Essentially, it promises too much. + +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. + +.. admonition:: Rationale + + Nonetheless, it is sometimes useful to be able to force an object to be + released at a precise time, even if that object does not appear to be used. + This is likely to be uncommon enough that the syntactic weight of explicitly + requesting these semantics will not be burdensome, and may even make the code + clearer. + +.. _arc.misc: + +============= +Miscellaneous +============= + +.. _arc.misc.special_methods: + +Special methods +=============== + +.. _arc.misc.special_methods.retain: + +Memory management methods +------------------------- + +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`` + +.. admonition:: Rationale + + ``retainCount`` is banned because ARC robs it of consistent semantics. The + others were banned after weighing three options for how to deal with message + sends: + + **Honoring** them would work out very poorly if a programmer naively or + accidentally tried to incorporate code written for manual retain/release code + into an ARC program. At best, such code would do twice as much work as + necessary; quite frequently, however, ARC and the explicit code would both + try to balance the same retain, leading to crashes. The cost is losing the + ability to perform "unrooted" retains, i.e. retains not logically + corresponding to a strong reference in the object graph. + + **Ignoring** them would badly violate user expectations about their code. + While it *would* make it easier to develop code simultaneously for ARC and + non-ARC, there is very little reason to do so except for certain library + developers. ARC and non-ARC translation units share an execution model and + can seamlessly interoperate. Within a translation unit, a developer who + faithfully maintains their code in non-ARC mode is suffering all the + restrictions of ARC for zero benefit, while a developer who isn't testing the + non-ARC mode is likely to be unpleasantly surprised if they try to go back to + it. + + **Banning** them has the disadvantage of making it very awkward to migrate + existing code to ARC. The best answer to that, given a number of other + changes and restrictions in ARC, is to provide a specialized tool to assist + users in that migration. + + Implementing these methods was banned because they are too integral to the + semantics of ARC; many tricks which worked tolerably under manual reference + counting will misbehave if ARC performs an ephemeral extra retain or two. If + absolutely required, it is still possible to implement them in non-ARC code, + for example in a category; the implementations must obey the :ref:`semantics + ` laid out elsewhere in this document. + +.. _arc.misc.special_methods.dealloc: + +``dealloc`` +----------- + +A program is ill-formed if it contains a message send or ``@selector`` +expression for the selector ``dealloc``. + +.. admonition:: Rationale + + There are no legitimate reasons to call ``dealloc`` directly. + +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. + +.. admonition:: Rationale + + Even though ARC destroys instance variables automatically, there are still + legitimate reasons to write a ``dealloc`` method, such as freeing + non-retainable resources. Failing to call ``[super dealloc]`` in such a + method is nearly always a bug. Sometimes, the object is simply trying to + prevent itself from being destroyed, but ``dealloc`` is really far too late + for the object to be raising such objections. Somewhat more legitimately, an + object may have been pool-allocated and should not be deallocated with + ``free``; for now, this can only be supported with a ``dealloc`` + implementation outside of ARC. Such an implementation must be very careful + to do all the other work that ``NSObject``'s ``dealloc`` would, which is + outside the scope of this document to describe. + +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. + +.. admonition:: Rationale + + The traditional, non-ARC pattern for destroying instance variables is to + destroy them immediately before calling ``[super dealloc]``. Unfortunately, + message sends from the superclass are quite capable of reaching methods in + the subclass, and those methods may well read or write to those instance + variables. Making such message sends from dealloc is generally discouraged, + since the subclass may well rely on other invariants that were broken during + ``dealloc``, but it's not so inescapably dangerous that we felt comfortable + calling it undefined behavior. Therefore we chose to delay destroying the + instance variables to a point at which message sends are clearly disallowed: + the point at which the root class's deallocation routines take over. + + In most code, the difference is not observable. It can, however, be observed + if an instance variable holds a strong reference to an object whose + deallocation will trigger a side-effect which must be carefully ordered with + respect to the destruction of the super class. Such code violates the design + principle that semantically important behavior should be explicit. A simple + fix is to clear the instance variable manually during ``dealloc``; a more + holistic solution is to move semantically important side-effects out of + ``dealloc`` and into a separate teardown phase which can rely on working with + well-formed objects. + +.. _arc.misc.autoreleasepool: + +``@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. + +.. admonition:: Rationale + + Autorelease pools are clearly important for the compiler to reason about, but + it is far too much to expect the compiler to accurately reason about control + dependencies between two calls. It is also very easy to accidentally forget + to drain an autorelease pool when using the manual API, and this can + significantly inflate the process's high-water-mark. The introduction of a + new scope is unfortunate but basically required for sane interaction with the + rest of the language. Not draining the pool during an unwind is apparently + required by the Objective-C exceptions implementation. + +.. _arc.misc.self: + +``self`` +======== + +The ``self`` parameter variable of an Objective-C method is never actually +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. + +To make this safe, for Objective-C instance methods ``self`` is implicitly +``const`` unless the method is in the :ref:`init family +`. Further, ``self`` is **always** implicitly +``const`` within a class method. + +.. admonition:: Rationale + + The cost of retaining ``self`` in all methods was found to be prohibitive, as + it tends to be live across calls, preventing the optimizer from proving that + the retain and release are unnecessary --- for good reason, as it's quite + possible in theory to cause an object to be deallocated during its execution + without this retain and release. Since it's extremely uncommon to actually + do so, even unintentionally, and since there's no natural way for the + programmer to remove this retain/release pair otherwise (as there is for + other parameters by, say, making the variable ``__unsafe_unretained``), we + chose to make this optimizing assumption and shift some amount of risk to the + user. + +.. _arc.misc.enumeration: + +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 +qualified with ``const __strong`` and objects encountered during the +enumeration are not actually retained. + +.. admonition:: Rationale + + This is an optimization made possible because fast enumeration loops promise + to keep the objects retained during enumeration, and the collection itself + cannot be synchronously modified. It can be overridden by explicitly + qualifying the variable with ``__strong``, which will make the variable + mutable again and cause the loop to retain the objects it encounters. + +.. _arc.misc.blocks: + +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 :ref:`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. + +.. _arc.misc.exceptions: + +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". + +.. admonition:: Rationale + + The standard Cocoa convention is that exceptions signal programmer error and + are not intended to be recovered from. Making code exceptions-safe by + default would impose severe runtime and code size penalties on code that + typically does not actually care about exceptions safety. Therefore, + ARC-generated code leaks by default on exceptions, which is just fine if the + process is going to be immediately terminated anyway. Programs which do care + about recovering from exceptions should enable the option. + +In Objective-C++, ``-fobjc-arc-exceptions`` is enabled by default. + +.. admonition:: Rationale + + C++ already introduces pervasive exceptions-cleanup code of the sort that ARC + introduces. C++ programmers who have not already disabled exceptions are + much more likely to actual require exception-safety. + +ARC does end the lifetimes of ``__weak`` objects when an exception terminates +their scope unless exceptions are disabled in the compiler. + +.. admonition:: Rationale + + The consequence of a local ``__weak`` object not being destroyed is very + likely to be corruption of the Objective-C runtime, so we want to be safer + here. Of course, potentially massive leaks are about as likely to take down + the process as this corruption is if the program does try to recover from + exceptions. + +.. _arc.misc.interior: + +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. + +.. admonition:: Rationale + + Rationale: not all memory and resources are managed with reference counts; it + is common for objects to manage private resources in their own, private way. + Typically these resources are completely encapsulated within the object, but + some classes offer their users direct access for efficiency. If ARC is not + aware of methods that return such "interior" pointers, its optimizations can + cause the owning object to be reclaimed too soon. This attribute informs ARC + that it must tread lightly. + + The extension rules are somewhat intentionally vague. The autorelease pool + limit is there to permit a simple implementation to simply retain and + autorelease the receiver. The other limit permits some amount of + optimization. The phrase "derived from" is intended to encompass the results + both of pointer transformations, such as casts and arithmetic, and of loading + from such derived pointers; furthermore, it applies whether or not such + derivations are applied directly in the calling code or by other utility code + (for example, the C library routine ``strchr``). However, the implementation + never need account for uses after a return from the code which calls the + method returning an interior pointer. + +As an exception, no extension is required if the receiver is loaded directly +from a ``__strong`` object with :ref:`precise lifetime semantics +`. + +.. admonition:: Rationale + + Implicit autoreleases carry the risk of significantly inflating memory use, + so it's important to provide users a way of avoiding these autoreleases. + Tying this to precise lifetime semantics is ideal, as for local variables + this requires a very explicit annotation, which allows ARC to trust the user + with good cheer. + +.. _arc.misc.c-retainable: + +C retainable pointer types +========================== + +A type is a :arc-term:`C retainable pointer type`` if it is a pointer to +(possibly qualified) ``void`` or a pointer to a (possibly qualifier) ``struct`` +or ``class`` type. + +.. admonition:: Rationale + + ARC does not manage pointers of CoreFoundation type (or any of the related + families of retainable C pointers which interoperate with Objective-C for + retain/release operation). In fact, ARC does not even know how to + distinguish these types from arbitrary C pointer types. The intent of this + concept is to filter out some obviously non-object types while leaving a hook + for later tightening if a means of exhaustively marking CF types is made + available. + +.. _arc.misc.c-retainable.audit: + +Auditing of C retainable pointer interfaces +------------------------------------------- + +:when-revised:`[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 :arc-term:`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: + +.. code-block:: objc + + #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)``. + +.. admonition:: Rationale + + A significant inconvenience in ARC programming is the necessity of + interacting with APIs based around C retainable pointers. These features are + designed to make it relatively easy for API authors to quickly review and + annotate their interfaces, in turn improving the fidelity of tools such as + the static analyzer and ARC. The single-file restriction on the pragma is + designed to eliminate the risk of accidentally annotating some other header's + interfaces. + +.. _arc.runtime: + +=============== +Runtime support +=============== + +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 `, +:ref:`objc_destroyWeak `, or +:ref:`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. + +.. admonition:: Rationale + + Several of these functions are semantically equivalent to a message send; we + emit calls to C functions instead because: + + * the machine code to do so is significantly smaller, + * it is much easier to recognize the C functions in the ARC optimizer, and + * a sufficient sophisticated runtime may be able to avoid the message send in + common cases. + + Several other of these functions are "fused" operations which can be + described entirely in terms of other operations. We use the fused operations + primarily as a code-size optimization, although in some cases there is also a + real potential for avoiding redundant operations in the runtime. + +.. _arc.runtime.objc_autorelease: + +``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``. + +.. _arc.runtime.objc_autoreleasePoolPop: + +``void objc_autoreleasePoolPop(void *pool);`` +============================================= + +*Precondition:* ``pool`` is the result of a previous call to +:ref:`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``. + +.. _arc.runtime.objc_autoreleasePoolPush: + +``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. + +.. admonition:: Rationale + + While the interface is described as an explicit hierarchy of pools, the rules + allow the implementation to just keep a stack of objects, using the stack + depth as the opaque pool handle. + +.. _arc.runtime.objc_autoreleaseReturnValue: + +``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 +:ref:`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``. + +.. _arc.runtime.objc_copyWeak: + +``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: + +.. code-block:: objc + + 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``. + +.. _arc.runtime.objc_destroyWeak: + +``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: + +.. code-block:: objc + + void objc_destroyWeak(id *object) { + objc_storeWeak(object, nil); + } + +Does not need to be atomic with respect to calls to ``objc_storeWeak`` on +``object``. + +.. _arc.runtime.objc_initWeak: + +``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: + +.. code-block:: objc + + 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``. + +.. _arc.runtime.objc_loadWeak: + +``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: + +.. code-block:: objc + + id objc_loadWeak(id *object) { + return objc_autorelease(objc_loadWeakRetained(object)); + } + +Must be atomic with respect to calls to ``objc_storeWeak`` on ``object``. + +.. admonition:: Rationale + + Loading weak references would be inherently prone to race conditions without + the retain. + +.. _arc.runtime.objc_loadWeakRetained: + +``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``. + +.. _arc.runtime.objc_moveWeak: + +``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 :ref:`objc_copyWeak +`, or it may be left as null. + +Must be atomic with respect to calls to ``objc_storeWeak`` on ``src``. + +.. _arc.runtime.objc_release: + +``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. + +.. _arc.runtime.objc_retain: + +``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``. + +.. _arc.runtime.objc_retainAutorelease: + +``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: + +.. code-block:: objc + + id objc_retainAutorelease(id value) { + return objc_autorelease(objc_retain(value)); + } + +Always returns ``value``. + +.. _arc.runtime.objc_retainAutoreleaseReturnValue: + +``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 +:ref:`objc_autoreleaseReturnValue `. +Equivalent to the following code: + +.. code-block:: objc + + id objc_retainAutoreleaseReturnValue(id value) { + return objc_autoreleaseReturnValue(objc_retain(value)); + } + +Always returns ``value``. + +.. _arc.runtime.objc_retainAutoreleasedReturnValue: + +``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 +:ref:`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 +`. + +Always returns ``value``. + +.. _arc.runtime.objc_retainBlock: + +``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. + +.. _arc.runtime.objc_storeStrong: + +``id 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: + +.. code-block:: objc + + id objc_storeStrong(id *object, id value) { + value = [value retain]; + id oldValue = *object; + *object = value; + [oldValue release]; + return value; + } + +Always returns ``value``. + +.. _arc.runtime.objc_storeWeak: + +``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. + -- 2.7.4