forked from OSchip/llvm-project
1940 lines
85 KiB
HTML
1940 lines
85 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
|
"http://www.w3.org/TR/html4/strict.dtd">
|
|
<html>
|
|
<head>
|
|
<title>Objective-C Automatic Reference Counting (ARC)</title>
|
|
<link type="text/css" rel="stylesheet" href="../menu.css">
|
|
<link type="text/css" rel="stylesheet" href="../content.css">
|
|
<style type="text/css">
|
|
/* Collapse the items in the ToC to the left. */
|
|
div#toc ul {
|
|
padding-left: 0
|
|
}
|
|
|
|
/* Rationales appear in italic. */
|
|
div.rationale {
|
|
font-style: italic
|
|
}
|
|
|
|
div.rationale em {
|
|
font-style: normal
|
|
}
|
|
|
|
div h1 { font-size: 2em; margin: .67em 0 }
|
|
div div h1 { font-size: 1.5em; margin: .75em 0 }
|
|
div div div h1 { font-size: 1.17em; margin: .83em 0 }
|
|
div div div div h1 { margin: 1.12em 0 }
|
|
|
|
span.term { font-style: italic; font-weight: bold }
|
|
</style>
|
|
|
|
<script type="text/javascript">
|
|
/// A little script to recursively build a table of contents.
|
|
function buildTOC(div, toc, ancestry) {
|
|
var children = div.childNodes;
|
|
var len = children.length;
|
|
|
|
var childNumber = 0;
|
|
|
|
var list = null;
|
|
for (var i = 0; i < len; ++i) {
|
|
var child = children[i];
|
|
if (child.nodeName != "DIV") continue;
|
|
if (child.getAttribute("class") == "rationale") continue;
|
|
if (child.id == "toc") continue;
|
|
|
|
// Okay, we're actually going to build a list node.
|
|
if (list === null) list = document.createElement("ul");
|
|
|
|
var childAncestry = ancestry + ++childNumber + ".";
|
|
|
|
var headerNode = child.childNodes[1];
|
|
var title = headerNode.innerHTML;
|
|
headerNode.insertBefore(document.createTextNode(childAncestry + " "),
|
|
headerNode.firstChild);
|
|
|
|
var item = document.createElement("li");
|
|
item.appendChild(document.createTextNode(childAncestry + " "));
|
|
|
|
var anchor = document.createElement("a");
|
|
anchor.href = "#" + child.id;
|
|
anchor.innerHTML = title;
|
|
item.appendChild(anchor);
|
|
|
|
buildTOC(child, item, childAncestry);
|
|
|
|
list.appendChild(item);
|
|
}
|
|
if (list) toc.appendChild(list);
|
|
}
|
|
|
|
function onLoad() {
|
|
var toc = document.getElementById("toc");
|
|
var content = document.getElementById("content");
|
|
buildTOC(content, toc, "");
|
|
}
|
|
window.onload = onLoad;
|
|
|
|
</script>
|
|
</head>
|
|
<body>
|
|
|
|
<!--#include virtual="../menu.html.incl"-->
|
|
|
|
<div id="content">
|
|
<h1>Automatic Reference Counting</h1>
|
|
|
|
<div id="toc">
|
|
</div>
|
|
|
|
<div id="meta">
|
|
<h1>About this document</h1>
|
|
|
|
<div id="meta.purpose">
|
|
<h1>Purpose</h1>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
</div> <!-- meta.purpose -->
|
|
|
|
<div id="meta.background">
|
|
<h1>Background</h1>
|
|
|
|
<p>This document assumes a basic familiarity with C.</p>
|
|
|
|
<p><span class="term">Blocks</span> are a C language extension for
|
|
creating anonymous functions. Users interact with and transfer block
|
|
objects using <span class="term">block pointers</span>, 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 <tt>Block_copy</tt> 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 <tt>Block_release</tt>,
|
|
which decreases the reference count by 1 and destroys the object if
|
|
the count reaches zero and is on the heap.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>Objective-C defines a new type kind, collectively called
|
|
the <span class="term">object pointer types</span>. This kind has two
|
|
notable builtin members, <tt>id</tt> and <tt>Class</tt>; <tt>id</tt>
|
|
is the final supertype of all object pointers. The validity of
|
|
conversions between object pointer types is not checked at runtime.
|
|
Users may define <span class="term">classes</span>; 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 <span class="term">ivars</span>, fields which appear on all
|
|
instances of that class. For every class <i>T</i> there's an
|
|
associated metaclass; it has no fields, its superclass is the
|
|
metaclass of <i>T</i>'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 <tt>Class</tt>.</p>
|
|
|
|
<p>A class declaration (<tt>@interface</tt>) declares a set
|
|
of <span class="term">methods</span>. A method has a return type, a
|
|
list of argument types, and a <span class="term">selector</span>: a
|
|
name like <tt>foo:bar:baz:</tt>, 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 <span class="term">receiver</span>) and a list of formal
|
|
arguments interspersed with the selector, like so:</p>
|
|
|
|
<pre>[receiver foo: fooArg bar: barArg baz: bazArg]</pre>
|
|
|
|
<p>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 <q>expression</q> 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 <tt>super</tt>, 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
|
|
<tt>@interface</tt>, but those defined in a separate
|
|
<tt>@implementation</tt> declaration; however, when compiling a
|
|
call, typechecking is done based on the methods declared in the
|
|
<tt>@interface</tt>.</p>
|
|
|
|
<p>Method declarations may also be grouped into
|
|
<span class="term">protocols</span>, 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.</p>
|
|
|
|
<p><span class="term">Class extensions</span> are collections of ivars
|
|
and methods, designed to allow a class's <tt>@interface</tt> to be
|
|
split across multiple files; however, there is still a primary
|
|
implementation file which must see the <tt>@interface</tt>s of all
|
|
class extensions.
|
|
<span class="term">Categories</span> allow methods (but not ivars) to
|
|
be declared <i>post hoc</i> on an arbitrary class; the methods in the
|
|
category's <tt>@implementation</tt> 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.</p>
|
|
|
|
<p>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: <tt>retain</tt> increases the object's reference count by
|
|
1, whereas <tt>release</tt> decreases it by 1 and calls the instance
|
|
method <tt>dealloc</tt> if the count reaches 0. To simplify certain
|
|
operations, there is also an <span class="term">autorelease
|
|
pool</span>, a thread-local list of objects to call <tt>release</tt>
|
|
on later; an object can be added to this pool by
|
|
calling <tt>autorelease</tt> on it.</p>
|
|
|
|
<p>Block pointers may be converted to type <tt>id</tt>; 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 <tt>retain</tt> by
|
|
adjusting the reference count, not by calling <tt>Block_copy</tt>.</p>
|
|
|
|
</div> <!-- meta.background -->
|
|
|
|
</div> <!-- meta -->
|
|
|
|
<div id="general">
|
|
<h1>General</h1>
|
|
|
|
<p>Automatic Reference Counting implements automatic memory management
|
|
for Objective-C objects and blocks, freeing the programmer from the
|
|
need explicitly insert retains and releases. It does not provide a
|
|
cycle collector; users must explicitly manage lifetime instead.</p>
|
|
|
|
<p>ARC may be explicitly enabled with the compiler
|
|
flag <tt>-fobjc-arc</tt>. It may also be explicitly disabled with the
|
|
compiler flag <tt>-fno-objc-arc</tt>. The last of these two flags
|
|
appearing on the compile line <q>wins</q>.</p>
|
|
|
|
<p>If ARC is enabled, <tt>__has_feature(objc_arc)</tt> will expand to
|
|
1 in the preprocessor. For more information about <tt>__has_feature</tt>,
|
|
see the <a href="LanguageExtensions.html#__has_feature_extension">language
|
|
extensions</a> document.</p>
|
|
|
|
</div>
|
|
|
|
<div id="objects">
|
|
<h1>Retainable object pointers</h1>
|
|
|
|
<p>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 <em>values</em>
|
|
(patterns of bits indicating the location of a pointed-to object), not
|
|
pointer
|
|
<em>objects</em> (locations in memory which store pointer values).
|
|
The rules for objects are covered in the next section.</p>
|
|
|
|
<p>A <span class="term">retainable object pointer</span>
|
|
(or <q>retainable pointer</q>) is a value of
|
|
a <span class="term">retainable object pointer type</span>
|
|
(<q>retainable type</q>). There are three kinds of retainable object
|
|
pointer types:</p>
|
|
<ul>
|
|
<li>block pointers (formed by applying the caret (<tt>^</tt>)
|
|
declarator sigil to a function type)</li>
|
|
<li>Objective-C object pointers (<tt>id</tt>, <tt>Class</tt>, <tt>NSFoo*</tt>, etc.)</li>
|
|
<li>typedefs marked with <tt>__attribute__((NSObject))</tt></li>
|
|
</ul>
|
|
|
|
<p>Other pointer types, such as <tt>int*</tt> and <tt>CFStringRef</tt>,
|
|
are not subject to ARC's semantics and restrictions.</p>
|
|
|
|
<div class="rationale">
|
|
|
|
<p>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:</p>
|
|
|
|
<ul>
|
|
<li>The type system must reliably identify which objects are to be
|
|
managed. An <tt>int*</tt> might be a pointer to a <tt>malloc</tt>'ed
|
|
array, or it might be a 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.</li>
|
|
<li>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.</li>
|
|
<li>There must be reliable conventions for whether and
|
|
when <q>ownership</q> 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.</li>
|
|
</ul>
|
|
</div> <!-- rationale -->
|
|
|
|
<p>The use of <tt>__attribute__((NSObject))</tt> 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 <tt>__typeof</tt> and C++
|
|
template argument substitution.</p>
|
|
|
|
<div class="rationale"><p>Rationale: any compiler operation which
|
|
incidentally strips type <q>sugar</q> from a type will yield a type
|
|
without the attribute, which may result in unexpected
|
|
behavior.</p></div>
|
|
|
|
<div id="objects.retains">
|
|
<h1>Retain count semantics</h1>
|
|
|
|
<p>A retainable object pointer is either a <span class="term">null
|
|
pointer</span> or a pointer to a valid object. Furthermore, if it has
|
|
block pointer type and is not <tt>null</tt> then it must actually be a
|
|
pointer to a block object, and if it has <tt>Class</tt> 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.</p>
|
|
|
|
<p>For ARC's purposes, a valid object is one with <q>well-behaved</q>
|
|
retaining operations. Specifically, the object must be laid out such
|
|
that the Objective-C message send machinery can successfully send it
|
|
the following messages:</p>
|
|
|
|
<ul>
|
|
<li><tt>retain</tt>, taking no arguments and returning a pointer to
|
|
the object.</li>
|
|
<li><tt>release</tt>, taking no arguments and returning <tt>void</tt>.</li>
|
|
<li><tt>autorelease</tt>, taking no arguments and returning a pointer
|
|
to the object.</li>
|
|
</ul>
|
|
|
|
<p>The behavior of these methods is constrained in the following ways.
|
|
The term <span class="term">high-level semantics</span> 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 <tt>retain</tt>, 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.</p>
|
|
|
|
<p>It is undefined behavior if a computation history featuring a send
|
|
of <tt>retain</tt> followed by a send of <tt>release</tt> to the same
|
|
object, with no intervening <tt>release</tt> 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.</p>
|
|
|
|
<p>It is undefined behavior if a computation history features any use
|
|
whatsoever of an object following the completion of a send
|
|
of <tt>release</tt> that is not preceded by a send of <tt>retain</tt>
|
|
to the same object.</p>
|
|
|
|
<p>The behavior of <tt>autorelease</tt> must be equivalent to sending
|
|
<tt>release</tt> when one of the autorelease pools currently in scope
|
|
is popped. It may not throw an exception.</p>
|
|
|
|
<p>When the semantics call for performing one of these operations on a
|
|
retainable object pointer, if that pointer is <tt>null</tt> then the
|
|
effect is a no-op.</p>
|
|
|
|
<p>All of the semantics described in this document are subject to
|
|
additional <a href="#optimization">optimization rules</a> 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.</p>
|
|
|
|
</div> <!-- objects.retains -->
|
|
|
|
<div id="objects.operands">
|
|
<h1>Retainable object pointers as operands and arguments</h1>
|
|
|
|
<p>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:</p>
|
|
<ul>
|
|
<li>loading a retainable pointer from an object with non-weak
|
|
<a href="#ownership">ownership</a>,</li>
|
|
<li>passing a retainable pointer as an argument to a function or
|
|
method, and</li>
|
|
<li>receiving a retainable pointer as the result of a function or
|
|
method call.</li>
|
|
</ul>
|
|
|
|
<div class="rationale"><p>Rationale: while this might seem
|
|
uncontroversial, it is actually unsafe when multiple expressions are
|
|
evaluated in <q>parallel</q>, 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.</p></div>
|
|
|
|
<p>The remainder of this section describes exceptions to these rules,
|
|
how those exceptions are detected, and what those exceptions imply
|
|
semantically.</p>
|
|
|
|
<div id="objects.operands.consumed">
|
|
<h1>Consumed parameters</h1>
|
|
|
|
<p>A function or method parameter of retainable object pointer type
|
|
may be marked as <span class="term">consumed</span>, signifying that
|
|
the callee expects to take ownership of a +1 retain count. This is
|
|
done by adding the <tt>ns_consumed</tt> attribute to the parameter
|
|
declaration, like so:</p>
|
|
|
|
<pre>void foo(__attribute((ns_consumed)) id x);
|
|
- (void) foo: (id) __attribute((ns_consumed)) x;</pre>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>When passing such an argument, ARC retains the argument prior to
|
|
making the call.</p>
|
|
|
|
<p>When receiving such an argument, ARC releases the argument at the
|
|
end of the function, subject to the usual optimizations for local
|
|
values.</p>
|
|
|
|
<div class="rationale"><p>Rationale: this formalizes direct transfers
|
|
of ownership from a caller to a callee. The most common scenario here
|
|
is passing the <tt>self</tt> parameter to <tt>init</tt>, 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.</p></div>
|
|
|
|
<p>The implicit <tt>self</tt> parameter of a method may be marked as
|
|
consumed by adding <tt>__attribute__((ns_consumes_self))</tt> to the
|
|
method declaration. Methods in the <tt>init</tt>
|
|
<a href="#family">family</a> are treated as if they were implicitly
|
|
marked with this attribute.</p>
|
|
|
|
<p>It is undefined behavior if an Objective-C message send to a method
|
|
with <tt>ns_consumed</tt> 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 <tt>ns_consumed</tt> 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 <tt>ns_consumed</tt>
|
|
parameters than the implementation of the called block or function.</p>
|
|
|
|
<div class="rationale"><p>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.</p></div>
|
|
|
|
</div>
|
|
|
|
<div id="objects.operands.retained_returns">
|
|
<h1>Retained return values</h1>
|
|
|
|
<p>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 <tt>ns_returns_retained</tt> attribute to the function or
|
|
method declaration, like so:</p>
|
|
|
|
<pre>id foo(void) __attribute((ns_returns_retained));
|
|
- (id) foo __attribute((ns_returns_retained));</pre>
|
|
|
|
<p>This attribute is part of the type of the function or method.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<div class="rationale"><p>Rationale: this formalizes direct transfers of
|
|
ownership from a callee to a caller. The most common scenario this
|
|
models is the retained return from <tt>init</tt>, <tt>alloc</tt>,
|
|
<tt>new</tt>, and <tt>copy</tt> methods, but there are other cases in
|
|
the frameworks. After optimization there are typically no extra
|
|
retains and releases required.</p></div>
|
|
|
|
<p>Methods in
|
|
the <tt>alloc</tt>, <tt>copy</tt>, <tt>init</tt>, <tt>mutableCopy</tt>,
|
|
and <tt>new</tt> <a href="#family">families</a> are implicitly marked
|
|
<tt>__attribute__((ns_returns_retained))</tt>. This may be suppressed
|
|
by explicitly marking the
|
|
method <tt>__attribute__((ns_returns_not_retained))</tt>.</p>
|
|
</div>
|
|
|
|
<p>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.</p>
|
|
|
|
<div class="rationale"><p>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.</p></div>
|
|
|
|
|
|
<div id="objects.operands.other-returns">
|
|
<h1>Unretained return values</h1>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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 <tt>autorelease</tt>, but callers must not assume that the
|
|
value is actually in the autorelease pool.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<div class="rationale"><p>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.</p></div>
|
|
|
|
<p>A method or function may be marked
|
|
with <tt>__attribute__((ns_returns_autoreleased))</tt> 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.</p>
|
|
</div>
|
|
|
|
<div id="objects.operands.casts">
|
|
<h1>Bridged casts</h1>
|
|
|
|
<p>A <span class="term">bridged cast</span> is a C-style cast
|
|
annotated with one of three keywords:</p>
|
|
|
|
<ul>
|
|
<li><tt>(__bridge T) op</tt> casts the operand to the destination
|
|
type <tt>T</tt>. If <tt>T</tt> is a retainable object pointer type,
|
|
then <tt>op</tt> must have a non-retainable pointer type.
|
|
If <tt>T</tt> is a non-retainable pointer type, then <tt>op</tt> 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.</li>
|
|
|
|
<li><tt>(__bridge_retained T) op</tt> 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.</li>
|
|
|
|
<li><tt>(__bridge_transfer T) op</tt> 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.</li>
|
|
</ul>
|
|
|
|
<p>These casts are required in order to transfer objects in and out of
|
|
ARC control; see the rationale in the section
|
|
on <a href="#objects.restrictions.conversion">conversion of retainable
|
|
object pointers</a>.</p>
|
|
|
|
<p>Using a <tt>__bridge_retained</tt> or <tt>__bridge_transfer</tt>
|
|
cast purely to convince ARC to emit an unbalanced retain or release,
|
|
respectively, is poor form.</p>
|
|
|
|
</div>
|
|
|
|
</div>
|
|
|
|
<div id="objects.restrictions">
|
|
<h1>Restrictions</h1>
|
|
|
|
<div id="objects.restrictions.conversion">
|
|
<h1>Conversion of retainable object pointers</h1>
|
|
|
|
<p>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 <tt>void*</tt>.
|
|
As an exception, cast to <tt>intptr_t</tt> is allowed because such
|
|
casts are not transferring ownership. The <a href="#objects.operands.casts">bridged
|
|
casts</a> may be used to perform these conversions where
|
|
necessary.</p>
|
|
|
|
<div class="rationale"><p>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.</p></div>
|
|
</div>
|
|
|
|
<p>An unbridged cast to a retainable object pointer type of the return
|
|
value of a Objective-C message send which yields a non-retainable
|
|
pointer is treated as a <tt>__bridge_transfer</tt> cast
|
|
if:</p>
|
|
|
|
<ul>
|
|
<li>the method has the <tt>cf_returns_retained</tt> attribute, or if
|
|
not that,</li>
|
|
<li>the method does not have the <tt>cf_returns_not_retained</tt>
|
|
attribute and</li>
|
|
<li>the method's <a href="#family">selector family</a> would imply
|
|
the <tt>ns_returns_retained</tt> attribute on a method which returned
|
|
a retainable object pointer type.</li>
|
|
</ul>
|
|
|
|
<p>Otherwise the cast is treated as a <tt>__bridge</tt> cast.</p>
|
|
|
|
</div>
|
|
|
|
</div>
|
|
|
|
<div id="ownership">
|
|
<h1>Ownership qualification</h1>
|
|
|
|
<p>This section describes the behavior of <em>objects</em> of
|
|
retainable object pointer type; that is, locations in memory which
|
|
store retainable object pointers.</p>
|
|
|
|
<p>A type is a <span class="term">retainable object owner type</span>
|
|
if it is a retainable object pointer type or an array type whose
|
|
element type is a retainable object owner type.</p>
|
|
|
|
<p>An <span class="term">ownership qualifier</span> 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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>Except as described under
|
|
the <a href="#ownership.inference">inference rules</a>, 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.</p>
|
|
|
|
<div class="rationale"><p>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 <a href="#ownership.inference.template_arguments">inference of <tt>__strong</tt> for template type arguments</a>. </p></div>
|
|
|
|
<p>There are four ownership qualifiers:</p>
|
|
|
|
<ul>
|
|
<li><tt>__autoreleasing</tt></li>
|
|
<li><tt>__strong</tt></li>
|
|
<li><tt>__unsafe_unretained</tt></li>
|
|
<li><tt>__weak</tt></li>
|
|
</ul>
|
|
|
|
<p>A type is <span class="term">nontrivially ownership-qualified</span>
|
|
if it is qualified with <tt>__autoreleasing</tt>, <tt>__strong</tt>, or
|
|
<tt>__weak</tt>.</p>
|
|
|
|
<div id="ownership.spelling">
|
|
<h1>Spelling</h1>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>An ownership qualifier may be written anywhere that any other type
|
|
qualifier may be written.</p>
|
|
|
|
<p>If an ownership qualifier appears in
|
|
the <i>declaration-specifiers</i>, the following rules apply:</p>
|
|
|
|
<ul>
|
|
<li>if the type specifier is a retainable object owner type, the
|
|
qualifier applies to that type;</li>
|
|
<li>if the outermost non-array part of the declarator is a pointer or
|
|
block pointer, the qualifier applies to that type;</li>
|
|
<li>otherwise the program is ill-formed.</li>
|
|
</ul>
|
|
|
|
<p>If an ownership qualifier appears on the declarator name, or on the
|
|
declared object, it is applied to outermost pointer or block-pointer
|
|
type.</p>
|
|
|
|
<p>If an ownership qualifier appears anywhere else in a declarator, it
|
|
applies to the type there.</p>
|
|
|
|
<div id="ownership.spelling.property">
|
|
<h1>Property declarations</h1>
|
|
|
|
<p>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 <tt>__autoreleasing</tt>
|
|
ownership.</p>
|
|
|
|
<ul>
|
|
<li><tt>assign</tt> implies <tt>__unsafe_unretained</tt> ownership.</li>
|
|
<li><tt>copy</tt> implies <tt>__strong</tt> ownership, as well as the
|
|
usual behavior of copy semantics on the setter.</li>
|
|
<li><tt>retain</tt> implies <tt>__strong</tt> ownership.</li>
|
|
<li><tt>strong</tt> implies <tt>__strong</tt> ownership.</li>
|
|
<li><tt>unsafe_unretained</tt> implies <tt>__unsafe_unretained</tt>
|
|
ownership.</li>
|
|
<li><tt>weak</tt> implies <tt>__weak</tt> ownership.</li>
|
|
</ul>
|
|
|
|
<p>With the exception of <tt>weak</tt>, these modifiers are available
|
|
in non-ARC modes.</p>
|
|
|
|
<p>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
|
|
<span class="term">associated instance variable</span> is the
|
|
instance variable which is named, possibly implicitly, by the
|
|
<tt>@synthesize</tt> 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.</p>
|
|
|
|
</div> <!-- ownership.spelling.property -->
|
|
|
|
</div> <!-- ownership.spelling -->
|
|
|
|
<div id="ownership.semantics">
|
|
<h1>Semantics</h1>
|
|
|
|
<p>There are five <span class="term">managed operations</span> 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.</p>
|
|
|
|
<p>A load or store with <q>primitive semantics</q> has the same
|
|
semantics as the respective operation would have on an <tt>void*</tt>
|
|
lvalue with the same alignment and non-ownership qualification.</p>
|
|
|
|
<p><span class="term">Reading</span> occurs when performing a
|
|
lvalue-to-rvalue conversion on an object lvalue.</p>
|
|
|
|
<ul>
|
|
<li>For <tt>__weak</tt> 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.</li>
|
|
<li>For all other objects, the lvalue is loaded with primitive
|
|
semantics.</li>
|
|
</ul>
|
|
|
|
<p><span class="term">Assignment</span> occurs when evaluating
|
|
an assignment operator. The semantics vary based on the qualification:</p>
|
|
<ul>
|
|
<li>For <tt>__strong</tt> 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.</li>
|
|
<li>For <tt>__weak</tt> objects, the lvalue is updated to point to the
|
|
new pointee, unless that object is currently undergoing deallocation,
|
|
in which case it 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 pointed-to
|
|
value.</li>
|
|
<li>For <tt>__unsafe_unretained</tt> objects, the new pointee is
|
|
stored into the lvalue using primitive semantics.</li>
|
|
<li>For <tt>__autoreleasing</tt> objects, the new pointee is retained,
|
|
autoreleased, and stored into the lvalue using primitive semantics.</li>
|
|
</ul>
|
|
|
|
<p><span class="term">Initialization</span> occurs when an object's
|
|
lifetime begins, which depends on its storage duration.
|
|
Initialization proceeds in two stages:</p>
|
|
<ol>
|
|
<li>First, a null pointer is stored into the lvalue using primitive
|
|
semantics. This step is skipped if the object
|
|
is <tt>__unsafe_unretained</tt>.</li>
|
|
<li>Second, if the object has an initializer, that expression is
|
|
evaluated and then assigned into the object using the usual assignment
|
|
semantics.</li>
|
|
</ol>
|
|
|
|
<p><span class="term">Destruction</span> 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.</p>
|
|
|
|
<p><span class="term">Moving</span> occurs in specific situations
|
|
where an lvalue is <q>moved from</q>, meaning that its current pointee
|
|
will be used but the object may be left in a different (but still
|
|
valid) state. This arises with <tt>__block</tt> variables and rvalue
|
|
references in C++. For <tt>__strong</tt> 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.</p>
|
|
|
|
</div> <!-- ownership.semantics -->
|
|
|
|
<div id="ownership.restrictions">
|
|
<h1>Restrictions</h1>
|
|
|
|
<div id="ownership.restrictions.weak">
|
|
<h1>Weak-unavailable types</h1>
|
|
|
|
<p>It is explicitly permitted for Objective-C classes to not
|
|
support <tt>__weak</tt> 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 <tt>__weak</tt>
|
|
references.</p>
|
|
|
|
<div class="rationale"><p>Rationale: historically, it has been
|
|
possible for a class to provide its own reference-count implementation
|
|
by overriding <tt>retain</tt>, <tt>release</tt>, 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.</p></div>
|
|
|
|
<p>A class may indicate that it does not support weak references by
|
|
providing the <tt>objc_arc_weak_unavailable</tt> attribute on the
|
|
class's interface declaration. A retainable object pointer type
|
|
is <span class="term">weak-unavailable</span> if is a pointer to an
|
|
(optionally protocol-qualified) Objective-C class <tt>T</tt>
|
|
where <tt>T</tt> or one of its superclasses has
|
|
the <tt>objc_arc_weak_unavailable</tt> attribute. A program is
|
|
ill-formed if it applies the <tt>__weak</tt> ownership qualifier to a
|
|
weak-unavailable type or if the value operand of a weak assignment
|
|
operation has a weak-unavailable type.</p>
|
|
</div> <!-- ownership.restrictions.weak -->
|
|
|
|
<div id="ownership.restrictions.autoreleasing">
|
|
<h1>Storage duration of <tt>__autoreleasing</tt> objects</h1>
|
|
|
|
<p>A program is ill-formed if it declares an <tt>__autoreleasing</tt>
|
|
object of non-automatic storage duration.</p>
|
|
|
|
<div class="rationale"><p>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.</p></div>
|
|
|
|
<p>It is undefined behavior if a non-null pointer is assigned to
|
|
an <tt>__autoreleasing</tt> object while an autorelease pool is in
|
|
scope and then that object is read after the autorelease pool's scope
|
|
is left.</p>
|
|
|
|
</div>
|
|
|
|
<div id="ownership.restrictions.conversion.indirect">
|
|
<h1>Conversion of pointers to ownership-qualified types</h1>
|
|
|
|
<p>A program is ill-formed if an expression of type <tt>T*</tt> is
|
|
converted, explicitly or implicitly, to the type <tt>U*</tt>,
|
|
where <tt>T</tt> and <tt>U</tt> have different ownership
|
|
qualification, unless:</p>
|
|
<ul>
|
|
<li><tt>T</tt> is qualified with <tt>__strong</tt>,
|
|
<tt>__autoreleasing</tt>, or <tt>__unsafe_unretained</tt>, and
|
|
<tt>U</tt> is qualified with both <tt>const</tt> and
|
|
<tt>__unsafe_unretained</tt>; or</li>
|
|
<li>either <tt>T</tt> or <tt>U</tt> is <tt>cv void</tt>, where
|
|
<tt>cv</tt> is an optional sequence of non-ownership qualifiers; or</li>
|
|
<li>the conversion is requested with a <tt>reinterpret_cast</tt> in
|
|
Objective-C++; or</li>
|
|
<li>the conversion is a
|
|
well-formed <a href="#ownership.restrictions.pass_by_writeback">pass-by-writeback</a>.</li>
|
|
</ul>
|
|
|
|
<p>The analogous rule applies to <tt>T&</tt> and <tt>U&</tt> in
|
|
Objective-C++.</p>
|
|
|
|
<div class="rationale"><p>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 <tt>const
|
|
__unsafe_unretained</tt> 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 <tt>void*</tt> is
|
|
useful for allocating memory or otherwise escaping the type system,
|
|
but use it carefully. <tt>reinterpret_cast</tt> is considered to be
|
|
an obvious enough sign of taking responsibility for any
|
|
problems.</p></div>
|
|
|
|
<p>It is undefined behavior to access an ownership-qualified object
|
|
through an lvalue of a differently-qualified type, except that any
|
|
non-<tt>__weak</tt> object may be read through
|
|
an <tt>__unsafe_unretained</tt> lvalue.</p>
|
|
|
|
<p>It is undefined behavior if a managed operation is performed on
|
|
a <tt>__strong</tt> or <tt>__weak</tt> 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.</p>
|
|
|
|
<div class="rationale"><p>Rationale: ARC cannot differentiate between
|
|
an assignment operator which is intended to <q>initialize</q> 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 (<tt>__strong</tt> objects) and
|
|
consistency errors (<tt>__weak</tt> objects).</p>
|
|
|
|
<p>These requirements are followed automatically in Objective-C++ when
|
|
creating objects of retainable object owner type with <tt>new</tt>
|
|
or <tt>new[]</tt> and destroying them with <tt>delete</tt>,
|
|
<tt>delete[]</tt>, 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 <tt>new[]</tt>'d in ARC translation units cannot
|
|
be <tt>delete[]</tt>'d in non-ARC translation units and
|
|
vice-versa.</p></div>
|
|
|
|
</div>
|
|
|
|
<div id="ownership.restrictions.pass_by_writeback">
|
|
<h1>Passing to an out parameter by writeback</h1>
|
|
|
|
<p>If the argument passed to a parameter of type
|
|
<tt>T __autoreleasing *</tt> has type <tt>U oq *</tt>,
|
|
where <tt>oq</tt> is an ownership qualifier, then the argument is a
|
|
candidate for <span class="term">pass-by-writeback</span> if:</p>
|
|
|
|
<ul>
|
|
<li><tt>oq</tt> is <tt>__strong</tt> or <tt>__weak</tt>, and</li>
|
|
<li>it would be legal to initialize a <tt>T __strong *</tt> with
|
|
a <tt>U __strong *</tt>.</li>
|
|
</ul>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>The pass-by-writeback is ill-formed if the argument expression does
|
|
not have a legal form:</p>
|
|
|
|
<ul>
|
|
<li><tt>&var</tt>, where <tt>var</tt> is a scalar variable of
|
|
automatic storage duration with retainable object pointer type</li>
|
|
<li>a conditional expression where the second and third operands are
|
|
both legal forms</li>
|
|
<li>a cast whose operand is a legal form</li>
|
|
<li>a null pointer constant</li>
|
|
</ul>
|
|
|
|
<div class="rationale"><p>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 <q>array</q>
|
|
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.</p></div>
|
|
|
|
<p>A pass-by-writeback is evaluated as follows:</p>
|
|
<ol>
|
|
<li>The argument is evaluated to yield a pointer <tt>p</tt> of
|
|
type <tt>U oq *</tt>.</li>
|
|
<li>If <tt>p</tt> is a null pointer, then a null pointer is passed as
|
|
the argument, and no further work is required for the pass-by-writeback.</li>
|
|
<li>Otherwise, a temporary of type <tt>T __autoreleasing</tt> is
|
|
created and initialized to a null pointer.</li>
|
|
<li>If the argument is not an Objective-C method parameter marked
|
|
<tt>out</tt>, then <tt>*p</tt> is read, and the result is written
|
|
into the temporary with primitive semantics.</li>
|
|
<li>The address of the temporary is passed as the argument to the
|
|
actual call.</li>
|
|
<li>After the call completes, the temporary is loaded with primitive
|
|
semantics, and that value is assigned into <tt>*p</tt>.</li>
|
|
</ol>
|
|
|
|
<div class="rationale"><p>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 <tt>__autoreleasing</tt> rather than <tt>__strong</tt>. 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 <tt>__autoreleasing</tt> on all the variables
|
|
they intend to use for out-parameters. This was the least bad
|
|
solution.</p></div>
|
|
|
|
</div>
|
|
|
|
<div id="ownership.restrictions.records">
|
|
<h1>Ownership-qualified fields of structs and unions</h1>
|
|
|
|
<p>A program is ill-formed if it declares a member of a C struct or
|
|
union to have a nontrivially ownership-qualified type.</p>
|
|
|
|
<div class="rationale"><p>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 <tt>void*</tt> or an <tt>__unsafe_unretained</tt>
|
|
object.</p></div>
|
|
|
|
<p>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++ One Definition Rule to use
|
|
a class outside of ARC that, under ARC, would have an
|
|
ownership-qualified member.</p>
|
|
|
|
<div class="rationale"><p>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
|
|
repercussion that the class will have a non-trivial copy constructor
|
|
and non-trivial destructor; if it wouldn't outside of ARC, this means
|
|
that objects of the type will be passed and returned in an
|
|
ABI-incompatible manner.</p></div>
|
|
|
|
</div>
|
|
|
|
</div>
|
|
|
|
<div id="ownership.inference">
|
|
<h1>Ownership inference</h1>
|
|
|
|
<div id="ownership.inference.variables">
|
|
<h1>Objects</h1>
|
|
|
|
<p>If an object is declared with retainable object owner type, but
|
|
without an explicit ownership qualifier, its type is implicitly
|
|
adjusted to have <tt>__strong</tt> qualification.</p>
|
|
|
|
<p>As a special case, if the object's base type is <tt>Class</tt>
|
|
(possibly protocol-qualified), the type is adjusted to
|
|
have <tt>__unsafe_unretained</tt> qualification instead.</p>
|
|
|
|
</div>
|
|
|
|
<div id="ownership.inference.indirect_parameters">
|
|
<h1>Indirect parameters</h1>
|
|
|
|
<p>If a function or method parameter has type <tt>T*</tt>, where
|
|
<tt>T</tt> is an ownership-unqualified retainable object pointer type,
|
|
then:</p>
|
|
|
|
<ul>
|
|
<li>if <tt>T</tt> is <tt>const</tt>-qualified or <tt>Class</tt>, then
|
|
it is implicitly qualified with <tt>__unsafe_unretained</tt>;</li>
|
|
<li>otherwise, it is implicitly qualified
|
|
with <tt>__autoreleasing</tt>.</li>
|
|
</ul>
|
|
|
|
<div class="rationale"><p>Rationale: <tt>__autoreleasing</tt> exists
|
|
mostly for this case, the Cocoa convention for out-parameters. Since
|
|
a pointer to <tt>const</tt> 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 <em>mutable</em> array, inferring
|
|
<tt>__autoreleasing</tt> is the wrong thing to do; this directs some
|
|
of the caution in the following rules about writeback.</p></div>
|
|
|
|
<p>Such a type written anywhere else would be ill-formed by the
|
|
general rule requiring ownership qualifiers.</p>
|
|
|
|
<p>This rule does not apply in Objective-C++ if a parameter's type is
|
|
dependent in a template pattern and is only <em>instantiated</em> to
|
|
a type which would be a pointer to an unqualified retainable object
|
|
pointer type. Such code is still ill-formed.</p>
|
|
|
|
<div class="rationale"><p>Rationale: the convention is very unlikely
|
|
to be intentional in template code.</p></div>
|
|
|
|
</div> <!-- ownership.inference.indirect_parameters -->
|
|
|
|
<div id="ownership.inference.template_arguments">
|
|
<h1>Template arguments</h1>
|
|
|
|
<p>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 <tt>__strong</tt>
|
|
qualification. This adjustment occurs regardless of whether the
|
|
template argument was deduced or explicitly specified. </p>
|
|
|
|
<div class="rationale"><p>Rationale: <tt>__strong</tt> is a useful default for containers (e.g., <tt>std::vector<id></tt>), 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.</p></div>
|
|
|
|
</div> <!-- ownership.inference.template_arguments -->
|
|
</div> <!-- ownership.inference -->
|
|
</div> <!-- ownership -->
|
|
|
|
|
|
<div id="family">
|
|
<h1>Method families</h1>
|
|
|
|
<p>An Objective-C method may fall into a <span class="term">method
|
|
family</span>, which is a conventional set of behaviors ascribed to it
|
|
by the Cocoa conventions.</p>
|
|
|
|
<p>A method is in a certain method family if:</p>
|
|
<ul>
|
|
<li>it has a <tt>objc_method_family</tt> attribute placing it in that
|
|
family; or if not that,</li>
|
|
<li>it does not have an <tt>objc_method_family</tt> attribute placing
|
|
it in a different or no family, and</li>
|
|
<li>its selector falls into the corresponding selector family, and</li>
|
|
<li>its signature obeys the added restrictions of the method family.</li>
|
|
</ul>
|
|
|
|
<p>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, <tt>_perform:with:</tt> and <tt>performWith:</tt> would fall
|
|
into the <tt>perform</tt> family (if we recognized one),
|
|
but <tt>performing:with</tt> would not.</p>
|
|
|
|
<p>The families and their added restrictions are:</p>
|
|
|
|
<ul>
|
|
<li><tt>alloc</tt> methods must return a retainable object pointer type.</li>
|
|
<li><tt>copy</tt> methods must return a retainable object pointer type.</li>
|
|
<li><tt>mutableCopy</tt> methods must return a retainable object pointer type.</li>
|
|
<li><tt>new</tt> methods must return a retainable object pointer type.</li>
|
|
<li><tt>init</tt> 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 <tt>init</tt> method whose return
|
|
type is neither <tt>id</tt> 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).
|
|
|
|
<div class="rationale"><p>Rationale: there are a fair number of existing
|
|
methods with <tt>init</tt>-like selectors which nonetheless don't
|
|
follow the <tt>init</tt> conventions. Typically these are either
|
|
accidental naming collisions or helper methods called during
|
|
initialization. Because of the peculiar retain/release behavior
|
|
of <tt>init</tt> methods, it's very important not to treat these
|
|
methods as <tt>init</tt> 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 <tt>init</tt> family.</p>
|
|
|
|
<p>Note that a method with an <tt>init</tt>-family selector which
|
|
returns a non-Objective-C type (e.g. <tt>void</tt>) is perfectly
|
|
well-formed; it simply isn't in the <tt>init</tt> family.</p></div>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>A program is ill-formed if a method's declarations,
|
|
implementations, and overrides do not all have the same method
|
|
family.</p>
|
|
|
|
<div id="family.attribute">
|
|
<h1>Explicit method family control</h1>
|
|
|
|
<p>A method may be annotated with the <tt>objc_method_family</tt>
|
|
attribute to precisely control which method family it belongs to. If
|
|
a method in an <tt>@implementation</tt> does not have this attribute,
|
|
but there is a method declared in the corresponding <tt>@interface</tt>
|
|
that does, then the attribute is copied to the declaration in the
|
|
<tt>@implementation</tt>. The attribute is available outside of ARC,
|
|
and may be tested for with the preprocessor query
|
|
<tt>__has_attribute(objc_method_family)</tt>.</p>
|
|
|
|
<p>The attribute is spelled
|
|
<tt>__attribute__((objc_method_family(<i>family</i>)))</tt>.
|
|
If <i>family</i> is <tt>none</tt>, the method has no family, even if
|
|
it would otherwise be considered to have one based on its selector and
|
|
type. Otherwise, <i>family</i> must be one
|
|
of <tt>alloc</tt>, <tt>copy</tt>, <tt>init</tt>,
|
|
<tt>mutableCopy</tt>, or <tt>new</tt>, 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.</p>
|
|
|
|
<div class="rationale"><p>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
|
|
<tt>ns_returns_retained</tt>, this attribute allows the user to
|
|
communicate semantic intent, which of use both to ARC (which, e.g.,
|
|
treats calls to <tt>init</tt> specially) and the static analyzer.</p></div>
|
|
</div>
|
|
|
|
<div id="family.semantics">
|
|
<h1>Semantics of method families</h1>
|
|
|
|
<p>A method's membership in a method family may imply non-standard
|
|
semantics for its parameters and return type.</p>
|
|
|
|
<p>Methods in the <tt>alloc</tt>, <tt>copy</tt>, <tt>mutableCopy</tt>,
|
|
and <tt>new</tt> families — that is, methods in all the
|
|
currently-defined families except <tt>init</tt> — implicitly
|
|
<a href="#objects.operands.retained_returns">return a retained
|
|
object</a> as if they were annotated with
|
|
the <tt>ns_returns_retained</tt> attribute. This can be overridden by
|
|
annotating the method with either of
|
|
the <tt>ns_returns_autoreleased</tt> or
|
|
<tt>ns_returns_not_retained</tt> attributes.</p>
|
|
|
|
<p>Properties also follow same naming rules as methods. This means that
|
|
those in the <tt>alloc</tt>, <tt>copy</tt>, <tt>mutableCopy</tt>,
|
|
and <tt>new</tt> families provide access to
|
|
<a href="#objects.operands.retained_returns">retained objects</a>.
|
|
This can be overridden by annotating the property with
|
|
<tt>ns_returns_not_retained</tt> attribute.</p>
|
|
|
|
<div id="family.semantics.init">
|
|
<h1>Semantics of <tt>init</tt></h1>
|
|
<p>Methods in the <tt>init</tt> family implicitly
|
|
<a href="#objects.operands.consumed">consume</a> their <tt>self</tt>
|
|
parameter and <a href="#objects.operands.retained_returns">return a
|
|
retained object</a>. Neither of these properties can be altered
|
|
through attributes.</p>
|
|
|
|
<p>A call to an <tt>init</tt> method with a receiver that is either
|
|
<tt>self</tt> (possibly parenthesized or casted) or <tt>super</tt> is
|
|
called a <span class="term">delegate init call</span>. It is an error
|
|
for a delegate init call to be made except from an <tt>init</tt>
|
|
method, and excluding blocks within such methods.</p>
|
|
|
|
<p>As an exception to the <a href="misc.self">usual rule</a>, the
|
|
variable <tt>self</tt> is mutable in an <tt>init</tt> method and has
|
|
the usual semantics for a <tt>__strong</tt> variable. However, it is
|
|
undefined behavior and the program is ill-formed, no diagnostic
|
|
required, if an <tt>init</tt> method attempts to use the previous
|
|
value of <tt>self</tt> after the completion of a delegate init call.
|
|
It is conventional, but not required, for an <tt>init</tt> method to
|
|
return <tt>self</tt>.</p>
|
|
|
|
<p>It is undefined behavior for a program to cause two or more calls
|
|
to <tt>init</tt> methods on the same object, except that
|
|
each <tt>init</tt> method invocation may perform at most one delegate
|
|
init call.</p>
|
|
|
|
</div> <!-- family.semantics.init -->
|
|
|
|
<div id="family.semantics.result_type">
|
|
<h1>Related result types</h1>
|
|
|
|
<p>Certain methods are candidates to have <span class="term">related
|
|
result types</span>:</p>
|
|
<ul>
|
|
<li>class methods in the <tt>alloc</tt> and <tt>new</tt> method families</li>
|
|
<li>instance methods in the <tt>init</tt> family</li>
|
|
<li>the instance method <tt>self</tt></li>
|
|
<li>outside of ARC, the instance methods <tt>retain</tt> and <tt>autorelease</tt></li>
|
|
</ul>
|
|
|
|
<p>If the formal result type of such a method is <tt>id</tt> or
|
|
protocol-qualified <tt>id</tt>, 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:</p>
|
|
|
|
<ul>
|
|
<li>if it is a class method, and the receiver is a class
|
|
name <tt>T</tt>, the message send expression has type <tt>T*</tt>;
|
|
otherwise</li>
|
|
<li>if it is an instance method, and the receiver has type <tt>T</tt>,
|
|
the message send expression has type <tt>T</tt>; otherwise</li>
|
|
<li>the message send expression has the normal result type of the
|
|
method.</li>
|
|
</ul>
|
|
|
|
<p>This is a new rule of the Objective-C language and applies outside
|
|
of ARC.</p>
|
|
|
|
<div class="rationale"><p>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 risks, as well as catching
|
|
a number of latent bugs.</p></div>
|
|
|
|
</div> <!-- family.semantics.result_type -->
|
|
</div> <!-- family.semantics -->
|
|
</div> <!-- family -->
|
|
|
|
<div id="optimization">
|
|
<h1>Optimization</h1>
|
|
|
|
<p>ARC applies aggressive rules for the optimization of local
|
|
behavior. These rules are based around a core assumption of
|
|
<span class="term">local balancing</span>: 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 <q>balancing</q> retains, such that
|
|
the local retain/release pair is the only thing preventing the called
|
|
function from ending up with a dangling reference.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>The complete optimization rules are quite complicated, but it would
|
|
still be useful to document them here.</p>
|
|
|
|
<div id="optimization.precise">
|
|
<h1>Precise lifetime semantics</h1>
|
|
|
|
<p>In general, ARC maintains an invariant that a retainable object
|
|
pointer held in a <tt>__strong</tt> object will be retained for the
|
|
full formal lifetime of the object. Objects subject to this invariant
|
|
have <span class="term">precise lifetime semantics</span>.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<div class="rationale"><p>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.</p></div>
|
|
|
|
<p>A local variable of retainable object owner type and automatic
|
|
storage duration may be annotated with the <tt>objc_precise_lifetime</tt>
|
|
attribute to indicate that it should be considered to be an object
|
|
with precise lifetime semantics.</p>
|
|
|
|
<div class="rationale"><p>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.</p></div>
|
|
|
|
</div> <!-- optimization.precise -->
|
|
|
|
</div>
|
|
|
|
<div id="misc">
|
|
<h1>Miscellaneous</h1>
|
|
|
|
<div id="misc.special_methods">
|
|
<h1>Special methods</h1>
|
|
|
|
<div id="misc.special_methods.retain">
|
|
<h1>Memory management methods</h1>
|
|
|
|
<p>A program is ill-formed if it contains a method definition, message
|
|
send, or <tt>@selector</tt> expression for any of the following
|
|
selectors:</p>
|
|
<ul>
|
|
<li><tt>autorelease</tt></li>
|
|
<li><tt>release</tt></li>
|
|
<li><tt>retain</tt></li>
|
|
<li><tt>retainCount</tt></li>
|
|
</ul>
|
|
|
|
<div class="rationale"><p>Rationale: <tt>retainCount</tt> is banned
|
|
because ARC robs it of consistent semantics. The others were banned
|
|
after weighing three options for how to deal with message sends:</p>
|
|
|
|
<p><b>Honoring</b> 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 <q>unrooted</q>
|
|
retains, i.e. retains not logically corresponding to a strong
|
|
reference in the object graph.</p>
|
|
|
|
<p><b>Ignoring</b> them would badly violate user expectations about their
|
|
code. While it <em>would</em> 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.</p>
|
|
|
|
<p><b>Banning</b> 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.</p>
|
|
|
|
<p>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 <a href="#objects.retains">semantics</a>
|
|
laid out elsewhere in this document.</p>
|
|
|
|
</div>
|
|
</div> <!-- misc.special_methods.retain -->
|
|
|
|
<div id="misc.special_methods.dealloc">
|
|
<h1><tt>dealloc</tt></h1>
|
|
|
|
<p>A program is ill-formed if it contains a message send
|
|
or <tt>@selector</tt> expression for the selector <tt>dealloc</tt>.</p>
|
|
|
|
<div class="rationale"><p>Rationale: there are no legitimate reasons
|
|
to call <tt>dealloc</tt> directly.</p></div>
|
|
|
|
<p>A class may provide a method definition for an instance method
|
|
named <tt>dealloc</tt>. This method will be called after the final
|
|
<tt>release</tt> of the object but before it is deallocated or any of
|
|
its instance variables are destroyed. The superclass's implementation
|
|
of <tt>dealloc</tt> will be called automatically when the method
|
|
returns.</p>
|
|
|
|
<div class="rationale"><p>Rationale: even though ARC destroys instance
|
|
variables automatically, there are still legitimate reasons to write
|
|
a <tt>dealloc</tt> method, such as freeing non-retainable resources.
|
|
Failing to call <tt>[super dealloc]</tt> in such a method is nearly
|
|
always a bug. Sometimes, the object is simply trying to prevent
|
|
itself from being destroyed, but <tt>dealloc</tt> 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 <tt>free</tt>; for now, this can only be supported
|
|
with a <tt>dealloc</tt> implementation outside of ARC. Such an
|
|
implementation must be very careful to do all the other work
|
|
that <tt>NSObject</tt>'s <tt>dealloc</tt> would, which is outside the
|
|
scope of this document to describe.</p></div>
|
|
|
|
</div>
|
|
|
|
</div> <!-- misc.special_methods -->
|
|
|
|
<div id="autoreleasepool">
|
|
<h1><tt>@autoreleasepool</tt></h1>
|
|
|
|
<p>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 <tt>@autoreleasepool</tt> followed by
|
|
a <i>compound-statement</i>, 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 <tt>return</tt> or <tt>break</tt>), 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.</p>
|
|
|
|
<p><tt>@autoreleasepool</tt> may be used in non-ARC translation units,
|
|
with equivalent semantics.</p>
|
|
|
|
<p>A program is ill-formed if it refers to the
|
|
<tt>NSAutoreleasePool</tt> class.</p>
|
|
|
|
<div class="rationale"><p>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.</p></div>
|
|
|
|
</div> <!-- autoreleasepool -->
|
|
|
|
<div id="misc.self">
|
|
<h1><tt>self</tt></h1>
|
|
|
|
<p>The <tt>self</tt> 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.</p>
|
|
|
|
<p>To make this safe, for Objective-C instance methods <tt>self</tt> is
|
|
implicitly <tt>const</tt> unless the method is in the <a
|
|
href="#family.semantics.init"><tt>init</tt> family</a>. Further, <tt>self</tt>
|
|
is <b>always</b> implicitly <tt>const</tt> within a class method.</p>
|
|
|
|
<div class="rationale"><p>Rationale: the cost of
|
|
retaining <tt>self</tt> 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 <tt>__unsafe_unretained</tt>), we chose to
|
|
make this optimizing assumption and shift some amount of risk to the
|
|
user.</p></div>
|
|
|
|
</div> <!-- misc.self -->
|
|
|
|
<div id="misc.enumeration">
|
|
<h1>Fast enumeration iteration variables</h1>
|
|
|
|
<p>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 <tt>const __strong</tt> and
|
|
objects encountered during the enumeration are not actually
|
|
retained.</p>
|
|
|
|
<div class="rationale"><p>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 <tt>__strong</tt>, which will make the variable
|
|
mutable again and cause the loop to retain the objects it
|
|
encounters.</p></div>
|
|
|
|
</div>
|
|
|
|
<div id="misc.blocks">
|
|
<h1>Blocks</h1>
|
|
|
|
<p>The implicit <tt>const</tt> 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.</p>
|
|
|
|
<p>The <a href="#ownership.inference">inference</a> rules apply
|
|
equally to <tt>__block</tt> variables, which is a shift in semantics
|
|
from non-ARC, where <tt>__block</tt> variables did not implicitly
|
|
retain during capture.</p>
|
|
|
|
<p><tt>__block</tt> 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.</p>
|
|
|
|
<p>With the exception of retains done as part of initializing
|
|
a <tt>__strong</tt> parameter variable or reading a <tt>__weak</tt>
|
|
variable, whenever these semantics call for retaining a value of
|
|
block-pointer type, it has the effect of a <tt>Block_copy</tt>. The
|
|
optimizer may remove such copies when it sees that the result is
|
|
used only as an argument to a call.</p>
|
|
|
|
</div> <!-- misc.blocks -->
|
|
|
|
<div id="misc.exceptions">
|
|
<h1>Exceptions</h1>
|
|
|
|
<p>By default in Objective C, ARC is not exception-safe for normal
|
|
releases:</p>
|
|
<ul>
|
|
<li>It does not end the lifetime of <tt>__strong</tt> variables when
|
|
their scopes are abnormally terminated by an exception.</li>
|
|
<li>It does not perform releases which would occur at the end of
|
|
a full-expression if that full-expression throws an exception.</li>
|
|
</ul>
|
|
|
|
<p>A program may be compiled with the option
|
|
<tt>-fobjc-arc-exceptions</tt> in order to enable these, or with the
|
|
option <tt>-fno-objc-arc-exceptions</tt> to explicitly disable them,
|
|
with the last such argument <q>winning</q>.</p>
|
|
|
|
<div class="rationale"><p>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.</p></div>
|
|
|
|
<p>In Objective-C++, <tt>-fobjc-arc-exceptions</tt> is enabled by
|
|
default.</p>
|
|
|
|
<div class="rationale"><p>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.</p></div>
|
|
|
|
<p>ARC does end the lifetimes of <tt>__weak</tt> objects when an
|
|
exception terminates their scope unless exceptions are disabled in the
|
|
compiler.</p>
|
|
|
|
<div class="rationale"><p>Rationale: the consequence of a
|
|
local <tt>__weak</tt> 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.</p></div>
|
|
|
|
</div> <!-- misc.exceptions -->
|
|
|
|
<div id="misc.interior">
|
|
<h1>Interior pointers</h1>
|
|
|
|
<p>An Objective-C method returning a non-retainable pointer may be
|
|
annotated with the <tt>objc_returns_inner_pointer</tt> 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:</p>
|
|
|
|
<ul>
|
|
<li>the last use of the returned pointer, or any pointer derived from
|
|
it, in the calling function or</li>
|
|
<li>the autorelease pool is restored to a previous state.</li>
|
|
</ul>
|
|
|
|
<div class="rationale"><p>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 <q>interior</q> pointers, its
|
|
optimizations can cause the owning object to be reclaimed too soon.
|
|
This attribute informs ARC that it must tread lightly.</p>
|
|
|
|
<p>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 <q>derived from</q> 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 <tt>strchr</tt>). However, the
|
|
implementation never need account for uses after a return from the
|
|
code which calls the method returning an interior pointer.</p></div>
|
|
|
|
<p>As an exception, no extension is required if the receiver is loaded
|
|
directly from a <tt>__strong</tt> object
|
|
with <a href="#optimization.precise">precise lifetime semantics</a>.</p>
|
|
|
|
<div class="rationale"><p>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.</p></div>
|
|
|
|
</div> <!-- misc.interior -->
|
|
|
|
</div> <!-- misc -->
|
|
|
|
<div id="runtime">
|
|
<h1>Runtime support</h1>
|
|
|
|
<p>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 <q>Itanium</q> generic ABI for C++.</p>
|
|
|
|
<p>Ownership qualification does not alter the storage requirements for
|
|
objects, except that it is undefined behavior if a <tt>__weak</tt>
|
|
object is inadequately aligned for an object of type <tt>id</tt>. The
|
|
other qualifiers may be used on explicitly under-aligned memory.</p>
|
|
|
|
<p>The runtime tracks <tt>__weak</tt> objects which holds non-null
|
|
values. It is undefined behavior to direct modify a <tt>__weak</tt>
|
|
object which is being tracked by the runtime except through an
|
|
<a href="#runtime.objc_storeWeak"><tt>objc_storeWeak</tt></a>,
|
|
<a href="#runtime.objc_destroyWeak"><tt>objc_destroyWeak</tt></a>,
|
|
or <a href="#runtime.objc_moveWeak"><tt>objc_moveWeak</tt></a>
|
|
call.</p>
|
|
|
|
<p>The runtime must provide a number of new entrypoints which the
|
|
compiler may emit, which are described in the remainder of this
|
|
section.</p>
|
|
|
|
<div class="rationale"><p>Rationale: Several of these functions are
|
|
semantically equivalent to a message send; we emit calls to C
|
|
functions instead because:</p>
|
|
<ul>
|
|
<li>the machine code to do so is significantly smaller,</li>
|
|
<li>it is much easier to recognize the C functions in the ARC optimizer, and</li>
|
|
<li>a sufficient sophisticated runtime may be able to avoid the
|
|
message send in common cases.</li>
|
|
</ul>
|
|
|
|
<p>Several other of these functions are <q>fused</q> 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.</p>
|
|
|
|
</div>
|
|
|
|
<div id="runtime.objc_autorelease">
|
|
<h1><tt>id objc_autorelease(id value);</tt></h1>
|
|
<p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a
|
|
valid object.</p>
|
|
<p>If <tt>value</tt> 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 <tt>autorelease</tt> message.</p>
|
|
<p>Always returns <tt>value</tt>.</p>
|
|
</div> <!-- runtime.objc_autorelease -->
|
|
|
|
<div id="runtime.objc_autoreleasePoolPop">
|
|
<h1><tt>void objc_autoreleasePoolPop(void *pool);</tt></h1>
|
|
<p><i>Precondition:</i> <tt>pool</tt> is the result of a previous call to
|
|
<a href="runtime.objc_autoreleasePoolPush"><tt>objc_autoreleasePoolPush</tt></a>
|
|
on the current thread, where neither <tt>pool</tt> nor any enclosing
|
|
pool have previously been popped.</p>
|
|
<p>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 <tt>pool</tt>.</p>
|
|
</div> <!-- runtime.objc_autoreleasePoolPop -->
|
|
|
|
<div id="runtime.objc_autoreleasePoolPush">
|
|
<h1><tt>void *objc_autoreleasePoolPush(void);</tt></h1>
|
|
<p>Creates a new autorelease pool that is enclosed by the current
|
|
pool, makes that the current pool, and returns an opaque <q>handle</q>
|
|
to it.</p>
|
|
|
|
<div class="rationale"><p>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.</p></div>
|
|
|
|
</div> <!-- runtime.objc_autoreleasePoolPush -->
|
|
|
|
<div id="runtime.objc_autoreleaseReturnValue">
|
|
<h1><tt>id objc_autoreleaseReturnValue(id value);</tt></h1>
|
|
<p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a
|
|
valid object.</p>
|
|
<p>If <tt>value</tt> 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 <a href="runtime.objc_retainAutoreleasedReturnValue"><tt>objc_retainAutoreleasedReturnValue</tt></a>
|
|
for the same object in an enclosing call frame. If this is not
|
|
possible, the object is autoreleased as above.</p>
|
|
<p>Always returns <tt>value</tt>.</p>
|
|
</div> <!-- runtime.objc_autoreleaseReturnValue -->
|
|
|
|
<div id="runtime.objc_copyWeak">
|
|
<h1><tt>void objc_copyWeak(id *dest, id *src);</tt></h1>
|
|
<p><i>Precondition:</i> <tt>src</tt> is a valid pointer which either
|
|
contains a null pointer or has been registered as a <tt>__weak</tt>
|
|
object. <tt>dest</tt> is a valid pointer which has not been
|
|
registered as a <tt>__weak</tt> object.</p>
|
|
<p><tt>dest</tt> is initialized to be equivalent to <tt>src</tt>,
|
|
potentially registering it with the runtime. Equivalent to the
|
|
following code:</p>
|
|
<pre>void objc_copyWeak(id *dest, id *src) {
|
|
objc_release(objc_initWeak(dest, objc_loadWeakRetained(src)));
|
|
}</pre>
|
|
<p>Must be atomic with respect to calls to <tt>objc_storeWeak</tt>
|
|
on <tt>src</tt>.</p>
|
|
</div> <!-- runtime.objc_copyWeak -->
|
|
|
|
<div id="runtime.objc_destroyWeak">
|
|
<h1><tt>void objc_destroyWeak(id *object);</tt></h1>
|
|
<p><i>Precondition:</i> <tt>object</tt> is a valid pointer which
|
|
either contains a null pointer or has been registered as
|
|
a <tt>__weak</tt> object.</p>
|
|
<p><tt>object</tt> is unregistered as a weak object, if it ever was.
|
|
The current value of <tt>object</tt> is left unspecified; otherwise,
|
|
equivalent to the following code:</p>
|
|
<pre>void objc_destroyWeak(id *object) {
|
|
objc_storeWeak(object, nil);
|
|
}</pre>
|
|
<p>Does not need to be atomic with respect to calls
|
|
to <tt>objc_storeWeak</tt> on <tt>object</tt>.</p>
|
|
</div> <!-- runtime.objc_destroyWeak -->
|
|
|
|
<div id="runtime.objc_initWeak">
|
|
<h1><tt>id objc_initWeak(id *object, id value);</tt></h1>
|
|
<p><i>Precondition:</i> <tt>object</tt> is a valid pointer which has
|
|
not been registered as a <tt>__weak</tt> object. <tt>value</tt> is
|
|
null or a pointer to a valid object.</p>
|
|
<p>If <tt>value</tt> is a null pointer or the object to which it
|
|
points has begun deallocation, <tt>object</tt> is zero-initialized.
|
|
Otherwise, <tt>object</tt> is registered as a <tt>__weak</tt> object
|
|
pointing to <tt>value</tt>. Equivalent to the following code:</p>
|
|
<pre>id objc_initWeak(id *object, id value) {
|
|
*object = nil;
|
|
return objc_storeWeak(object, value);
|
|
}</pre>
|
|
<p>Returns the value of <tt>object</tt> after the call.</p>
|
|
<p>Does not need to be atomic with respect to calls
|
|
to <tt>objc_storeWeak</tt> on <tt>object</tt>.</p>
|
|
</div> <!-- runtime.objc_initWeak -->
|
|
|
|
<div id="runtime.objc_loadWeak">
|
|
<h1><tt>id objc_loadWeak(id *object);</tt></h1>
|
|
<p><i>Precondition:</i> <tt>object</tt> is a valid pointer which
|
|
either contains a null pointer or has been registered as
|
|
a <tt>__weak</tt> object.</p>
|
|
<p>If <tt>object</tt> is registered as a <tt>__weak</tt> object, and
|
|
the last value stored into <tt>object</tt> has not yet been
|
|
deallocated or begun deallocation, retains and autoreleases that value
|
|
and returns it. Otherwise returns null. Equivalent to the following
|
|
code:</p>
|
|
<pre>id objc_loadWeak(id *object) {
|
|
return objc_autorelease(objc_loadWeakRetained(object));
|
|
}</pre>
|
|
<p>Must be atomic with respect to calls to <tt>objc_storeWeak</tt>
|
|
on <tt>object</tt>.</p>
|
|
<div class="rationale">Rationale: loading weak references would be
|
|
inherently prone to race conditions without the retain.</div>
|
|
</div> <!-- runtime.objc_loadWeak -->
|
|
|
|
<div id="runtime.objc_loadWeakRetained">
|
|
<h1><tt>id objc_loadWeakRetained(id *object);</tt></h1>
|
|
<p><i>Precondition:</i> <tt>object</tt> is a valid pointer which
|
|
either contains a null pointer or has been registered as
|
|
a <tt>__weak</tt> object.</p>
|
|
<p>If <tt>object</tt> is registered as a <tt>__weak</tt> object, and
|
|
the last value stored into <tt>object</tt> has not yet been
|
|
deallocated or begun deallocation, retains that value and returns it.
|
|
Otherwise returns null.</p>
|
|
<p>Must be atomic with respect to calls to <tt>objc_storeWeak</tt>
|
|
on <tt>object</tt>.</p>
|
|
</div> <!-- runtime.objc_loadWeakRetained -->
|
|
|
|
<div id="runtime.objc_moveWeak">
|
|
<h1><tt>void objc_moveWeak(id *dest, id *src);</tt></h1>
|
|
<p><i>Precondition:</i> <tt>src</tt> is a valid pointer which either
|
|
contains a null pointer or has been registered as a <tt>__weak</tt>
|
|
object. <tt>dest</tt> is a valid pointer which has not been
|
|
registered as a <tt>__weak</tt> object.</p>
|
|
<p><tt>dest</tt> is initialized to be equivalent to <tt>src</tt>,
|
|
potentially registering it with the runtime. <tt>src</tt> may then be
|
|
left in its original state, in which case this call is equivalent
|
|
to <a href="#runtime.objc_copyWeak"><tt>objc_copyWeak</tt></a>, or it
|
|
may be left as null.</p>
|
|
<p>Must be atomic with respect to calls to <tt>objc_storeWeak</tt>
|
|
on <tt>src</tt>.</p>
|
|
</div> <!-- runtime.objc_moveWeak -->
|
|
|
|
<div id="runtime.objc_release">
|
|
<h1><tt>void objc_release(id value);</tt></h1>
|
|
<p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a
|
|
valid object.</p>
|
|
<p>If <tt>value</tt> is null, this call has no effect. Otherwise, it
|
|
performs a release operation exactly as if the object had been sent
|
|
the <tt>release</tt> message.</p>
|
|
</div> <!-- runtime.objc_release -->
|
|
|
|
<div id="runtime.objc_retain">
|
|
<h1><tt>id objc_retain(id value);</tt></h1>
|
|
<p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a
|
|
valid object.</p>
|
|
<p>If <tt>value</tt> is null, this call has no effect. Otherwise, it
|
|
performs a retain operation exactly as if the object had been sent
|
|
the <tt>retain</tt> message.</p>
|
|
<p>Always returns <tt>value</tt>.</p>
|
|
</div> <!-- runtime.objc_retain -->
|
|
|
|
<div id="runtime.objc_retainAutorelease">
|
|
<h1><tt>id objc_retainAutorelease(id value);</tt></h1>
|
|
<p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a
|
|
valid object.</p>
|
|
<p>If <tt>value</tt> is null, this call has no effect. Otherwise, it
|
|
performs a retain operation followed by an autorelease operation.
|
|
Equivalent to the following code:</p>
|
|
<pre>id objc_retainAutorelease(id value) {
|
|
return objc_autorelease(objc_retain(value));
|
|
}</pre>
|
|
<p>Always returns <tt>value</tt>.</p>
|
|
</div> <!-- runtime.objc_retainAutorelease -->
|
|
|
|
<div id="runtime.objc_retainAutoreleaseReturnValue">
|
|
<h1><tt>id objc_retainAutoreleaseReturnValue(id value);</tt></h1>
|
|
<p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a
|
|
valid object.</p>
|
|
<p>If <tt>value</tt> is null, this call has no effect. Otherwise, it
|
|
performs a retain operation followed by the operation described in
|
|
<a href="#runtime.objc_autoreleaseReturnValue"><tt>objc_autoreleaseReturnValue</tt></a>.
|
|
Equivalent to the following code:</p>
|
|
<pre>id objc_retainAutoreleaseReturnValue(id value) {
|
|
return objc_autoreleaseReturnValue(objc_retain(value));
|
|
}</pre>
|
|
<p>Always returns <tt>value</tt>.</p>
|
|
</div> <!-- runtime.objc_retainAutoreleaseReturnValue -->
|
|
|
|
<div id="runtime.objc_retainAutoreleasedReturnValue">
|
|
<h1><tt>id objc_retainAutoreleasedReturnValue(id value);</tt></h1>
|
|
<p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a
|
|
valid object.</p>
|
|
<p>If <tt>value</tt> is null, this call has no effect. Otherwise, it
|
|
attempts to accept a hand off of a retain count from a call to
|
|
<a href="#runtime.objc_autoreleaseReturnValue"><tt>objc_autoreleaseReturnValue</tt></a>
|
|
on <tt>value</tt> in a recently-called function or something it
|
|
calls. If that fails, it performs a retain operation exactly
|
|
like <a href="#runtime.objc_retain"><tt>objc_retain</tt></a>.</p>
|
|
<p>Always returns <tt>value</tt>.</p>
|
|
</div> <!-- runtime.objc_retainAutoreleasedReturnValue -->
|
|
|
|
<div id="runtime.objc_retainBlock">
|
|
<h1><tt>id objc_retainBlock(id value);</tt></h1>
|
|
<p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a
|
|
valid block object.</p>
|
|
<p>If <tt>value</tt> is null, this call has no effect. Otherwise, if
|
|
the block pointed to by <tt>value</tt> 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 <tt>retain</tt> message.</p>
|
|
</div> <!-- runtime.objc_retainBlock -->
|
|
|
|
<div id="runtime.objc_storeStrong">
|
|
<h1><tt>id objc_storeStrong(id *object, id value);</tt></h1>
|
|
<p><i>Precondition:</i> <tt>object</tt> is a valid pointer to
|
|
a <tt>__strong</tt> object which is adequately aligned for a
|
|
pointer. <tt>value</tt> is null or a pointer to a valid object.</p>
|
|
<p>Performs the complete sequence for assigning to a <tt>__strong</tt>
|
|
object of non-block type. Equivalent to the following code:</p>
|
|
<pre>id objc_storeStrong(id *object, id value) {
|
|
value = [value retain];
|
|
id oldValue = *object;
|
|
*object = value;
|
|
[oldValue release];
|
|
return value;
|
|
}</pre>
|
|
<p>Always returns <tt>value</tt>.</p>
|
|
</div> <!-- runtime.objc_storeStrong -->
|
|
|
|
<div id="runtime.objc_storeWeak">
|
|
<h1><tt>id objc_storeWeak(id *object, id value);</tt></h1>
|
|
<p><i>Precondition:</i> <tt>object</tt> is a valid pointer which
|
|
either contains a null pointer or has been registered as
|
|
a <tt>__weak</tt> object. <tt>value</tt> is null or a pointer to a
|
|
valid object.</p>
|
|
<p>If <tt>value</tt> is a null pointer or the object to which it
|
|
points has begun deallocation, <tt>object</tt> is assigned null
|
|
and unregistered as a <tt>__weak</tt> object. Otherwise,
|
|
<tt>object</tt> is registered as a <tt>__weak</tt> object or has its
|
|
registration updated to point to <tt>value</tt>.</p>
|
|
<p>Returns the value of <tt>object</tt> after the call.</p>
|
|
</div> <!-- runtime.objc_storeWeak -->
|
|
|
|
</div> <!-- runtime -->
|
|
</div> <!-- root -->
|
|
</body>
|
|
</html>
|