Benjamin Kramer | 665a8dc | 2012-01-15 15:26:07 +0000 | [diff] [blame] | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" |
| 2 | "http://www.w3.org/TR/html4/strict.dtd"> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 3 | <html> |
| 4 | <head> |
| 5 | <title>Objective-C Automatic Reference Counting (ARC)</title> |
Benjamin Kramer | 665a8dc | 2012-01-15 15:26:07 +0000 | [diff] [blame] | 6 | <link type="text/css" rel="stylesheet" href="../menu.css"> |
| 7 | <link type="text/css" rel="stylesheet" href="../content.css"> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 8 | <style type="text/css"> |
| 9 | /* Collapse the items in the ToC to the left. */ |
| 10 | div#toc ul { |
| 11 | padding-left: 0 |
| 12 | } |
| 13 | |
| 14 | /* Rationales appear in italic. */ |
| 15 | div.rationale { |
| 16 | font-style: italic |
| 17 | } |
| 18 | |
John McCall | f3d08a6 | 2011-06-18 07:31:30 +0000 | [diff] [blame] | 19 | div.rationale em { |
| 20 | font-style: normal |
| 21 | } |
| 22 | |
John McCall | 9da31cb | 2012-03-27 07:42:12 +0000 | [diff] [blame] | 23 | /* Revisions are also italicized. */ |
| 24 | span.revision { |
| 25 | font-style: italic |
| 26 | } |
| 27 | |
| 28 | span.whenRevised { |
| 29 | font-weight: bold; |
| 30 | font-style: normal |
| 31 | } |
| 32 | |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 33 | div h1 { font-size: 2em; margin: .67em 0 } |
| 34 | div div h1 { font-size: 1.5em; margin: .75em 0 } |
| 35 | div div div h1 { font-size: 1.17em; margin: .83em 0 } |
| 36 | div div div div h1 { margin: 1.12em 0 } |
| 37 | |
| 38 | span.term { font-style: italic; font-weight: bold } |
| 39 | </style> |
| 40 | |
Benjamin Kramer | 665a8dc | 2012-01-15 15:26:07 +0000 | [diff] [blame] | 41 | <script type="text/javascript"> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 42 | /// A little script to recursively build a table of contents. |
| 43 | function buildTOC(div, toc, ancestry) { |
| 44 | var children = div.childNodes; |
| 45 | var len = children.length; |
| 46 | |
| 47 | var childNumber = 0; |
| 48 | |
| 49 | var list = null; |
| 50 | for (var i = 0; i < len; ++i) { |
| 51 | var child = children[i]; |
| 52 | if (child.nodeName != "DIV") continue; |
| 53 | if (child.getAttribute("class") == "rationale") continue; |
| 54 | if (child.id == "toc") continue; |
| 55 | |
| 56 | // Okay, we're actually going to build a list node. |
| 57 | if (list === null) list = document.createElement("ul"); |
| 58 | |
| 59 | var childAncestry = ancestry + ++childNumber + "."; |
| 60 | |
| 61 | var headerNode = child.childNodes[1]; |
| 62 | var title = headerNode.innerHTML; |
| 63 | headerNode.insertBefore(document.createTextNode(childAncestry + " "), |
| 64 | headerNode.firstChild); |
| 65 | |
| 66 | var item = document.createElement("li"); |
| 67 | item.appendChild(document.createTextNode(childAncestry + " ")); |
| 68 | |
| 69 | var anchor = document.createElement("a"); |
| 70 | anchor.href = "#" + child.id; |
| 71 | anchor.innerHTML = title; |
| 72 | item.appendChild(anchor); |
| 73 | |
| 74 | buildTOC(child, item, childAncestry); |
| 75 | |
| 76 | list.appendChild(item); |
| 77 | } |
| 78 | if (list) toc.appendChild(list); |
| 79 | } |
| 80 | |
| 81 | function onLoad() { |
| 82 | var toc = document.getElementById("toc"); |
| 83 | var content = document.getElementById("content"); |
| 84 | buildTOC(content, toc, ""); |
| 85 | } |
| 86 | window.onload = onLoad; |
| 87 | |
| 88 | </script> |
| 89 | </head> |
| 90 | <body> |
| 91 | |
| 92 | <!--#include virtual="../menu.html.incl"--> |
| 93 | |
| 94 | <div id="content"> |
| 95 | <h1>Automatic Reference Counting</h1> |
| 96 | |
| 97 | <div id="toc"> |
| 98 | </div> |
| 99 | |
| 100 | <div id="meta"> |
| 101 | <h1>About this document</h1> |
| 102 | |
| 103 | <div id="meta.purpose"> |
| 104 | <h1>Purpose</h1> |
| 105 | |
| 106 | <p>The first and primary purpose of this document is to serve as a |
| 107 | complete technical specification of Automatic Reference Counting. |
| 108 | Given a core Objective-C compiler and runtime, it should be possible |
| 109 | to write a compiler and runtime which implements these new |
| 110 | semantics.</p> |
| 111 | |
| 112 | <p>The secondary purpose is to act as a rationale for why ARC was |
| 113 | designed in this way. This should remain tightly focused on the |
| 114 | technical design and should not stray into marketing speculation.</p> |
| 115 | |
| 116 | </div> <!-- meta.purpose --> |
| 117 | |
| 118 | <div id="meta.background"> |
| 119 | <h1>Background</h1> |
| 120 | |
| 121 | <p>This document assumes a basic familiarity with C.</p> |
| 122 | |
| 123 | <p><span class="term">Blocks</span> are a C language extension for |
| 124 | creating anonymous functions. Users interact with and transfer block |
| 125 | objects using <span class="term">block pointers</span>, which are |
| 126 | represented like a normal pointer. A block may capture values from |
| 127 | local variables; when this occurs, memory must be dynamically |
| 128 | allocated. The initial allocation is done on the stack, but the |
| 129 | runtime provides a <tt>Block_copy</tt> function which, given a block |
| 130 | pointer, either copies the underlying block object to the heap, |
| 131 | setting its reference count to 1 and returning the new block pointer, |
| 132 | or (if the block object is already on the heap) increases its |
| 133 | reference count by 1. The paired function is <tt>Block_release</tt>, |
| 134 | which decreases the reference count by 1 and destroys the object if |
| 135 | the count reaches zero and is on the heap.</p> |
| 136 | |
| 137 | <p>Objective-C is a set of language extensions, significant enough to |
| 138 | be considered a different language. It is a strict superset of C. |
| 139 | The extensions can also be imposed on C++, producing a language called |
| 140 | Objective-C++. The primary feature is a single-inheritance object |
| 141 | system; we briefly describe the modern dialect.</p> |
| 142 | |
| 143 | <p>Objective-C defines a new type kind, collectively called |
| 144 | the <span class="term">object pointer types</span>. This kind has two |
| 145 | notable builtin members, <tt>id</tt> and <tt>Class</tt>; <tt>id</tt> |
| 146 | is the final supertype of all object pointers. The validity of |
| 147 | conversions between object pointer types is not checked at runtime. |
| 148 | Users may define <span class="term">classes</span>; each class is a |
| 149 | type, and the pointer to that type is an object pointer type. A class |
| 150 | may have a superclass; its pointer type is a subtype of its |
| 151 | superclass's pointer type. A class has a set |
| 152 | of <span class="term">ivars</span>, fields which appear on all |
| 153 | instances of that class. For every class <i>T</i> there's an |
| 154 | associated metaclass; it has no fields, its superclass is the |
| 155 | metaclass of <i>T</i>'s superclass, and its metaclass is a global |
| 156 | class. Every class has a global object whose class is the |
| 157 | class's metaclass; metaclasses have no associated type, so pointers to |
| 158 | this object have type <tt>Class</tt>.</p> |
| 159 | |
| 160 | <p>A class declaration (<tt>@interface</tt>) declares a set |
| 161 | of <span class="term">methods</span>. A method has a return type, a |
| 162 | list of argument types, and a <span class="term">selector</span>: a |
| 163 | name like <tt>foo:bar:baz:</tt>, where the number of colons |
| 164 | corresponds to the number of formal arguments. A method may be an |
| 165 | instance method, in which case it can be invoked on objects of the |
| 166 | class, or a class method, in which case it can be invoked on objects |
| 167 | of the metaclass. A method may be invoked by providing an object |
| 168 | (called the <span class="term">receiver</span>) and a list of formal |
| 169 | arguments interspersed with the selector, like so:</p> |
| 170 | |
| 171 | <pre>[receiver foo: fooArg bar: barArg baz: bazArg]</pre> |
| 172 | |
| 173 | <p>This looks in the dynamic class of the receiver for a method with |
| 174 | this name, then in that class's superclass, etc., until it finds |
| 175 | something it can execute. The receiver <q>expression</q> may also be |
| 176 | the name of a class, in which case the actual receiver is the class |
| 177 | object for that class, or (within method definitions) it may |
| 178 | be <tt>super</tt>, in which case the lookup algorithm starts with the |
| 179 | static superclass instead of the dynamic class. The actual methods |
| 180 | dynamically found in a class are not those declared in the |
| 181 | <tt>@interface</tt>, but those defined in a separate |
| 182 | <tt>@implementation</tt> declaration; however, when compiling a |
| 183 | call, typechecking is done based on the methods declared in the |
| 184 | <tt>@interface</tt>.</p> |
| 185 | |
| 186 | <p>Method declarations may also be grouped into |
| 187 | <span class="term">protocols</span>, which are not inherently |
| 188 | associated with any class, but which classes may claim to follow. |
| 189 | Object pointer types may be qualified with additional protocols that |
| 190 | the object is known to support.</p> |
| 191 | |
| 192 | <p><span class="term">Class extensions</span> are collections of ivars |
| 193 | and methods, designed to allow a class's <tt>@interface</tt> to be |
| 194 | split across multiple files; however, there is still a primary |
| 195 | implementation file which must see the <tt>@interface</tt>s of all |
| 196 | class extensions. |
| 197 | <span class="term">Categories</span> allow methods (but not ivars) to |
| 198 | be declared <i>post hoc</i> on an arbitrary class; the methods in the |
| 199 | category's <tt>@implementation</tt> will be dynamically added to that |
| 200 | class's method tables which the category is loaded at runtime, |
| 201 | replacing those methods in case of a collision.</p> |
| 202 | |
| 203 | <p>In the standard environment, objects are allocated on the heap, and |
| 204 | their lifetime is manually managed using a reference count. This is |
| 205 | done using two instance methods which all classes are expected to |
| 206 | implement: <tt>retain</tt> increases the object's reference count by |
| 207 | 1, whereas <tt>release</tt> decreases it by 1 and calls the instance |
| 208 | method <tt>dealloc</tt> if the count reaches 0. To simplify certain |
| 209 | operations, there is also an <span class="term">autorelease |
| 210 | pool</span>, a thread-local list of objects to call <tt>release</tt> |
| 211 | on later; an object can be added to this pool by |
| 212 | calling <tt>autorelease</tt> on it.</p> |
| 213 | |
| 214 | <p>Block pointers may be converted to type <tt>id</tt>; block objects |
| 215 | are laid out in a way that makes them compatible with Objective-C |
| 216 | objects. There is a builtin class that all block objects are |
| 217 | considered to be objects of; this class implements <tt>retain</tt> by |
| 218 | adjusting the reference count, not by calling <tt>Block_copy</tt>.</p> |
| 219 | |
| 220 | </div> <!-- meta.background --> |
| 221 | |
John McCall | 9da31cb | 2012-03-27 07:42:12 +0000 | [diff] [blame] | 222 | <div id="meta.evolution"> |
| 223 | <h1>Evolution</h1> |
| 224 | |
| 225 | <p>ARC is under continual evolution, and this document must be updated |
| 226 | as the language progresses.</p> |
| 227 | |
| 228 | <p>If a change increases the expressiveness of the language, for |
| 229 | example by lifting a restriction or by adding new syntax, the change |
| 230 | will be annotated with a revision marker, like so:</p> |
| 231 | |
| 232 | <blockquote> |
| 233 | ARC applies to Objective-C pointer types, block pointer types, and |
| 234 | <span class="revision"><span class="whenRevised">[beginning Apple |
| 235 | 8.0, LLVM 3.8]</span> BPTRs declared within <code>extern |
| 236 | "BCPL"</code> blocks</span>. |
| 237 | </blockquote> |
| 238 | |
| 239 | <p>For now, it is sensible to version this document by the releases of |
| 240 | its sole implementation (and its host project), clang. |
| 241 | <q>LLVM X.Y</q> refers to an open-source release of clang from the |
| 242 | LLVM project. <q>Apple X.Y</q> refers to an Apple-provided release of |
| 243 | the Apple LLVM Compiler. Other organizations that prepare their own, |
| 244 | separately-versioned clang releases and wish to maintain similar |
| 245 | information in this document should send requests to cfe-dev.</p> |
| 246 | |
| 247 | <p>If a change decreases the expressiveness of the language, for |
| 248 | example by imposing a new restriction, this should be taken as an |
| 249 | oversight in the original specification and something to be avoided |
| 250 | in all versions. Such changes are generally to be avoided.</p> |
| 251 | |
| 252 | </div> <!-- meta.evolution --> |
| 253 | |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 254 | </div> <!-- meta --> |
| 255 | |
| 256 | <div id="general"> |
| 257 | <h1>General</h1> |
| 258 | |
| 259 | <p>Automatic Reference Counting implements automatic memory management |
| 260 | for Objective-C objects and blocks, freeing the programmer from the |
John McCall | 9da31cb | 2012-03-27 07:42:12 +0000 | [diff] [blame] | 261 | need to explicitly insert retains and releases. It does not provide a |
| 262 | cycle collector; users must explicitly manage the lifetime of their |
| 263 | objects, breaking cycles manually or with weak or unsafe |
| 264 | references.</p> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 265 | |
| 266 | <p>ARC may be explicitly enabled with the compiler |
| 267 | flag <tt>-fobjc-arc</tt>. It may also be explicitly disabled with the |
| 268 | compiler flag <tt>-fno-objc-arc</tt>. The last of these two flags |
| 269 | appearing on the compile line <q>wins</q>.</p> |
| 270 | |
| 271 | <p>If ARC is enabled, <tt>__has_feature(objc_arc)</tt> will expand to |
| 272 | 1 in the preprocessor. For more information about <tt>__has_feature</tt>, |
| 273 | see the <a href="LanguageExtensions.html#__has_feature_extension">language |
| 274 | extensions</a> document.</p> |
| 275 | |
John McCall | 9da31cb | 2012-03-27 07:42:12 +0000 | [diff] [blame] | 276 | </div> <!-- general --> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 277 | |
| 278 | <div id="objects"> |
| 279 | <h1>Retainable object pointers</h1> |
| 280 | |
| 281 | <p>This section describes retainable object pointers, their basic |
| 282 | operations, and the restrictions imposed on their use under ARC. Note |
| 283 | in particular that it covers the rules for pointer <em>values</em> |
| 284 | (patterns of bits indicating the location of a pointed-to object), not |
| 285 | pointer |
| 286 | <em>objects</em> (locations in memory which store pointer values). |
| 287 | The rules for objects are covered in the next section.</p> |
| 288 | |
| 289 | <p>A <span class="term">retainable object pointer</span> |
| 290 | (or <q>retainable pointer</q>) is a value of |
| 291 | a <span class="term">retainable object pointer type</span> |
| 292 | (<q>retainable type</q>). There are three kinds of retainable object |
| 293 | pointer types:</p> |
| 294 | <ul> |
| 295 | <li>block pointers (formed by applying the caret (<tt>^</tt>) |
| 296 | declarator sigil to a function type)</li> |
| 297 | <li>Objective-C object pointers (<tt>id</tt>, <tt>Class</tt>, <tt>NSFoo*</tt>, etc.)</li> |
| 298 | <li>typedefs marked with <tt>__attribute__((NSObject))</tt></li> |
| 299 | </ul> |
| 300 | |
| 301 | <p>Other pointer types, such as <tt>int*</tt> and <tt>CFStringRef</tt>, |
| 302 | are not subject to ARC's semantics and restrictions.</p> |
| 303 | |
| 304 | <div class="rationale"> |
| 305 | |
| 306 | <p>Rationale: We are not at liberty to require |
| 307 | all code to be recompiled with ARC; therefore, ARC must interoperate |
| 308 | with Objective-C code which manages retains and releases manually. In |
| 309 | general, there are three requirements in order for a |
| 310 | compiler-supported reference-count system to provide reliable |
| 311 | interoperation:</p> |
| 312 | |
| 313 | <ul> |
| 314 | <li>The type system must reliably identify which objects are to be |
| 315 | managed. An <tt>int*</tt> might be a pointer to a <tt>malloc</tt>'ed |
| 316 | array, or it might be a interior pointer to such an array, or it might |
| 317 | point to some field or local variable. In contrast, values of the |
| 318 | retainable object pointer types are never interior.</li> |
| 319 | <li>The type system must reliably indicate how to |
| 320 | manage objects of a type. This usually means that the type must imply |
| 321 | a procedure for incrementing and decrementing retain counts. |
| 322 | Supporting single-ownership objects requires a lot more explicit |
| 323 | mediation in the language.</li> |
| 324 | <li>There must be reliable conventions for whether and |
| 325 | when <q>ownership</q> is passed between caller and callee, for both |
| 326 | arguments and return values. Objective-C methods follow such a |
| 327 | convention very reliably, at least for system libraries on Mac OS X, |
| 328 | and functions always pass objects at +0. The C-based APIs for Core |
| 329 | Foundation objects, on the other hand, have much more varied transfer |
| 330 | semantics.</li> |
| 331 | </ul> |
| 332 | </div> <!-- rationale --> |
| 333 | |
| 334 | <p>The use of <tt>__attribute__((NSObject))</tt> typedefs is not |
| 335 | recommended. If it's absolutely necessary to use this attribute, be |
| 336 | very explicit about using the typedef, and do not assume that it will |
| 337 | be preserved by language features like <tt>__typeof</tt> and C++ |
| 338 | template argument substitution.</p> |
| 339 | |
| 340 | <div class="rationale"><p>Rationale: any compiler operation which |
| 341 | incidentally strips type <q>sugar</q> from a type will yield a type |
| 342 | without the attribute, which may result in unexpected |
| 343 | behavior.</p></div> |
| 344 | |
| 345 | <div id="objects.retains"> |
| 346 | <h1>Retain count semantics</h1> |
| 347 | |
| 348 | <p>A retainable object pointer is either a <span class="term">null |
| 349 | pointer</span> or a pointer to a valid object. Furthermore, if it has |
| 350 | block pointer type and is not <tt>null</tt> then it must actually be a |
| 351 | pointer to a block object, and if it has <tt>Class</tt> type (possibly |
| 352 | protocol-qualified) then it must actually be a pointer to a class |
| 353 | object. Otherwise ARC does not enforce the Objective-C type system as |
| 354 | long as the implementing methods follow the signature of the static |
| 355 | type. It is undefined behavior if ARC is exposed to an invalid |
| 356 | pointer.</p> |
| 357 | |
| 358 | <p>For ARC's purposes, a valid object is one with <q>well-behaved</q> |
| 359 | retaining operations. Specifically, the object must be laid out such |
| 360 | that the Objective-C message send machinery can successfully send it |
| 361 | the following messages:</p> |
| 362 | |
| 363 | <ul> |
| 364 | <li><tt>retain</tt>, taking no arguments and returning a pointer to |
| 365 | the object.</li> |
| 366 | <li><tt>release</tt>, taking no arguments and returning <tt>void</tt>.</li> |
| 367 | <li><tt>autorelease</tt>, taking no arguments and returning a pointer |
| 368 | to the object.</li> |
| 369 | </ul> |
| 370 | |
| 371 | <p>The behavior of these methods is constrained in the following ways. |
| 372 | The term <span class="term">high-level semantics</span> is an |
| 373 | intentionally vague term; the intent is that programmers must |
| 374 | implement these methods in a way such that the compiler, modifying |
| 375 | code in ways it deems safe according to these constraints, will not |
| 376 | violate their requirements. For example, if the user puts logging |
| 377 | statements in <tt>retain</tt>, they should not be surprised if those |
| 378 | statements are executed more or less often depending on optimization |
| 379 | settings. These constraints are not exhaustive of the optimization |
| 380 | opportunities: values held in local variables are subject to |
| 381 | additional restrictions, described later in this document.</p> |
| 382 | |
| 383 | <p>It is undefined behavior if a computation history featuring a send |
| 384 | of <tt>retain</tt> followed by a send of <tt>release</tt> to the same |
| 385 | object, with no intervening <tt>release</tt> on that object, is not |
| 386 | equivalent under the high-level semantics to a computation |
| 387 | history in which these sends are removed. Note that this implies that |
| 388 | these methods may not raise exceptions.</p> |
| 389 | |
| 390 | <p>It is undefined behavior if a computation history features any use |
| 391 | whatsoever of an object following the completion of a send |
| 392 | of <tt>release</tt> that is not preceded by a send of <tt>retain</tt> |
| 393 | to the same object.</p> |
| 394 | |
| 395 | <p>The behavior of <tt>autorelease</tt> must be equivalent to sending |
| 396 | <tt>release</tt> when one of the autorelease pools currently in scope |
| 397 | is popped. It may not throw an exception.</p> |
| 398 | |
| 399 | <p>When the semantics call for performing one of these operations on a |
| 400 | retainable object pointer, if that pointer is <tt>null</tt> then the |
| 401 | effect is a no-op.</p> |
| 402 | |
| 403 | <p>All of the semantics described in this document are subject to |
| 404 | additional <a href="#optimization">optimization rules</a> which permit |
| 405 | the removal or optimization of operations based on local knowledge of |
| 406 | data flow. The semantics describe the high-level behaviors that the |
| 407 | compiler implements, not an exact sequence of operations that a |
| 408 | program will be compiled into.</p> |
| 409 | |
| 410 | </div> <!-- objects.retains --> |
| 411 | |
| 412 | <div id="objects.operands"> |
| 413 | <h1>Retainable object pointers as operands and arguments</h1> |
| 414 | |
| 415 | <p>In general, ARC does not perform retain or release operations when |
| 416 | simply using a retainable object pointer as an operand within an |
| 417 | expression. This includes:</p> |
| 418 | <ul> |
| 419 | <li>loading a retainable pointer from an object with non-weak |
| 420 | <a href="#ownership">ownership</a>,</li> |
| 421 | <li>passing a retainable pointer as an argument to a function or |
| 422 | method, and</li> |
| 423 | <li>receiving a retainable pointer as the result of a function or |
| 424 | method call.</li> |
| 425 | </ul> |
| 426 | |
| 427 | <div class="rationale"><p>Rationale: while this might seem |
| 428 | uncontroversial, it is actually unsafe when multiple expressions are |
| 429 | evaluated in <q>parallel</q>, as with binary operators and calls, |
| 430 | because (for example) one expression might load from an object while |
| 431 | another writes to it. However, C and C++ already call this undefined |
| 432 | behavior because the evaluations are unsequenced, and ARC simply |
| 433 | exploits that here to avoid needing to retain arguments across a large |
| 434 | number of calls.</p></div> |
| 435 | |
| 436 | <p>The remainder of this section describes exceptions to these rules, |
| 437 | how those exceptions are detected, and what those exceptions imply |
| 438 | semantically.</p> |
| 439 | |
| 440 | <div id="objects.operands.consumed"> |
| 441 | <h1>Consumed parameters</h1> |
| 442 | |
| 443 | <p>A function or method parameter of retainable object pointer type |
| 444 | may be marked as <span class="term">consumed</span>, signifying that |
| 445 | the callee expects to take ownership of a +1 retain count. This is |
| 446 | done by adding the <tt>ns_consumed</tt> attribute to the parameter |
| 447 | declaration, like so:</p> |
| 448 | |
| 449 | <pre>void foo(__attribute((ns_consumed)) id x); |
| 450 | - (void) foo: (id) __attribute((ns_consumed)) x;</pre> |
| 451 | |
| 452 | <p>This attribute is part of the type of the function or method, not |
| 453 | the type of the parameter. It controls only how the argument is |
| 454 | passed and received.</p> |
| 455 | |
| 456 | <p>When passing such an argument, ARC retains the argument prior to |
| 457 | making the call.</p> |
| 458 | |
| 459 | <p>When receiving such an argument, ARC releases the argument at the |
| 460 | end of the function, subject to the usual optimizations for local |
| 461 | values.</p> |
| 462 | |
| 463 | <div class="rationale"><p>Rationale: this formalizes direct transfers |
| 464 | of ownership from a caller to a callee. The most common scenario here |
| 465 | is passing the <tt>self</tt> parameter to <tt>init</tt>, but it is |
| 466 | useful to generalize. Typically, local optimization will remove any |
| 467 | extra retains and releases: on the caller side the retain will be |
| 468 | merged with a +1 source, and on the callee side the release will be |
| 469 | rolled into the initialization of the parameter.</p></div> |
| 470 | |
| 471 | <p>The implicit <tt>self</tt> parameter of a method may be marked as |
| 472 | consumed by adding <tt>__attribute__((ns_consumes_self))</tt> to the |
John McCall | be16b89 | 2011-06-18 08:15:19 +0000 | [diff] [blame] | 473 | method declaration. Methods in the <tt>init</tt> |
| 474 | <a href="#family">family</a> are treated as if they were implicitly |
| 475 | marked with this attribute.</p> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 476 | |
John McCall | be16b89 | 2011-06-18 08:15:19 +0000 | [diff] [blame] | 477 | <p>It is undefined behavior if an Objective-C message send to a method |
| 478 | with <tt>ns_consumed</tt> parameters (other than self) is made with a |
| 479 | null receiver. It is undefined behavior if the method to which an |
| 480 | Objective-C message send statically resolves to has a different set |
| 481 | of <tt>ns_consumed</tt> parameters than the method it dynamically |
| 482 | resolves to. It is undefined behavior if a block or function call is |
| 483 | made through a static type with a different set of <tt>ns_consumed</tt> |
| 484 | parameters than the implementation of the called block or function.</p> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 485 | |
John McCall | be16b89 | 2011-06-18 08:15:19 +0000 | [diff] [blame] | 486 | <div class="rationale"><p>Rationale: consumed parameters with null |
| 487 | receiver are a guaranteed leak. Mismatches with consumed parameters |
| 488 | will cause over-retains or over-releases, depending on the direction. |
| 489 | The rule about function calls is really just an application of the |
| 490 | existing C/C++ rule about calling functions through an incompatible |
| 491 | function type, but it's useful to state it explicitly.</p></div> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 492 | |
John McCall | 9da31cb | 2012-03-27 07:42:12 +0000 | [diff] [blame] | 493 | </div> <!-- objects.operands.consumed --> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 494 | |
John McCall | 9da31cb | 2012-03-27 07:42:12 +0000 | [diff] [blame] | 495 | <div id="objects.operands.retained-returns"> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 496 | <h1>Retained return values</h1> |
| 497 | |
| 498 | <p>A function or method which returns a retainable object pointer type |
| 499 | may be marked as returning a retained value, signifying that the |
| 500 | caller expects to take ownership of a +1 retain count. This is done |
| 501 | by adding the <tt>ns_returns_retained</tt> attribute to the function or |
| 502 | method declaration, like so:</p> |
| 503 | |
| 504 | <pre>id foo(void) __attribute((ns_returns_retained)); |
| 505 | - (id) foo __attribute((ns_returns_retained));</pre> |
| 506 | |
| 507 | <p>This attribute is part of the type of the function or method.</p> |
| 508 | |
| 509 | <p>When returning from such a function or method, ARC retains the |
| 510 | value at the point of evaluation of the return statement, before |
| 511 | leaving all local scopes.</p> |
| 512 | |
| 513 | <p>When receiving a return result from such a function or method, ARC |
| 514 | releases the value at the end of the full-expression it is contained |
| 515 | within, subject to the usual optimizations for local values.</p> |
| 516 | |
| 517 | <div class="rationale"><p>Rationale: this formalizes direct transfers of |
| 518 | ownership from a callee to a caller. The most common scenario this |
| 519 | models is the retained return from <tt>init</tt>, <tt>alloc</tt>, |
| 520 | <tt>new</tt>, and <tt>copy</tt> methods, but there are other cases in |
| 521 | the frameworks. After optimization there are typically no extra |
| 522 | retains and releases required.</p></div> |
| 523 | |
| 524 | <p>Methods in |
| 525 | the <tt>alloc</tt>, <tt>copy</tt>, <tt>init</tt>, <tt>mutableCopy</tt>, |
| 526 | and <tt>new</tt> <a href="#family">families</a> are implicitly marked |
| 527 | <tt>__attribute__((ns_returns_retained))</tt>. This may be suppressed |
| 528 | by explicitly marking the |
| 529 | method <tt>__attribute__((ns_returns_not_retained))</tt>.</p> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 530 | |
John McCall | be16b89 | 2011-06-18 08:15:19 +0000 | [diff] [blame] | 531 | <p>It is undefined behavior if the method to which an Objective-C |
| 532 | message send statically resolves has different retain semantics on its |
| 533 | result from the method it dynamically resolves to. It is undefined |
| 534 | behavior if a block or function call is made through a static type |
| 535 | with different retain semantics on its result from the implementation |
| 536 | of the called block or function.</p> |
| 537 | |
| 538 | <div class="rationale"><p>Rationale: Mismatches with returned results |
| 539 | will cause over-retains or over-releases, depending on the direction. |
| 540 | Again, the rule about function calls is really just an application of |
| 541 | the existing C/C++ rule about calling functions through an |
| 542 | incompatible function type.</p></div> |
| 543 | |
John McCall | 9da31cb | 2012-03-27 07:42:12 +0000 | [diff] [blame] | 544 | </div> <!-- objects.operands.retained-returns --> |
John McCall | be16b89 | 2011-06-18 08:15:19 +0000 | [diff] [blame] | 545 | |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 546 | <div id="objects.operands.other-returns"> |
| 547 | <h1>Unretained return values</h1> |
| 548 | |
| 549 | <p>A method or function which returns a retainable object type but |
| 550 | does not return a retained value must ensure that the object is |
| 551 | still valid across the return boundary.</p> |
| 552 | |
| 553 | <p>When returning from such a function or method, ARC retains the |
| 554 | value at the point of evaluation of the return statement, then leaves |
| 555 | all local scopes, and then balances out the retain while ensuring that |
| 556 | the value lives across the call boundary. In the worst case, this may |
| 557 | involve an <tt>autorelease</tt>, but callers must not assume that the |
| 558 | value is actually in the autorelease pool.</p> |
| 559 | |
| 560 | <p>ARC performs no extra mandatory work on the caller side, although |
| 561 | it may elect to do something to shorten the lifetime of the returned |
| 562 | value.</p> |
| 563 | |
| 564 | <div class="rationale"><p>Rationale: it is common in non-ARC code to not |
| 565 | return an autoreleased value; therefore the convention does not force |
| 566 | either path. It is convenient to not be required to do unnecessary |
| 567 | retains and autoreleases; this permits optimizations such as eliding |
| 568 | retain/autoreleases when it can be shown that the original pointer |
| 569 | will still be valid at the point of return.</p></div> |
| 570 | |
| 571 | <p>A method or function may be marked |
| 572 | with <tt>__attribute__((ns_returns_autoreleased))</tt> to indicate |
| 573 | that it returns a pointer which is guaranteed to be valid at least as |
| 574 | long as the innermost autorelease pool. There are no additional |
| 575 | semantics enforced in the definition of such a method; it merely |
| 576 | enables optimizations in callers.</p> |
John McCall | 9da31cb | 2012-03-27 07:42:12 +0000 | [diff] [blame] | 577 | |
| 578 | </div> <!-- objects.operands.other-returns --> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 579 | |
| 580 | <div id="objects.operands.casts"> |
| 581 | <h1>Bridged casts</h1> |
| 582 | |
| 583 | <p>A <span class="term">bridged cast</span> is a C-style cast |
| 584 | annotated with one of three keywords:</p> |
| 585 | |
| 586 | <ul> |
| 587 | <li><tt>(__bridge T) op</tt> casts the operand to the destination |
| 588 | type <tt>T</tt>. If <tt>T</tt> is a retainable object pointer type, |
| 589 | then <tt>op</tt> must have a non-retainable pointer type. |
| 590 | If <tt>T</tt> is a non-retainable pointer type, then <tt>op</tt> must |
| 591 | have a retainable object pointer type. Otherwise the cast is |
| 592 | ill-formed. There is no transfer of ownership, and ARC inserts |
| 593 | no retain operations.</li> |
| 594 | |
| 595 | <li><tt>(__bridge_retained T) op</tt> casts the operand, which must |
| 596 | have retainable object pointer type, to the destination type, which |
| 597 | must be a non-retainable pointer type. ARC retains the value, subject |
| 598 | to the usual optimizations on local values, and the recipient is |
| 599 | responsible for balancing that +1.</li> |
| 600 | |
| 601 | <li><tt>(__bridge_transfer T) op</tt> casts the operand, which must |
| 602 | have non-retainable pointer type, to the destination type, which must |
| 603 | be a retainable object pointer type. ARC will release the value at |
| 604 | the end of the enclosing full-expression, subject to the usual |
| 605 | optimizations on local values.</li> |
| 606 | </ul> |
| 607 | |
| 608 | <p>These casts are required in order to transfer objects in and out of |
| 609 | ARC control; see the rationale in the section |
| 610 | on <a href="#objects.restrictions.conversion">conversion of retainable |
| 611 | object pointers</a>.</p> |
| 612 | |
| 613 | <p>Using a <tt>__bridge_retained</tt> or <tt>__bridge_transfer</tt> |
| 614 | cast purely to convince ARC to emit an unbalanced retain or release, |
| 615 | respectively, is poor form.</p> |
| 616 | |
John McCall | 9da31cb | 2012-03-27 07:42:12 +0000 | [diff] [blame] | 617 | </div> <!-- objects.operands.casts --> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 618 | |
John McCall | 9da31cb | 2012-03-27 07:42:12 +0000 | [diff] [blame] | 619 | </div> <!-- objects.operands --> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 620 | |
| 621 | <div id="objects.restrictions"> |
| 622 | <h1>Restrictions</h1> |
| 623 | |
| 624 | <div id="objects.restrictions.conversion"> |
| 625 | <h1>Conversion of retainable object pointers</h1> |
| 626 | |
| 627 | <p>In general, a program which attempts to implicitly or explicitly |
| 628 | convert a value of retainable object pointer type to any |
| 629 | non-retainable type, or vice-versa, is ill-formed. For example, an |
Fariborz Jahanian | a26b2e5 | 2011-07-06 21:58:44 +0000 | [diff] [blame] | 630 | Objective-C object pointer shall not be converted to <tt>void*</tt>. |
David Blaikie | 0ff6495 | 2011-11-24 00:37:54 +0000 | [diff] [blame] | 631 | As an exception, cast to <tt>intptr_t</tt> is allowed because such |
Fariborz Jahanian | a26b2e5 | 2011-07-06 21:58:44 +0000 | [diff] [blame] | 632 | casts are not transferring ownership. The <a href="#objects.operands.casts">bridged |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 633 | casts</a> may be used to perform these conversions where |
| 634 | necessary.</p> |
| 635 | |
| 636 | <div class="rationale"><p>Rationale: we cannot ensure the correct |
| 637 | management of the lifetime of objects if they may be freely passed |
| 638 | around as unmanaged types. The bridged casts are provided so that the |
| 639 | programmer may explicitly describe whether the cast transfers control |
| 640 | into or out of ARC.</p></div> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 641 | |
John McCall | 9da31cb | 2012-03-27 07:42:12 +0000 | [diff] [blame] | 642 | <p>However, the following exceptions apply.</p> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 643 | |
John McCall | 9da31cb | 2012-03-27 07:42:12 +0000 | [diff] [blame] | 644 | </div> <!-- objects.restrictions.conversion --> |
| 645 | |
| 646 | <div id="objects.restrictions.conversion-exception-known"> |
| 647 | <h1>Conversion to retainable object pointer type of |
| 648 | expressions with known semantics</h1> |
| 649 | |
| 650 | <p><span class="revision"><span class="whenRevised">[beginning Apple |
| 651 | 4.0, LLVM 3.1]</span> These exceptions have been greatly expanded; |
| 652 | they previously applied only to a much-reduced subset which is |
| 653 | difficult to categorize but which included null pointers, message |
| 654 | sends (under the given rules), and the various global constants.</span></p> |
| 655 | |
| 656 | <p>An unbridged conversion to a retainable object pointer type from a |
| 657 | type other than a retainable object pointer type is ill-formed, as |
| 658 | discussed above, unless the operand of the cast has a syntactic form |
| 659 | which is known retained, known unretained, or known |
| 660 | retain-agnostic.</p> |
| 661 | |
| 662 | <p>An expression is <span class="term">known retain-agnostic</span> if |
| 663 | it is:</p> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 664 | <ul> |
John McCall | 9da31cb | 2012-03-27 07:42:12 +0000 | [diff] [blame] | 665 | <li>an Objective-C string literal,</li> |
| 666 | <li>a load from a <tt>const</tt> system global variable of |
| 667 | <a href="#misc.c-retainable">C retainable pointer type</a>, or</li> |
| 668 | <li>a null pointer constant.</li> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 669 | </ul> |
| 670 | |
John McCall | 9da31cb | 2012-03-27 07:42:12 +0000 | [diff] [blame] | 671 | <p>An expression is <span class="term">known unretained</span> if it |
| 672 | is an rvalue of <a href="#misc.c-retainable">C retainable |
| 673 | pointer type</a> and it is:</p> |
| 674 | <ul> |
| 675 | <li>a direct call to a function, and either that function has the |
| 676 | <tt>cf_returns_not_retained</tt> attribute or it is an |
| 677 | <a href="#misc.c-retainable.audit">audited</a> function that does not |
| 678 | have the <tt>cf_returns_retained</tt> attribute and does not follow |
| 679 | the create/copy naming convention,</li> |
| 680 | <li>a message send, and the declared method either has |
| 681 | the <tt>cf_returns_not_retained</tt> attribute or it has neither |
| 682 | the <tt>cf_returns_retained</tt> attribute nor a |
| 683 | <a href="#family">selector family</a> that implies a retained |
| 684 | result.</li> |
| 685 | </ul> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 686 | |
John McCall | 9da31cb | 2012-03-27 07:42:12 +0000 | [diff] [blame] | 687 | <p>An expression is <span class="term">known retained</span> if it is |
| 688 | an rvalue of <a href="#misc.c-retainable">C retainable pointer type</a> |
| 689 | and it is:</p> |
| 690 | <ul> |
| 691 | <li>a message send, and the declared method either has the |
| 692 | <tt>cf_returns_retained</tt> attribute, or it does not have |
| 693 | the <tt>cf_returns_not_retained</tt> attribute but it does have a |
| 694 | <a href="#family">selector family</a> that implies a retained |
| 695 | result.</li> |
| 696 | </ul> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 697 | |
John McCall | 9da31cb | 2012-03-27 07:42:12 +0000 | [diff] [blame] | 698 | <p>Furthermore:</p> |
| 699 | <ul> |
| 700 | <li>a comma expression is classified according to its right-hand side,</li> |
| 701 | <li>a statement expression is classified according to its result |
| 702 | expression, if it has one,</li> |
| 703 | <li>an lvalue-to-rvalue conversion applied to an Objective-C property |
| 704 | lvalue is classified according to the underlying message send, and</li> |
| 705 | <li>a conditional operator is classified according to its second and |
| 706 | third operands, if they agree in classification, or else the other |
| 707 | if one is known retain-agnostic.</li> |
| 708 | </ul> |
| 709 | |
| 710 | <p>If the cast operand is known retained, the conversion is treated as |
| 711 | a <tt>__bridge_transfer</tt> cast. If the cast operand is known |
| 712 | unretained or known retain-agnostic, the conversion is treated as |
| 713 | a <tt>__bridge</tt> cast.</p> |
| 714 | |
| 715 | <div class="rationale"><p>Rationale: Bridging casts are annoying. |
| 716 | Absent the ability to completely automate the management of CF |
| 717 | objects, however, we are left with relatively poor attempts to reduce |
| 718 | the need for a glut of explicit bridges. Hence these rules.</p> |
| 719 | |
| 720 | <p>We've so far consciously refrained from implicitly turning retained |
| 721 | CF results from function calls into <tt>__bridge_transfer</tt> casts. |
| 722 | The worry is that some code patterns — for example, creating a |
| 723 | CF value, assigning it to an ObjC-typed local, and then |
| 724 | calling <tt>CFRelease</tt> when done — are a bit too likely to |
| 725 | be accidentally accepted, leading to mysterious behavior.</p></div> |
| 726 | |
| 727 | </div> <!-- objects.restrictions.conversion-exception-known --> |
| 728 | |
| 729 | <div id="objects.restrictions.conversion-exception-contextual"> |
| 730 | <h1>Conversion from retainable object pointer type in certain contexts</h1> |
| 731 | |
| 732 | <p><span class="revision"><span class="whenRevised">[beginning Apple |
| 733 | 4.0, LLVM 3.1]</span></span></p> |
| 734 | |
| 735 | <p>If an expression of retainable object pointer type is explicitly |
| 736 | cast to a <a href="#misc.c-retainable">C retainable pointer type</a>, |
| 737 | the program is ill-formed as discussed above unless the result is |
| 738 | immediately used:</p> |
| 739 | |
| 740 | <ul> |
| 741 | <li>to initialize a parameter in an Objective-C message send where the |
| 742 | parameter is not marked with the <tt>cf_consumed</tt> attribute, or</li> |
| 743 | <li>to initialize a parameter in a direct call to |
| 744 | an <a href="#misc.c-retainable.audit">audited</a> function where the |
| 745 | parameter is not marked with the <tt>cf_consumed</tt> attribute.</li> |
| 746 | </ul> |
| 747 | |
| 748 | <div class="rationale"><p>Rationale: Consumed parameters are left out |
| 749 | because ARC would naturally balance them with a retain, which was |
| 750 | judged too treacherous. This is in part because several of the most |
| 751 | common consuming functions are in the <tt>Release</tt> family, and it |
| 752 | would be quite unfortunate for explicit releases to be silently |
| 753 | balanced out in this way.</p></div> |
| 754 | |
| 755 | </div> <!-- objects.restrictions.conversion-exception-contextual --> |
| 756 | |
| 757 | </div> <!-- objects.restrictions --> |
| 758 | |
| 759 | </div> <!-- objects --> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 760 | |
| 761 | <div id="ownership"> |
| 762 | <h1>Ownership qualification</h1> |
| 763 | |
| 764 | <p>This section describes the behavior of <em>objects</em> of |
| 765 | retainable object pointer type; that is, locations in memory which |
| 766 | store retainable object pointers.</p> |
| 767 | |
| 768 | <p>A type is a <span class="term">retainable object owner type</span> |
| 769 | if it is a retainable object pointer type or an array type whose |
| 770 | element type is a retainable object owner type.</p> |
| 771 | |
| 772 | <p>An <span class="term">ownership qualifier</span> is a type |
Douglas Gregor | 4020cae | 2011-06-17 23:16:24 +0000 | [diff] [blame] | 773 | qualifier which applies only to retainable object owner types. An array type is |
| 774 | ownership-qualified according to its element type, and adding an ownership |
| 775 | qualifier to an array type so qualifies its element type.</p> |
| 776 | |
| 777 | <p>A program is ill-formed if it attempts to apply an ownership qualifier |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 778 | to a type which is already ownership-qualified, even if it is the same |
Douglas Gregor | 4020cae | 2011-06-17 23:16:24 +0000 | [diff] [blame] | 779 | qualifier. There is a single exception to this rule: an ownership qualifier |
| 780 | may be applied to a substituted template type parameter, which overrides the |
| 781 | ownership qualifier provided by the template argument.</p> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 782 | |
| 783 | <p>Except as described under |
| 784 | the <a href="#ownership.inference">inference rules</a>, a program is |
| 785 | ill-formed if it attempts to form a pointer or reference type to a |
| 786 | retainable object owner type which lacks an ownership qualifier.</p> |
| 787 | |
| 788 | <div class="rationale"><p>Rationale: these rules, together with the |
| 789 | inference rules, ensure that all objects and lvalues of retainable |
Douglas Gregor | 4020cae | 2011-06-17 23:16:24 +0000 | [diff] [blame] | 790 | 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> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 791 | |
| 792 | <p>There are four ownership qualifiers:</p> |
| 793 | |
| 794 | <ul> |
| 795 | <li><tt>__autoreleasing</tt></li> |
| 796 | <li><tt>__strong</tt></li> |
| 797 | <li><tt>__unsafe_unretained</tt></li> |
| 798 | <li><tt>__weak</tt></li> |
| 799 | </ul> |
| 800 | |
| 801 | <p>A type is <span class="term">nontrivially ownership-qualified</span> |
| 802 | if it is qualified with <tt>__autoreleasing</tt>, <tt>__strong</tt>, or |
| 803 | <tt>__weak</tt>.</p> |
| 804 | |
| 805 | <div id="ownership.spelling"> |
| 806 | <h1>Spelling</h1> |
| 807 | |
| 808 | <p>The names of the ownership qualifiers are reserved for the |
| 809 | implementation. A program may not assume that they are or are not |
| 810 | implemented with macros, or what those macros expand to.</p> |
| 811 | |
| 812 | <p>An ownership qualifier may be written anywhere that any other type |
| 813 | qualifier may be written.</p> |
| 814 | |
| 815 | <p>If an ownership qualifier appears in |
| 816 | the <i>declaration-specifiers</i>, the following rules apply:</p> |
| 817 | |
| 818 | <ul> |
| 819 | <li>if the type specifier is a retainable object owner type, the |
| 820 | qualifier applies to that type;</li> |
| 821 | <li>if the outermost non-array part of the declarator is a pointer or |
| 822 | block pointer, the qualifier applies to that type;</li> |
| 823 | <li>otherwise the program is ill-formed.</li> |
| 824 | </ul> |
| 825 | |
| 826 | <p>If an ownership qualifier appears on the declarator name, or on the |
| 827 | declared object, it is applied to outermost pointer or block-pointer |
| 828 | type.</p> |
| 829 | |
| 830 | <p>If an ownership qualifier appears anywhere else in a declarator, it |
| 831 | applies to the type there.</p> |
| 832 | |
John McCall | 4f26495 | 2011-07-13 23:15:32 +0000 | [diff] [blame] | 833 | <div id="ownership.spelling.property"> |
| 834 | <h1>Property declarations</h1> |
| 835 | |
| 836 | <p>A property of retainable object pointer type may have ownership. |
| 837 | If the property's type is ownership-qualified, then the property has |
| 838 | that ownership. If the property has one of the following modifiers, |
| 839 | then the property has the corresponding ownership. A property is |
| 840 | ill-formed if it has conflicting sources of ownership, or if it has |
| 841 | redundant ownership modifiers, or if it has <tt>__autoreleasing</tt> |
| 842 | ownership.</p> |
| 843 | |
| 844 | <ul> |
| 845 | <li><tt>assign</tt> implies <tt>__unsafe_unretained</tt> ownership.</li> |
| 846 | <li><tt>copy</tt> implies <tt>__strong</tt> ownership, as well as the |
| 847 | usual behavior of copy semantics on the setter.</li> |
| 848 | <li><tt>retain</tt> implies <tt>__strong</tt> ownership.</li> |
| 849 | <li><tt>strong</tt> implies <tt>__strong</tt> ownership.</li> |
| 850 | <li><tt>unsafe_unretained</tt> implies <tt>__unsafe_unretained</tt> |
| 851 | ownership.</li> |
| 852 | <li><tt>weak</tt> implies <tt>__weak</tt> ownership.</li> |
| 853 | </ul> |
| 854 | |
| 855 | <p>With the exception of <tt>weak</tt>, these modifiers are available |
| 856 | in non-ARC modes.</p> |
| 857 | |
| 858 | <p>A property's specified ownership is preserved in its metadata, but |
| 859 | otherwise the meaning is purely conventional unless the property is |
| 860 | synthesized. If a property is synthesized, then the |
| 861 | <span class="term">associated instance variable</span> is the |
| 862 | instance variable which is named, possibly implicitly, by the |
| 863 | <tt>@synthesize</tt> declaration. If the associated instance variable |
| 864 | already exists, then its ownership qualification must equal the |
| 865 | ownership of the property; otherwise, the instance variable is created |
| 866 | with that ownership qualification.</p> |
| 867 | |
John McCall | 9da31cb | 2012-03-27 07:42:12 +0000 | [diff] [blame] | 868 | <p>A property of retainable object pointer type which is synthesized |
| 869 | without a source of ownership has the ownership of its associated |
| 870 | instance variable, if it already exists; otherwise, |
| 871 | <span class="revision"><span class="whenRevised">[beginning Apple 3.1, |
| 872 | LLVM 3.1]</span> its ownership is implicitly <tt>strong</tt></span>. |
| 873 | Prior to this revision, it was ill-formed to synthesize such a |
| 874 | property.</p> |
| 875 | |
| 876 | <div class="rationale"><p>Rationale: using <tt>strong</tt> by default |
| 877 | is safe and consistent with the generic ARC rule about |
| 878 | <a href="#ownership.inference.variables">inferring ownership</a>. It |
| 879 | is, unfortunately, inconsistent with the non-ARC rule which states |
| 880 | that such properties are implicitly <tt>assign</tt>. However, that |
| 881 | rule is clearly untenable in ARC, since it leads to default-unsafe |
| 882 | code. The main merit to banning the properties is to avoid confusion |
| 883 | with non-ARC practice, which did not ultimately strike us as |
| 884 | sufficient to justify requiring extra syntax and (more importantly) |
| 885 | forcing novices to understand ownership rules just to declare a |
| 886 | property when the default is so reasonable. Changing the rule away |
| 887 | from non-ARC practice was acceptable because we had conservatively |
| 888 | banned the synthesis in order to give ourselves exactly this |
| 889 | leeway.</p></div> |
| 890 | |
John McCall | 4f26495 | 2011-07-13 23:15:32 +0000 | [diff] [blame] | 891 | </div> <!-- ownership.spelling.property --> |
| 892 | |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 893 | </div> <!-- ownership.spelling --> |
| 894 | |
| 895 | <div id="ownership.semantics"> |
| 896 | <h1>Semantics</h1> |
| 897 | |
| 898 | <p>There are five <span class="term">managed operations</span> which |
| 899 | may be performed on an object of retainable object pointer type. Each |
| 900 | qualifier specifies different semantics for each of these operations. |
| 901 | It is still undefined behavior to access an object outside of its |
| 902 | lifetime.</p> |
| 903 | |
| 904 | <p>A load or store with <q>primitive semantics</q> has the same |
| 905 | semantics as the respective operation would have on an <tt>void*</tt> |
| 906 | lvalue with the same alignment and non-ownership qualification.</p> |
| 907 | |
| 908 | <p><span class="term">Reading</span> occurs when performing a |
Benjamin Kramer | 665a8dc | 2012-01-15 15:26:07 +0000 | [diff] [blame] | 909 | lvalue-to-rvalue conversion on an object lvalue.</p> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 910 | |
| 911 | <ul> |
| 912 | <li>For <tt>__weak</tt> objects, the current pointee is retained and |
| 913 | then released at the end of the current full-expression. This must |
| 914 | execute atomically with respect to assignments and to the final |
| 915 | release of the pointee.</li> |
| 916 | <li>For all other objects, the lvalue is loaded with primitive |
| 917 | semantics.</li> |
| 918 | </ul> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 919 | |
| 920 | <p><span class="term">Assignment</span> occurs when evaluating |
Benjamin Kramer | 665a8dc | 2012-01-15 15:26:07 +0000 | [diff] [blame] | 921 | an assignment operator. The semantics vary based on the qualification:</p> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 922 | <ul> |
| 923 | <li>For <tt>__strong</tt> objects, the new pointee is first retained; |
| 924 | second, the lvalue is loaded with primitive semantics; third, the new |
| 925 | pointee is stored into the lvalue with primitive semantics; and |
| 926 | finally, the old pointee is released. This is not performed |
| 927 | atomically; external synchronization must be used to make this safe in |
| 928 | the face of concurrent loads and stores.</li> |
| 929 | <li>For <tt>__weak</tt> objects, the lvalue is updated to point to the |
John McCall | 9da31cb | 2012-03-27 07:42:12 +0000 | [diff] [blame] | 930 | new pointee, unless the new pointee is an object currently undergoing |
| 931 | deallocation, in which case the lvalue is updated to a null pointer. |
| 932 | This must execute atomically with respect to other assignments to the |
| 933 | object, to reads from the object, and to the final release of the new |
| 934 | pointee.</li> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 935 | <li>For <tt>__unsafe_unretained</tt> objects, the new pointee is |
| 936 | stored into the lvalue using primitive semantics.</li> |
| 937 | <li>For <tt>__autoreleasing</tt> objects, the new pointee is retained, |
| 938 | autoreleased, and stored into the lvalue using primitive semantics.</li> |
| 939 | </ul> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 940 | |
| 941 | <p><span class="term">Initialization</span> occurs when an object's |
| 942 | lifetime begins, which depends on its storage duration. |
Benjamin Kramer | 665a8dc | 2012-01-15 15:26:07 +0000 | [diff] [blame] | 943 | Initialization proceeds in two stages:</p> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 944 | <ol> |
| 945 | <li>First, a null pointer is stored into the lvalue using primitive |
| 946 | semantics. This step is skipped if the object |
| 947 | is <tt>__unsafe_unretained</tt>.</li> |
| 948 | <li>Second, if the object has an initializer, that expression is |
| 949 | evaluated and then assigned into the object using the usual assignment |
| 950 | semantics.</li> |
| 951 | </ol> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 952 | |
| 953 | <p><span class="term">Destruction</span> occurs when an object's |
| 954 | lifetime ends. In all cases it is semantically equivalent to |
| 955 | assigning a null pointer to the object, with the proviso that of |
| 956 | course the object cannot be legally read after the object's lifetime |
| 957 | ends.</p> |
| 958 | |
| 959 | <p><span class="term">Moving</span> occurs in specific situations |
| 960 | where an lvalue is <q>moved from</q>, meaning that its current pointee |
| 961 | will be used but the object may be left in a different (but still |
| 962 | valid) state. This arises with <tt>__block</tt> variables and rvalue |
| 963 | references in C++. For <tt>__strong</tt> lvalues, moving is equivalent |
| 964 | to loading the lvalue with primitive semantics, writing a null pointer |
| 965 | to it with primitive semantics, and then releasing the result of the |
| 966 | load at the end of the current full-expression. For all other |
| 967 | lvalues, moving is equivalent to reading the object.</p> |
| 968 | |
| 969 | </div> <!-- ownership.semantics --> |
| 970 | |
| 971 | <div id="ownership.restrictions"> |
| 972 | <h1>Restrictions</h1> |
| 973 | |
John McCall | 2fad783 | 2011-07-07 00:03:42 +0000 | [diff] [blame] | 974 | <div id="ownership.restrictions.weak"> |
| 975 | <h1>Weak-unavailable types</h1> |
| 976 | |
| 977 | <p>It is explicitly permitted for Objective-C classes to not |
| 978 | support <tt>__weak</tt> references. It is undefined behavior to |
| 979 | perform an operation with weak assignment semantics with a pointer to |
| 980 | an Objective-C object whose class does not support <tt>__weak</tt> |
| 981 | references.</p> |
| 982 | |
| 983 | <div class="rationale"><p>Rationale: historically, it has been |
| 984 | possible for a class to provide its own reference-count implementation |
| 985 | by overriding <tt>retain</tt>, <tt>release</tt>, etc. However, weak |
| 986 | references to an object require coordination with its class's |
| 987 | reference-count implementation because, among other things, weak loads |
| 988 | and stores must be atomic with respect to the final release. |
| 989 | Therefore, existing custom reference-count implementations will |
| 990 | generally not support weak references without additional effort. This |
| 991 | is unavoidable without breaking binary compatibility.</p></div> |
| 992 | |
| 993 | <p>A class may indicate that it does not support weak references by |
| 994 | providing the <tt>objc_arc_weak_unavailable</tt> attribute on the |
| 995 | class's interface declaration. A retainable object pointer type |
| 996 | is <span class="term">weak-unavailable</span> if is a pointer to an |
| 997 | (optionally protocol-qualified) Objective-C class <tt>T</tt> |
| 998 | where <tt>T</tt> or one of its superclasses has |
| 999 | the <tt>objc_arc_weak_unavailable</tt> attribute. A program is |
| 1000 | ill-formed if it applies the <tt>__weak</tt> ownership qualifier to a |
| 1001 | weak-unavailable type or if the value operand of a weak assignment |
| 1002 | operation has a weak-unavailable type.</p> |
| 1003 | </div> <!-- ownership.restrictions.weak --> |
| 1004 | |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1005 | <div id="ownership.restrictions.autoreleasing"> |
John McCall | 2fad783 | 2011-07-07 00:03:42 +0000 | [diff] [blame] | 1006 | <h1>Storage duration of <tt>__autoreleasing</tt> objects</h1> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1007 | |
| 1008 | <p>A program is ill-formed if it declares an <tt>__autoreleasing</tt> |
John McCall | 100c649 | 2012-03-30 05:23:48 +0000 | [diff] [blame] | 1009 | object of non-automatic storage duration. A program is ill-formed |
| 1010 | if it captures an <tt>__autoreleasing</tt> object in a block or, |
| 1011 | unless by reference, in a C++11 lambda.</p> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1012 | |
| 1013 | <div class="rationale"><p>Rationale: autorelease pools are tied to the |
| 1014 | current thread and scope by their nature. While it is possible to |
| 1015 | have temporary objects whose instance variables are filled with |
| 1016 | autoreleased objects, there is no way that ARC can provide any sort of |
| 1017 | safety guarantee there.</p></div> |
| 1018 | |
| 1019 | <p>It is undefined behavior if a non-null pointer is assigned to |
| 1020 | an <tt>__autoreleasing</tt> object while an autorelease pool is in |
| 1021 | scope and then that object is read after the autorelease pool's scope |
| 1022 | is left.</p> |
| 1023 | |
| 1024 | </div> |
| 1025 | |
| 1026 | <div id="ownership.restrictions.conversion.indirect"> |
| 1027 | <h1>Conversion of pointers to ownership-qualified types</h1> |
| 1028 | |
| 1029 | <p>A program is ill-formed if an expression of type <tt>T*</tt> is |
| 1030 | converted, explicitly or implicitly, to the type <tt>U*</tt>, |
| 1031 | where <tt>T</tt> and <tt>U</tt> have different ownership |
Benjamin Kramer | 665a8dc | 2012-01-15 15:26:07 +0000 | [diff] [blame] | 1032 | qualification, unless:</p> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1033 | <ul> |
| 1034 | <li><tt>T</tt> is qualified with <tt>__strong</tt>, |
| 1035 | <tt>__autoreleasing</tt>, or <tt>__unsafe_unretained</tt>, and |
| 1036 | <tt>U</tt> is qualified with both <tt>const</tt> and |
| 1037 | <tt>__unsafe_unretained</tt>; or</li> |
| 1038 | <li>either <tt>T</tt> or <tt>U</tt> is <tt>cv void</tt>, where |
| 1039 | <tt>cv</tt> is an optional sequence of non-ownership qualifiers; or</li> |
| 1040 | <li>the conversion is requested with a <tt>reinterpret_cast</tt> in |
| 1041 | Objective-C++; or</li> |
| 1042 | <li>the conversion is a |
| 1043 | well-formed <a href="#ownership.restrictions.pass_by_writeback">pass-by-writeback</a>.</li> |
| 1044 | </ul> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1045 | |
Benjamin Kramer | 665a8dc | 2012-01-15 15:26:07 +0000 | [diff] [blame] | 1046 | <p>The analogous rule applies to <tt>T&</tt> and <tt>U&</tt> in |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1047 | Objective-C++.</p> |
| 1048 | |
| 1049 | <div class="rationale"><p>Rationale: these rules provide a reasonable |
| 1050 | level of type-safety for indirect pointers, as long as the underlying |
| 1051 | memory is not deallocated. The conversion to <tt>const |
| 1052 | __unsafe_unretained</tt> is permitted because the semantics of reads |
| 1053 | are equivalent across all these ownership semantics, and that's a very |
| 1054 | useful and common pattern. The interconversion with <tt>void*</tt> is |
| 1055 | useful for allocating memory or otherwise escaping the type system, |
| 1056 | but use it carefully. <tt>reinterpret_cast</tt> is considered to be |
| 1057 | an obvious enough sign of taking responsibility for any |
| 1058 | problems.</p></div> |
| 1059 | |
| 1060 | <p>It is undefined behavior to access an ownership-qualified object |
| 1061 | through an lvalue of a differently-qualified type, except that any |
| 1062 | non-<tt>__weak</tt> object may be read through |
| 1063 | an <tt>__unsafe_unretained</tt> lvalue.</p> |
| 1064 | |
| 1065 | <p>It is undefined behavior if a managed operation is performed on |
| 1066 | a <tt>__strong</tt> or <tt>__weak</tt> object without a guarantee that |
| 1067 | it contains a primitive zero bit-pattern, or if the storage for such |
| 1068 | an object is freed or reused without the object being first assigned a |
| 1069 | null pointer.</p> |
| 1070 | |
| 1071 | <div class="rationale"><p>Rationale: ARC cannot differentiate between |
| 1072 | an assignment operator which is intended to <q>initialize</q> dynamic |
| 1073 | memory and one which is intended to potentially replace a value. |
| 1074 | Therefore the object's pointer must be valid before letting ARC at it. |
| 1075 | Similarly, C and Objective-C do not provide any language hooks for |
| 1076 | destroying objects held in dynamic memory, so it is the programmer's |
| 1077 | responsibility to avoid leaks (<tt>__strong</tt> objects) and |
| 1078 | consistency errors (<tt>__weak</tt> objects).</p> |
| 1079 | |
| 1080 | <p>These requirements are followed automatically in Objective-C++ when |
| 1081 | creating objects of retainable object owner type with <tt>new</tt> |
| 1082 | or <tt>new[]</tt> and destroying them with <tt>delete</tt>, |
| 1083 | <tt>delete[]</tt>, or a pseudo-destructor expression. Note that |
| 1084 | arrays of nontrivially-ownership-qualified type are not ABI compatible |
| 1085 | with non-ARC code because the element type is non-POD: such arrays |
| 1086 | that are <tt>new[]</tt>'d in ARC translation units cannot |
| 1087 | be <tt>delete[]</tt>'d in non-ARC translation units and |
| 1088 | vice-versa.</p></div> |
| 1089 | |
| 1090 | </div> |
| 1091 | |
| 1092 | <div id="ownership.restrictions.pass_by_writeback"> |
| 1093 | <h1>Passing to an out parameter by writeback</h1> |
| 1094 | |
| 1095 | <p>If the argument passed to a parameter of type |
| 1096 | <tt>T __autoreleasing *</tt> has type <tt>U oq *</tt>, |
| 1097 | where <tt>oq</tt> is an ownership qualifier, then the argument is a |
| 1098 | candidate for <span class="term">pass-by-writeback</span> if:</p> |
| 1099 | |
| 1100 | <ul> |
Benjamin Kramer | 665a8dc | 2012-01-15 15:26:07 +0000 | [diff] [blame] | 1101 | <li><tt>oq</tt> is <tt>__strong</tt> or <tt>__weak</tt>, and</li> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1102 | <li>it would be legal to initialize a <tt>T __strong *</tt> with |
| 1103 | a <tt>U __strong *</tt>.</li> |
| 1104 | </ul> |
| 1105 | |
| 1106 | <p>For purposes of overload resolution, an implicit conversion |
| 1107 | sequence requiring a pass-by-writeback is always worse than an |
| 1108 | implicit conversion sequence not requiring a pass-by-writeback.</p> |
| 1109 | |
| 1110 | <p>The pass-by-writeback is ill-formed if the argument expression does |
| 1111 | not have a legal form:</p> |
| 1112 | |
| 1113 | <ul> |
Benjamin Kramer | 665a8dc | 2012-01-15 15:26:07 +0000 | [diff] [blame] | 1114 | <li><tt>&var</tt>, where <tt>var</tt> is a scalar variable of |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1115 | automatic storage duration with retainable object pointer type</li> |
| 1116 | <li>a conditional expression where the second and third operands are |
| 1117 | both legal forms</li> |
| 1118 | <li>a cast whose operand is a legal form</li> |
| 1119 | <li>a null pointer constant</li> |
| 1120 | </ul> |
| 1121 | |
| 1122 | <div class="rationale"><p>Rationale: the restriction in the form of |
| 1123 | the argument serves two purposes. First, it makes it impossible to |
| 1124 | pass the address of an array to the argument, which serves to protect |
| 1125 | against an otherwise serious risk of mis-inferring an <q>array</q> |
| 1126 | argument as an out-parameter. Second, it makes it much less likely |
| 1127 | that the user will see confusing aliasing problems due to the |
| 1128 | implementation, below, where their store to the writeback temporary is |
| 1129 | not immediately seen in the original argument variable.</p></div> |
| 1130 | |
Benjamin Kramer | 665a8dc | 2012-01-15 15:26:07 +0000 | [diff] [blame] | 1131 | <p>A pass-by-writeback is evaluated as follows:</p> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1132 | <ol> |
| 1133 | <li>The argument is evaluated to yield a pointer <tt>p</tt> of |
| 1134 | type <tt>U oq *</tt>.</li> |
| 1135 | <li>If <tt>p</tt> is a null pointer, then a null pointer is passed as |
| 1136 | the argument, and no further work is required for the pass-by-writeback.</li> |
| 1137 | <li>Otherwise, a temporary of type <tt>T __autoreleasing</tt> is |
| 1138 | created and initialized to a null pointer.</li> |
John McCall | 9da31cb | 2012-03-27 07:42:12 +0000 | [diff] [blame] | 1139 | <li>If the parameter is not an Objective-C method parameter marked |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1140 | <tt>out</tt>, then <tt>*p</tt> is read, and the result is written |
| 1141 | into the temporary with primitive semantics.</li> |
| 1142 | <li>The address of the temporary is passed as the argument to the |
| 1143 | actual call.</li> |
| 1144 | <li>After the call completes, the temporary is loaded with primitive |
| 1145 | semantics, and that value is assigned into <tt>*p</tt>.</li> |
Benjamin Kramer | 665a8dc | 2012-01-15 15:26:07 +0000 | [diff] [blame] | 1146 | </ol> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1147 | |
| 1148 | <div class="rationale"><p>Rationale: this is all admittedly |
| 1149 | convoluted. In an ideal world, we would see that a local variable is |
| 1150 | being passed to an out-parameter and retroactively modify its type to |
| 1151 | be <tt>__autoreleasing</tt> rather than <tt>__strong</tt>. This would |
| 1152 | be remarkably difficult and not always well-founded under the C type |
| 1153 | system. However, it was judged unacceptably invasive to require |
| 1154 | programmers to write <tt>__autoreleasing</tt> on all the variables |
| 1155 | they intend to use for out-parameters. This was the least bad |
| 1156 | solution.</p></div> |
| 1157 | |
| 1158 | </div> |
| 1159 | |
| 1160 | <div id="ownership.restrictions.records"> |
| 1161 | <h1>Ownership-qualified fields of structs and unions</h1> |
| 1162 | |
| 1163 | <p>A program is ill-formed if it declares a member of a C struct or |
| 1164 | union to have a nontrivially ownership-qualified type.</p> |
| 1165 | |
| 1166 | <div class="rationale"><p>Rationale: the resulting type would be |
| 1167 | non-POD in the C++ sense, but C does not give us very good language |
| 1168 | tools for managing the lifetime of aggregates, so it is more |
| 1169 | convenient to simply forbid them. It is still possible to manage this |
| 1170 | with a <tt>void*</tt> or an <tt>__unsafe_unretained</tt> |
| 1171 | object.</p></div> |
| 1172 | |
| 1173 | <p>This restriction does not apply in Objective-C++. However, |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 1174 | nontrivally ownership-qualified types are considered non-POD: in C++11 |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1175 | terms, they are not trivially default constructible, copy |
| 1176 | constructible, move constructible, copy assignable, move assignable, |
John McCall | 9da31cb | 2012-03-27 07:42:12 +0000 | [diff] [blame] | 1177 | or destructible. It is a violation of C++'s One Definition Rule to use |
| 1178 | a class outside of ARC that, under ARC, would have a nontrivially |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1179 | ownership-qualified member.</p> |
| 1180 | |
| 1181 | <div class="rationale"><p>Rationale: unlike in C, we can express all |
| 1182 | the necessary ARC semantics for ownership-qualified subobjects as |
| 1183 | suboperations of the (default) special member functions for the class. |
| 1184 | These functions then become non-trivial. This has the non-obvious |
John McCall | 9da31cb | 2012-03-27 07:42:12 +0000 | [diff] [blame] | 1185 | result that the class will have a non-trivial copy constructor and |
| 1186 | non-trivial destructor; if this would not normally be true outside of |
| 1187 | ARC, objects of the type will be passed and returned in an |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1188 | ABI-incompatible manner.</p></div> |
| 1189 | |
| 1190 | </div> |
| 1191 | |
| 1192 | </div> |
| 1193 | |
| 1194 | <div id="ownership.inference"> |
| 1195 | <h1>Ownership inference</h1> |
| 1196 | |
| 1197 | <div id="ownership.inference.variables"> |
| 1198 | <h1>Objects</h1> |
| 1199 | |
| 1200 | <p>If an object is declared with retainable object owner type, but |
| 1201 | without an explicit ownership qualifier, its type is implicitly |
| 1202 | adjusted to have <tt>__strong</tt> qualification.</p> |
| 1203 | |
| 1204 | <p>As a special case, if the object's base type is <tt>Class</tt> |
| 1205 | (possibly protocol-qualified), the type is adjusted to |
| 1206 | have <tt>__unsafe_unretained</tt> qualification instead.</p> |
| 1207 | |
| 1208 | </div> |
| 1209 | |
| 1210 | <div id="ownership.inference.indirect_parameters"> |
| 1211 | <h1>Indirect parameters</h1> |
| 1212 | |
| 1213 | <p>If a function or method parameter has type <tt>T*</tt>, where |
| 1214 | <tt>T</tt> is an ownership-unqualified retainable object pointer type, |
| 1215 | then:</p> |
| 1216 | |
| 1217 | <ul> |
| 1218 | <li>if <tt>T</tt> is <tt>const</tt>-qualified or <tt>Class</tt>, then |
| 1219 | it is implicitly qualified with <tt>__unsafe_unretained</tt>;</li> |
| 1220 | <li>otherwise, it is implicitly qualified |
| 1221 | with <tt>__autoreleasing</tt>.</li> |
| 1222 | </ul> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1223 | |
| 1224 | <div class="rationale"><p>Rationale: <tt>__autoreleasing</tt> exists |
| 1225 | mostly for this case, the Cocoa convention for out-parameters. Since |
| 1226 | a pointer to <tt>const</tt> is obviously not an out-parameter, we |
| 1227 | instead use a type more useful for passing arrays. If the user |
| 1228 | instead intends to pass in a <em>mutable</em> array, inferring |
| 1229 | <tt>__autoreleasing</tt> is the wrong thing to do; this directs some |
| 1230 | of the caution in the following rules about writeback.</p></div> |
| 1231 | |
| 1232 | <p>Such a type written anywhere else would be ill-formed by the |
| 1233 | general rule requiring ownership qualifiers.</p> |
| 1234 | |
| 1235 | <p>This rule does not apply in Objective-C++ if a parameter's type is |
| 1236 | dependent in a template pattern and is only <em>instantiated</em> to |
| 1237 | a type which would be a pointer to an unqualified retainable object |
| 1238 | pointer type. Such code is still ill-formed.</p> |
| 1239 | |
| 1240 | <div class="rationale"><p>Rationale: the convention is very unlikely |
| 1241 | to be intentional in template code.</p></div> |
| 1242 | |
| 1243 | </div> <!-- ownership.inference.indirect_parameters --> |
Douglas Gregor | e559ca1 | 2011-06-17 22:11:49 +0000 | [diff] [blame] | 1244 | |
| 1245 | <div id="ownership.inference.template_arguments"> |
| 1246 | <h1>Template arguments</h1> |
| 1247 | |
| 1248 | <p>If a template argument for a template type parameter is an |
| 1249 | retainable object owner type that does not have an explicit ownership |
| 1250 | qualifier, it is adjusted to have <tt>__strong</tt> |
Douglas Gregor | 54fb28a | 2011-06-17 22:19:27 +0000 | [diff] [blame] | 1251 | qualification. This adjustment occurs regardless of whether the |
Douglas Gregor | e559ca1 | 2011-06-17 22:11:49 +0000 | [diff] [blame] | 1252 | template argument was deduced or explicitly specified. </p> |
| 1253 | |
| 1254 | <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> |
| 1255 | |
| 1256 | </div> <!-- ownership.inference.template_arguments --> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1257 | </div> <!-- ownership.inference --> |
| 1258 | </div> <!-- ownership --> |
| 1259 | |
Douglas Gregor | e559ca1 | 2011-06-17 22:11:49 +0000 | [diff] [blame] | 1260 | |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1261 | <div id="family"> |
| 1262 | <h1>Method families</h1> |
| 1263 | |
| 1264 | <p>An Objective-C method may fall into a <span class="term">method |
| 1265 | family</span>, which is a conventional set of behaviors ascribed to it |
| 1266 | by the Cocoa conventions.</p> |
| 1267 | |
Benjamin Kramer | 665a8dc | 2012-01-15 15:26:07 +0000 | [diff] [blame] | 1268 | <p>A method is in a certain method family if:</p> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1269 | <ul> |
| 1270 | <li>it has a <tt>objc_method_family</tt> attribute placing it in that |
| 1271 | family; or if not that,</li> |
| 1272 | <li>it does not have an <tt>objc_method_family</tt> attribute placing |
| 1273 | it in a different or no family, and</li> |
| 1274 | <li>its selector falls into the corresponding selector family, and</li> |
| 1275 | <li>its signature obeys the added restrictions of the method family.</li> |
Benjamin Kramer | 665a8dc | 2012-01-15 15:26:07 +0000 | [diff] [blame] | 1276 | </ul> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1277 | |
| 1278 | <p>A selector is in a certain selector family if, ignoring any leading |
| 1279 | underscores, the first component of the selector either consists |
| 1280 | entirely of the name of the method family or it begins with that name |
| 1281 | followed by a character other than a lowercase letter. For |
| 1282 | example, <tt>_perform:with:</tt> and <tt>performWith:</tt> would fall |
| 1283 | into the <tt>perform</tt> family (if we recognized one), |
| 1284 | but <tt>performing:with</tt> would not.</p> |
| 1285 | |
| 1286 | <p>The families and their added restrictions are:</p> |
| 1287 | |
| 1288 | <ul> |
| 1289 | <li><tt>alloc</tt> methods must return a retainable object pointer type.</li> |
| 1290 | <li><tt>copy</tt> methods must return a retainable object pointer type.</li> |
| 1291 | <li><tt>mutableCopy</tt> methods must return a retainable object pointer type.</li> |
| 1292 | <li><tt>new</tt> methods must return a retainable object pointer type.</li> |
| 1293 | <li><tt>init</tt> methods must be instance methods and must return an |
| 1294 | Objective-C pointer type. Additionally, a program is ill-formed if it |
| 1295 | declares or contains a call to an <tt>init</tt> method whose return |
| 1296 | type is neither <tt>id</tt> nor a pointer to a super-class or |
John McCall | be16b89 | 2011-06-18 08:15:19 +0000 | [diff] [blame] | 1297 | sub-class of the declaring class (if the method was declared on |
| 1298 | a class) or the static receiver type of the call (if it was declared |
Benjamin Kramer | 665a8dc | 2012-01-15 15:26:07 +0000 | [diff] [blame] | 1299 | on a protocol). |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1300 | |
| 1301 | <div class="rationale"><p>Rationale: there are a fair number of existing |
| 1302 | methods with <tt>init</tt>-like selectors which nonetheless don't |
| 1303 | follow the <tt>init</tt> conventions. Typically these are either |
| 1304 | accidental naming collisions or helper methods called during |
| 1305 | initialization. Because of the peculiar retain/release behavior |
| 1306 | of <tt>init</tt> methods, it's very important not to treat these |
| 1307 | methods as <tt>init</tt> methods if they aren't meant to be. It was |
| 1308 | felt that implicitly defining these methods out of the family based on |
| 1309 | the exact relationship between the return type and the declaring class |
John McCall | be16b89 | 2011-06-18 08:15:19 +0000 | [diff] [blame] | 1310 | would be much too subtle and fragile. Therefore we identify a small |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1311 | number of legitimate-seeming return types and call everything else an |
| 1312 | error. This serves the secondary purpose of encouraging programmers |
John McCall | be16b89 | 2011-06-18 08:15:19 +0000 | [diff] [blame] | 1313 | not to accidentally give methods names in the <tt>init</tt> family.</p> |
| 1314 | |
| 1315 | <p>Note that a method with an <tt>init</tt>-family selector which |
| 1316 | returns a non-Objective-C type (e.g. <tt>void</tt>) is perfectly |
| 1317 | well-formed; it simply isn't in the <tt>init</tt> family.</p></div> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1318 | </li> |
| 1319 | </ul> |
| 1320 | |
| 1321 | <p>A program is ill-formed if a method's declarations, |
| 1322 | implementations, and overrides do not all have the same method |
| 1323 | family.</p> |
| 1324 | |
| 1325 | <div id="family.attribute"> |
| 1326 | <h1>Explicit method family control</h1> |
| 1327 | |
| 1328 | <p>A method may be annotated with the <tt>objc_method_family</tt> |
| 1329 | attribute to precisely control which method family it belongs to. If |
| 1330 | a method in an <tt>@implementation</tt> does not have this attribute, |
| 1331 | but there is a method declared in the corresponding <tt>@interface</tt> |
| 1332 | that does, then the attribute is copied to the declaration in the |
| 1333 | <tt>@implementation</tt>. The attribute is available outside of ARC, |
| 1334 | and may be tested for with the preprocessor query |
| 1335 | <tt>__has_attribute(objc_method_family)</tt>.</p> |
| 1336 | |
| 1337 | <p>The attribute is spelled |
| 1338 | <tt>__attribute__((objc_method_family(<i>family</i>)))</tt>. |
| 1339 | If <i>family</i> is <tt>none</tt>, the method has no family, even if |
| 1340 | it would otherwise be considered to have one based on its selector and |
| 1341 | type. Otherwise, <i>family</i> must be one |
| 1342 | of <tt>alloc</tt>, <tt>copy</tt>, <tt>init</tt>, |
| 1343 | <tt>mutableCopy</tt>, or <tt>new</tt>, in which case the method is |
| 1344 | considered to belong to the corresponding family regardless of its |
| 1345 | selector. It is an error if a method that is explicitly added to a |
| 1346 | family in this way does not meet the requirements of the family other |
| 1347 | than the selector naming convention.</p> |
| 1348 | |
| 1349 | <div class="rationale"><p>Rationale: the rules codified in this document |
| 1350 | describe the standard conventions of Objective-C. However, as these |
| 1351 | conventions have not heretofore been enforced by an unforgiving |
| 1352 | mechanical system, they are only imperfectly kept, especially as they |
| 1353 | haven't always even been precisely defined. While it is possible to |
| 1354 | define low-level ownership semantics with attributes like |
| 1355 | <tt>ns_returns_retained</tt>, this attribute allows the user to |
John McCall | 9da31cb | 2012-03-27 07:42:12 +0000 | [diff] [blame] | 1356 | communicate semantic intent, which is of use both to ARC (which, e.g., |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1357 | treats calls to <tt>init</tt> specially) and the static analyzer.</p></div> |
| 1358 | </div> |
| 1359 | |
| 1360 | <div id="family.semantics"> |
| 1361 | <h1>Semantics of method families</h1> |
| 1362 | |
| 1363 | <p>A method's membership in a method family may imply non-standard |
| 1364 | semantics for its parameters and return type.</p> |
| 1365 | |
| 1366 | <p>Methods in the <tt>alloc</tt>, <tt>copy</tt>, <tt>mutableCopy</tt>, |
| 1367 | and <tt>new</tt> families — that is, methods in all the |
John McCall | be16b89 | 2011-06-18 08:15:19 +0000 | [diff] [blame] | 1368 | currently-defined families except <tt>init</tt> — implicitly |
| 1369 | <a href="#objects.operands.retained_returns">return a retained |
| 1370 | object</a> as if they were annotated with |
| 1371 | the <tt>ns_returns_retained</tt> attribute. This can be overridden by |
| 1372 | annotating the method with either of |
| 1373 | the <tt>ns_returns_autoreleased</tt> or |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1374 | <tt>ns_returns_not_retained</tt> attributes.</p> |
| 1375 | |
Fariborz Jahanian | acd4aaf | 2011-07-06 22:47:46 +0000 | [diff] [blame] | 1376 | <p>Properties also follow same naming rules as methods. This means that |
| 1377 | those in the <tt>alloc</tt>, <tt>copy</tt>, <tt>mutableCopy</tt>, |
| 1378 | and <tt>new</tt> families provide access to |
| 1379 | <a href="#objects.operands.retained_returns">retained objects</a>. |
| 1380 | This can be overridden by annotating the property with |
| 1381 | <tt>ns_returns_not_retained</tt> attribute.</p> |
| 1382 | |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1383 | <div id="family.semantics.init"> |
| 1384 | <h1>Semantics of <tt>init</tt></h1> |
John McCall | be16b89 | 2011-06-18 08:15:19 +0000 | [diff] [blame] | 1385 | <p>Methods in the <tt>init</tt> family implicitly |
| 1386 | <a href="#objects.operands.consumed">consume</a> their <tt>self</tt> |
| 1387 | parameter and <a href="#objects.operands.retained_returns">return a |
| 1388 | retained object</a>. Neither of these properties can be altered |
| 1389 | through attributes.</p> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1390 | |
| 1391 | <p>A call to an <tt>init</tt> method with a receiver that is either |
| 1392 | <tt>self</tt> (possibly parenthesized or casted) or <tt>super</tt> is |
| 1393 | called a <span class="term">delegate init call</span>. It is an error |
| 1394 | for a delegate init call to be made except from an <tt>init</tt> |
| 1395 | method, and excluding blocks within such methods.</p> |
| 1396 | |
John McCall | be16b89 | 2011-06-18 08:15:19 +0000 | [diff] [blame] | 1397 | <p>As an exception to the <a href="misc.self">usual rule</a>, the |
| 1398 | variable <tt>self</tt> is mutable in an <tt>init</tt> method and has |
| 1399 | the usual semantics for a <tt>__strong</tt> variable. However, it is |
| 1400 | undefined behavior and the program is ill-formed, no diagnostic |
| 1401 | required, if an <tt>init</tt> method attempts to use the previous |
| 1402 | value of <tt>self</tt> after the completion of a delegate init call. |
| 1403 | It is conventional, but not required, for an <tt>init</tt> method to |
| 1404 | return <tt>self</tt>.</p> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1405 | |
John McCall | be16b89 | 2011-06-18 08:15:19 +0000 | [diff] [blame] | 1406 | <p>It is undefined behavior for a program to cause two or more calls |
| 1407 | to <tt>init</tt> methods on the same object, except that |
| 1408 | each <tt>init</tt> method invocation may perform at most one delegate |
| 1409 | init call.</p> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1410 | |
John McCall | f3d08a6 | 2011-06-18 07:31:30 +0000 | [diff] [blame] | 1411 | </div> <!-- family.semantics.init --> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1412 | |
| 1413 | <div id="family.semantics.result_type"> |
| 1414 | <h1>Related result types</h1> |
| 1415 | |
| 1416 | <p>Certain methods are candidates to have <span class="term">related |
| 1417 | result types</span>:</p> |
| 1418 | <ul> |
| 1419 | <li>class methods in the <tt>alloc</tt> and <tt>new</tt> method families</li> |
| 1420 | <li>instance methods in the <tt>init</tt> family</li> |
| 1421 | <li>the instance method <tt>self</tt></li> |
| 1422 | <li>outside of ARC, the instance methods <tt>retain</tt> and <tt>autorelease</tt></li> |
| 1423 | </ul> |
| 1424 | |
| 1425 | <p>If the formal result type of such a method is <tt>id</tt> or |
| 1426 | protocol-qualified <tt>id</tt>, or a type equal to the declaring class |
| 1427 | or a superclass, then it is said to have a related result type. In |
| 1428 | this case, when invoked in an explicit message send, it is assumed to |
| 1429 | return a type related to the type of the receiver:</p> |
| 1430 | |
| 1431 | <ul> |
| 1432 | <li>if it is a class method, and the receiver is a class |
| 1433 | name <tt>T</tt>, the message send expression has type <tt>T*</tt>; |
| 1434 | otherwise</li> |
| 1435 | <li>if it is an instance method, and the receiver has type <tt>T</tt>, |
| 1436 | the message send expression has type <tt>T</tt>; otherwise</li> |
| 1437 | <li>the message send expression has the normal result type of the |
| 1438 | method.</li> |
| 1439 | </ul> |
| 1440 | |
| 1441 | <p>This is a new rule of the Objective-C language and applies outside |
| 1442 | of ARC.</p> |
| 1443 | |
| 1444 | <div class="rationale"><p>Rationale: ARC's automatic code emission is |
| 1445 | more prone than most code to signature errors, i.e. errors where a |
| 1446 | call was emitted against one method signature, but the implementing |
| 1447 | method has an incompatible signature. Having more precise type |
John McCall | 9da31cb | 2012-03-27 07:42:12 +0000 | [diff] [blame] | 1448 | information helps drastically lower this risk, as well as catching |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1449 | a number of latent bugs.</p></div> |
| 1450 | |
| 1451 | </div> <!-- family.semantics.result_type --> |
| 1452 | </div> <!-- family.semantics --> |
| 1453 | </div> <!-- family --> |
| 1454 | |
| 1455 | <div id="optimization"> |
| 1456 | <h1>Optimization</h1> |
| 1457 | |
| 1458 | <p>ARC applies aggressive rules for the optimization of local |
| 1459 | behavior. These rules are based around a core assumption of |
| 1460 | <span class="term">local balancing</span>: that other code will |
| 1461 | perform retains and releases as necessary (and only as necessary) for |
| 1462 | its own safety, and so the optimizer does not need to consider global |
| 1463 | properties of the retain and release sequence. For example, if a |
| 1464 | retain and release immediately bracket a call, the optimizer can |
| 1465 | delete the retain and release on the assumption that the called |
| 1466 | function will not do a constant number of unmotivated releases |
| 1467 | followed by a constant number of <q>balancing</q> retains, such that |
| 1468 | the local retain/release pair is the only thing preventing the called |
| 1469 | function from ending up with a dangling reference.</p> |
| 1470 | |
| 1471 | <p>The optimizer assumes that when a new value enters local control, |
| 1472 | e.g. from a load of a non-local object or as the result of a function |
| 1473 | call, it is instaneously valid. Subsequently, a retain and release of |
| 1474 | a value are necessary on a computation path only if there is a use of |
| 1475 | that value before the release and after any operation which might |
| 1476 | cause a release of the value (including indirectly or non-locally), |
| 1477 | and only if the value is not demonstrably already retained.</p> |
| 1478 | |
| 1479 | <p>The complete optimization rules are quite complicated, but it would |
| 1480 | still be useful to document them here.</p> |
| 1481 | |
John McCall | dc7c5ad | 2011-07-22 08:53:00 +0000 | [diff] [blame] | 1482 | <div id="optimization.precise"> |
| 1483 | <h1>Precise lifetime semantics</h1> |
| 1484 | |
| 1485 | <p>In general, ARC maintains an invariant that a retainable object |
| 1486 | pointer held in a <tt>__strong</tt> object will be retained for the |
| 1487 | full formal lifetime of the object. Objects subject to this invariant |
| 1488 | have <span class="term">precise lifetime semantics</span>.</p> |
| 1489 | |
| 1490 | <p>By default, local variables of automatic storage duration do not |
| 1491 | have precise lifetime semantics. Such objects are simply strong |
| 1492 | references which hold values of retainable object pointer type, and |
| 1493 | these values are still fully subject to the optimizations on values |
| 1494 | under local control.</p> |
| 1495 | |
| 1496 | <div class="rationale"><p>Rationale: applying these precise-lifetime |
| 1497 | semantics strictly would be prohibitive. Many useful optimizations |
| 1498 | that might theoretically decrease the lifetime of an object would be |
| 1499 | rendered impossible. Essentially, it promises too much.</p></div> |
| 1500 | |
| 1501 | <p>A local variable of retainable object owner type and automatic |
| 1502 | storage duration may be annotated with the <tt>objc_precise_lifetime</tt> |
| 1503 | attribute to indicate that it should be considered to be an object |
| 1504 | with precise lifetime semantics.</p> |
| 1505 | |
| 1506 | <div class="rationale"><p>Rationale: nonetheless, it is sometimes |
| 1507 | useful to be able to force an object to be released at a precise time, |
| 1508 | even if that object does not appear to be used. This is likely to be |
| 1509 | uncommon enough that the syntactic weight of explicitly requesting |
| 1510 | these semantics will not be burdensome, and may even make the code |
| 1511 | clearer.</p></div> |
| 1512 | |
| 1513 | </div> <!-- optimization.precise --> |
| 1514 | |
John McCall | 9da31cb | 2012-03-27 07:42:12 +0000 | [diff] [blame] | 1515 | </div> <!-- optimization --> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1516 | |
| 1517 | <div id="misc"> |
| 1518 | <h1>Miscellaneous</h1> |
| 1519 | |
John McCall | f3d08a6 | 2011-06-18 07:31:30 +0000 | [diff] [blame] | 1520 | <div id="misc.special_methods"> |
| 1521 | <h1>Special methods</h1> |
| 1522 | |
| 1523 | <div id="misc.special_methods.retain"> |
| 1524 | <h1>Memory management methods</h1> |
| 1525 | |
| 1526 | <p>A program is ill-formed if it contains a method definition, message |
| 1527 | send, or <tt>@selector</tt> expression for any of the following |
Benjamin Kramer | 665a8dc | 2012-01-15 15:26:07 +0000 | [diff] [blame] | 1528 | selectors:</p> |
John McCall | f3d08a6 | 2011-06-18 07:31:30 +0000 | [diff] [blame] | 1529 | <ul> |
| 1530 | <li><tt>autorelease</tt></li> |
| 1531 | <li><tt>release</tt></li> |
| 1532 | <li><tt>retain</tt></li> |
| 1533 | <li><tt>retainCount</tt></li> |
| 1534 | </ul> |
John McCall | f3d08a6 | 2011-06-18 07:31:30 +0000 | [diff] [blame] | 1535 | |
| 1536 | <div class="rationale"><p>Rationale: <tt>retainCount</tt> is banned |
| 1537 | because ARC robs it of consistent semantics. The others were banned |
| 1538 | after weighing three options for how to deal with message sends:</p> |
| 1539 | |
| 1540 | <p><b>Honoring</b> them would work out very poorly if a programmer |
| 1541 | naively or accidentally tried to incorporate code written for manual |
| 1542 | retain/release code into an ARC program. At best, such code would do |
| 1543 | twice as much work as necessary; quite frequently, however, ARC and |
| 1544 | the explicit code would both try to balance the same retain, leading |
| 1545 | to crashes. The cost is losing the ability to perform <q>unrooted</q> |
| 1546 | retains, i.e. retains not logically corresponding to a strong |
| 1547 | reference in the object graph.</p> |
| 1548 | |
| 1549 | <p><b>Ignoring</b> them would badly violate user expectations about their |
| 1550 | code. While it <em>would</em> make it easier to develop code simultaneously |
| 1551 | for ARC and non-ARC, there is very little reason to do so except for |
| 1552 | certain library developers. ARC and non-ARC translation units share |
| 1553 | an execution model and can seamlessly interoperate. Within a |
| 1554 | translation unit, a developer who faithfully maintains their code in |
| 1555 | non-ARC mode is suffering all the restrictions of ARC for zero |
| 1556 | benefit, while a developer who isn't testing the non-ARC mode is |
| 1557 | likely to be unpleasantly surprised if they try to go back to it.</p> |
| 1558 | |
| 1559 | <p><b>Banning</b> them has the disadvantage of making it very awkward |
| 1560 | to migrate existing code to ARC. The best answer to that, given a |
| 1561 | number of other changes and restrictions in ARC, is to provide a |
| 1562 | specialized tool to assist users in that migration.</p> |
| 1563 | |
| 1564 | <p>Implementing these methods was banned because they are too integral |
| 1565 | to the semantics of ARC; many tricks which worked tolerably under |
| 1566 | manual reference counting will misbehave if ARC performs an ephemeral |
| 1567 | extra retain or two. If absolutely required, it is still possible to |
| 1568 | implement them in non-ARC code, for example in a category; the |
| 1569 | implementations must obey the <a href="#objects.retains">semantics</a> |
| 1570 | laid out elsewhere in this document.</p> |
| 1571 | |
| 1572 | </div> |
| 1573 | </div> <!-- misc.special_methods.retain --> |
| 1574 | |
| 1575 | <div id="misc.special_methods.dealloc"> |
| 1576 | <h1><tt>dealloc</tt></h1> |
| 1577 | |
| 1578 | <p>A program is ill-formed if it contains a message send |
| 1579 | or <tt>@selector</tt> expression for the selector <tt>dealloc</tt>.</p> |
| 1580 | |
| 1581 | <div class="rationale"><p>Rationale: there are no legitimate reasons |
| 1582 | to call <tt>dealloc</tt> directly.</p></div> |
| 1583 | |
| 1584 | <p>A class may provide a method definition for an instance method |
| 1585 | named <tt>dealloc</tt>. This method will be called after the final |
| 1586 | <tt>release</tt> of the object but before it is deallocated or any of |
| 1587 | its instance variables are destroyed. The superclass's implementation |
| 1588 | of <tt>dealloc</tt> will be called automatically when the method |
| 1589 | returns.</p> |
| 1590 | |
| 1591 | <div class="rationale"><p>Rationale: even though ARC destroys instance |
| 1592 | variables automatically, there are still legitimate reasons to write |
| 1593 | a <tt>dealloc</tt> method, such as freeing non-retainable resources. |
| 1594 | Failing to call <tt>[super dealloc]</tt> in such a method is nearly |
| 1595 | always a bug. Sometimes, the object is simply trying to prevent |
| 1596 | itself from being destroyed, but <tt>dealloc</tt> is really far too |
| 1597 | late for the object to be raising such objections. Somewhat more |
| 1598 | legitimately, an object may have been pool-allocated and should not be |
| 1599 | deallocated with <tt>free</tt>; for now, this can only be supported |
| 1600 | with a <tt>dealloc</tt> implementation outside of ARC. Such an |
| 1601 | implementation must be very careful to do all the other work |
| 1602 | that <tt>NSObject</tt>'s <tt>dealloc</tt> would, which is outside the |
| 1603 | scope of this document to describe.</p></div> |
| 1604 | |
| 1605 | </div> |
| 1606 | |
| 1607 | </div> <!-- misc.special_methods --> |
| 1608 | |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1609 | <div id="autoreleasepool"> |
| 1610 | <h1><tt>@autoreleasepool</tt></h1> |
| 1611 | |
| 1612 | <p>To simplify the use of autorelease pools, and to bring them under |
| 1613 | the control of the compiler, a new kind of statement is available in |
| 1614 | Objective-C. It is written <tt>@autoreleasepool</tt> followed by |
| 1615 | a <i>compound-statement</i>, i.e. by a new scope delimited by curly |
| 1616 | braces. Upon entry to this block, the current state of the |
| 1617 | autorelease pool is captured. When the block is exited normally, |
| 1618 | whether by fallthrough or directed control flow (such |
| 1619 | as <tt>return</tt> or <tt>break</tt>), the autorelease pool is |
| 1620 | restored to the saved state, releasing all the objects in it. When |
| 1621 | the block is exited with an exception, the pool is not drained.</p> |
| 1622 | |
John McCall | f3d08a6 | 2011-06-18 07:31:30 +0000 | [diff] [blame] | 1623 | <p><tt>@autoreleasepool</tt> may be used in non-ARC translation units, |
| 1624 | with equivalent semantics.</p> |
| 1625 | |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1626 | <p>A program is ill-formed if it refers to the |
| 1627 | <tt>NSAutoreleasePool</tt> class.</p> |
| 1628 | |
| 1629 | <div class="rationale"><p>Rationale: autorelease pools are clearly |
| 1630 | important for the compiler to reason about, but it is far too much to |
| 1631 | expect the compiler to accurately reason about control dependencies |
| 1632 | between two calls. It is also very easy to accidentally forget to |
| 1633 | drain an autorelease pool when using the manual API, and this can |
| 1634 | significantly inflate the process's high-water-mark. The introduction |
| 1635 | of a new scope is unfortunate but basically required for sane |
| 1636 | interaction with the rest of the language. Not draining the pool |
| 1637 | during an unwind is apparently required by the Objective-C exceptions |
| 1638 | implementation.</p></div> |
| 1639 | |
| 1640 | </div> <!-- autoreleasepool --> |
| 1641 | |
| 1642 | <div id="misc.self"> |
| 1643 | <h1><tt>self</tt></h1> |
| 1644 | |
| 1645 | <p>The <tt>self</tt> parameter variable of an Objective-C method is |
| 1646 | never actually retained by the implementation. It is undefined |
| 1647 | behavior, or at least dangerous, to cause an object to be deallocated |
Ted Kremenek | 2bbcd5c | 2011-11-14 21:59:25 +0000 | [diff] [blame] | 1648 | during a message send to that object.</p> |
| 1649 | |
| 1650 | <p>To make this safe, for Objective-C instance methods <tt>self</tt> is |
| 1651 | implicitly <tt>const</tt> unless the method is in the <a |
| 1652 | href="#family.semantics.init"><tt>init</tt> family</a>. Further, <tt>self</tt> |
| 1653 | is <b>always</b> implicitly <tt>const</tt> within a class method.</p> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1654 | |
| 1655 | <div class="rationale"><p>Rationale: the cost of |
| 1656 | retaining <tt>self</tt> in all methods was found to be prohibitive, as |
| 1657 | it tends to be live across calls, preventing the optimizer from |
| 1658 | proving that the retain and release are unnecessary — for good |
| 1659 | reason, as it's quite possible in theory to cause an object to be |
| 1660 | deallocated during its execution without this retain and release. |
| 1661 | Since it's extremely uncommon to actually do so, even unintentionally, |
| 1662 | and since there's no natural way for the programmer to remove this |
| 1663 | retain/release pair otherwise (as there is for other parameters by, |
| 1664 | say, making the variable <tt>__unsafe_unretained</tt>), we chose to |
| 1665 | make this optimizing assumption and shift some amount of risk to the |
| 1666 | user.</p></div> |
| 1667 | |
| 1668 | </div> <!-- misc.self --> |
| 1669 | |
| 1670 | <div id="misc.enumeration"> |
| 1671 | <h1>Fast enumeration iteration variables</h1> |
| 1672 | |
| 1673 | <p>If a variable is declared in the condition of an Objective-C fast |
| 1674 | enumeration loop, and the variable has no explicit ownership |
| 1675 | qualifier, then it is qualified with <tt>const __strong</tt> and |
| 1676 | objects encountered during the enumeration are not actually |
| 1677 | retained.</p> |
| 1678 | |
| 1679 | <div class="rationale"><p>Rationale: this is an optimization made |
| 1680 | possible because fast enumeration loops promise to keep the objects |
| 1681 | retained during enumeration, and the collection itself cannot be |
| 1682 | synchronously modified. It can be overridden by explicitly qualifying |
| 1683 | the variable with <tt>__strong</tt>, which will make the variable |
| 1684 | mutable again and cause the loop to retain the objects it |
Benjamin Kramer | 665a8dc | 2012-01-15 15:26:07 +0000 | [diff] [blame] | 1685 | encounters.</p></div> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1686 | |
John McCall | 9da31cb | 2012-03-27 07:42:12 +0000 | [diff] [blame] | 1687 | </div> <!-- misc.enumeration --> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1688 | |
| 1689 | <div id="misc.blocks"> |
| 1690 | <h1>Blocks</h1> |
| 1691 | |
| 1692 | <p>The implicit <tt>const</tt> capture variables created when |
| 1693 | evaluating a block literal expression have the same ownership |
| 1694 | semantics as the local variables they capture. The capture is |
| 1695 | performed by reading from the captured variable and initializing the |
| 1696 | capture variable with that value; the capture variable is destroyed |
| 1697 | when the block literal is, i.e. at the end of the enclosing scope.</p> |
| 1698 | |
| 1699 | <p>The <a href="#ownership.inference">inference</a> rules apply |
| 1700 | equally to <tt>__block</tt> variables, which is a shift in semantics |
| 1701 | from non-ARC, where <tt>__block</tt> variables did not implicitly |
| 1702 | retain during capture.</p> |
| 1703 | |
| 1704 | <p><tt>__block</tt> variables of retainable object owner type are |
| 1705 | moved off the stack by initializing the heap copy with the result of |
Benjamin Kramer | 665a8dc | 2012-01-15 15:26:07 +0000 | [diff] [blame] | 1706 | moving from the stack copy.</p> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1707 | |
| 1708 | <p>With the exception of retains done as part of initializing |
| 1709 | a <tt>__strong</tt> parameter variable or reading a <tt>__weak</tt> |
| 1710 | variable, whenever these semantics call for retaining a value of |
| 1711 | block-pointer type, it has the effect of a <tt>Block_copy</tt>. The |
| 1712 | optimizer may remove such copies when it sees that the result is |
| 1713 | used only as an argument to a call.</p> |
| 1714 | |
| 1715 | </div> <!-- misc.blocks --> |
| 1716 | |
| 1717 | <div id="misc.exceptions"> |
| 1718 | <h1>Exceptions</h1> |
| 1719 | |
| 1720 | <p>By default in Objective C, ARC is not exception-safe for normal |
Benjamin Kramer | 665a8dc | 2012-01-15 15:26:07 +0000 | [diff] [blame] | 1721 | releases:</p> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1722 | <ul> |
| 1723 | <li>It does not end the lifetime of <tt>__strong</tt> variables when |
| 1724 | their scopes are abnormally terminated by an exception.</li> |
| 1725 | <li>It does not perform releases which would occur at the end of |
| 1726 | a full-expression if that full-expression throws an exception.</li> |
| 1727 | </ul> |
| 1728 | |
| 1729 | <p>A program may be compiled with the option |
| 1730 | <tt>-fobjc-arc-exceptions</tt> in order to enable these, or with the |
| 1731 | option <tt>-fno-objc-arc-exceptions</tt> to explicitly disable them, |
| 1732 | with the last such argument <q>winning</q>.</p> |
| 1733 | |
| 1734 | <div class="rationale"><p>Rationale: the standard Cocoa convention is |
| 1735 | that exceptions signal programmer error and are not intended to be |
| 1736 | recovered from. Making code exceptions-safe by default would impose |
| 1737 | severe runtime and code size penalties on code that typically does not |
| 1738 | actually care about exceptions safety. Therefore, ARC-generated code |
| 1739 | leaks by default on exceptions, which is just fine if the process is |
| 1740 | going to be immediately terminated anyway. Programs which do care |
| 1741 | about recovering from exceptions should enable the option.</p></div> |
| 1742 | |
| 1743 | <p>In Objective-C++, <tt>-fobjc-arc-exceptions</tt> is enabled by |
| 1744 | default.</p> |
| 1745 | |
| 1746 | <div class="rationale"><p>Rationale: C++ already introduces pervasive |
| 1747 | exceptions-cleanup code of the sort that ARC introduces. C++ |
| 1748 | programmers who have not already disabled exceptions are much more |
| 1749 | likely to actual require exception-safety.</p></div> |
| 1750 | |
| 1751 | <p>ARC does end the lifetimes of <tt>__weak</tt> objects when an |
| 1752 | exception terminates their scope unless exceptions are disabled in the |
| 1753 | compiler.</p> |
| 1754 | |
| 1755 | <div class="rationale"><p>Rationale: the consequence of a |
| 1756 | local <tt>__weak</tt> object not being destroyed is very likely to be |
| 1757 | corruption of the Objective-C runtime, so we want to be safer here. |
| 1758 | Of course, potentially massive leaks are about as likely to take down |
| 1759 | the process as this corruption is if the program does try to recover |
| 1760 | from exceptions.</p></div> |
| 1761 | |
| 1762 | </div> <!-- misc.exceptions --> |
| 1763 | |
John McCall | dc7c5ad | 2011-07-22 08:53:00 +0000 | [diff] [blame] | 1764 | <div id="misc.interior"> |
| 1765 | <h1>Interior pointers</h1> |
| 1766 | |
| 1767 | <p>An Objective-C method returning a non-retainable pointer may be |
| 1768 | annotated with the <tt>objc_returns_inner_pointer</tt> attribute to |
| 1769 | indicate that it returns a handle to the internal data of an object, |
| 1770 | and that this reference will be invalidated if the object is |
| 1771 | destroyed. When such a message is sent to an object, the object's |
| 1772 | lifetime will be extended until at least the earliest of:</p> |
| 1773 | |
| 1774 | <ul> |
| 1775 | <li>the last use of the returned pointer, or any pointer derived from |
| 1776 | it, in the calling function or</li> |
| 1777 | <li>the autorelease pool is restored to a previous state.</li> |
| 1778 | </ul> |
| 1779 | |
| 1780 | <div class="rationale"><p>Rationale: not all memory and resources are |
| 1781 | managed with reference counts; it is common for objects to manage |
| 1782 | private resources in their own, private way. Typically these |
| 1783 | resources are completely encapsulated within the object, but some |
| 1784 | classes offer their users direct access for efficiency. If ARC is not |
| 1785 | aware of methods that return such <q>interior</q> pointers, its |
| 1786 | optimizations can cause the owning object to be reclaimed too soon. |
| 1787 | This attribute informs ARC that it must tread lightly.</p> |
| 1788 | |
| 1789 | <p>The extension rules are somewhat intentionally vague. The |
| 1790 | autorelease pool limit is there to permit a simple implementation to |
| 1791 | simply retain and autorelease the receiver. The other limit permits |
| 1792 | some amount of optimization. The phrase <q>derived from</q> is |
| 1793 | intended to encompass the results both of pointer transformations, |
| 1794 | such as casts and arithmetic, and of loading from such derived |
| 1795 | pointers; furthermore, it applies whether or not such derivations are |
| 1796 | applied directly in the calling code or by other utility code (for |
| 1797 | example, the C library routine <tt>strchr</tt>). However, the |
| 1798 | implementation never need account for uses after a return from the |
| 1799 | code which calls the method returning an interior pointer.</p></div> |
| 1800 | |
| 1801 | <p>As an exception, no extension is required if the receiver is loaded |
| 1802 | directly from a <tt>__strong</tt> object |
| 1803 | with <a href="#optimization.precise">precise lifetime semantics</a>.</p> |
| 1804 | |
| 1805 | <div class="rationale"><p>Rationale: implicit autoreleases carry the |
| 1806 | risk of significantly inflating memory use, so it's important to |
| 1807 | provide users a way of avoiding these autoreleases. Tying this to |
| 1808 | precise lifetime semantics is ideal, as for local variables this |
| 1809 | requires a very explicit annotation, which allows ARC to trust the |
| 1810 | user with good cheer.</p></div> |
| 1811 | |
| 1812 | </div> <!-- misc.interior --> |
| 1813 | |
John McCall | 9da31cb | 2012-03-27 07:42:12 +0000 | [diff] [blame] | 1814 | <div id="misc.c-retainable"> |
| 1815 | <h1>C retainable pointer types</h1> |
| 1816 | |
| 1817 | <p>A type is a <span class="term">C retainable pointer type</span> |
| 1818 | if it is a pointer to (possibly qualified) <tt>void</tt> or a |
| 1819 | pointer to a (possibly qualifier) <tt>struct</tt> or <tt>class</tt> |
| 1820 | type.</p> |
| 1821 | |
| 1822 | <div class="rationale"><p>Rationale: ARC does not manage pointers of |
| 1823 | CoreFoundation type (or any of the related families of retainable C |
| 1824 | pointers which interoperate with Objective-C for retain/release |
| 1825 | operation). In fact, ARC does not even know how to distinguish these |
| 1826 | types from arbitrary C pointer types. The intent of this concept is |
| 1827 | to filter out some obviously non-object types while leaving a hook for |
| 1828 | later tightening if a means of exhaustively marking CF types is made |
| 1829 | available.</p></div> |
| 1830 | |
| 1831 | <div id="misc.c-retainable.audit"> |
| 1832 | <h1>Auditing of C retainable pointer interfaces</h1> |
| 1833 | |
| 1834 | <p><span class="revision"><span class="whenRevised">[beginning Apple 4.0, LLVM 3.1]</span></span></p> |
| 1835 | |
| 1836 | <p>A C function may be marked with the <tt>cf_audited_transfer</tt> |
| 1837 | attribute to express that, except as otherwise marked with attributes, |
| 1838 | it obeys the parameter (consuming vs. non-consuming) and return |
| 1839 | (retained vs. non-retained) conventions for a C function of its name, |
| 1840 | namely:</p> |
| 1841 | |
| 1842 | <ul> |
| 1843 | <li>A parameter of C retainable pointer type is assumed to not be |
| 1844 | consumed unless it is marked with the <tt>cf_consumed</tt> attribute, and</li> |
| 1845 | <li>A result of C retainable pointer type is assumed to not be |
| 1846 | returned retained unless the function is either |
| 1847 | marked <tt>cf_returns_retained</tt> or it follows |
| 1848 | the create/copy naming convention and is not |
| 1849 | marked <tt>cf_returns_not_retained</tt>.</li> |
| 1850 | </ul> |
| 1851 | |
| 1852 | <p>A function obeys the <span class="term">create/copy</span> naming |
| 1853 | convention if its name contains as a substring:</p> |
| 1854 | <ul> |
| 1855 | <li>either <q>Create</q> or <q>Copy</q> not followed by a lowercase letter, or</li> |
| 1856 | <li>either <q>create</q> or <q>copy</q> not followed by a lowercase |
| 1857 | letter and not preceded by any letter, whether uppercase or lowercase.</li> |
| 1858 | </ul> |
| 1859 | |
| 1860 | <p>A second attribute, <tt>cf_unknown_transfer</tt>, signifies that a |
| 1861 | function's transfer semantics cannot be accurately captured using any |
| 1862 | of these annotations. A program is ill-formed if it annotates the |
| 1863 | same function with both <tt>cf_audited_transfer</tt> |
| 1864 | and <tt>cf_unknown_transfer</tt>.</p> |
| 1865 | |
Benjamin Kramer | 48d798c | 2012-06-02 10:20:41 +0000 | [diff] [blame] | 1866 | <p>A pragma is provided to facilitate the mass annotation of interfaces:</p> |
John McCall | 9da31cb | 2012-03-27 07:42:12 +0000 | [diff] [blame] | 1867 | |
| 1868 | <pre>#pragma arc_cf_code_audited begin |
| 1869 | ... |
| 1870 | #pragma arc_cf_code_audited end</pre> |
| 1871 | |
| 1872 | <p>All C functions declared within the extent of this pragma are |
| 1873 | treated as if annotated with the <tt>cf_audited_transfer</tt> |
| 1874 | attribute unless they otherwise have the <tt>cf_unknown_transfer</tt> |
| 1875 | attribute. The pragma is accepted in all language modes. A program |
| 1876 | is ill-formed if it attempts to change files, whether by including a |
| 1877 | file or ending the current file, within the extent of this pragma.</p> |
| 1878 | |
| 1879 | <p>It is possible to test for all the features in this section with |
| 1880 | <tt>__has_feature(arc_cf_code_audited)</tt>.</p> |
| 1881 | |
| 1882 | <div class="rationale"><p>Rationale: A significant inconvenience in |
| 1883 | ARC programming is the necessity of interacting with APIs based around |
| 1884 | C retainable pointers. These features are designed to make it |
| 1885 | relatively easy for API authors to quickly review and annotate their |
| 1886 | interfaces, in turn improving the fidelity of tools such as the static |
| 1887 | analyzer and ARC. The single-file restriction on the pragma is |
| 1888 | designed to eliminate the risk of accidentally annotating some other |
| 1889 | header's interfaces.</p></div> |
| 1890 | |
| 1891 | </div> <!-- misc.c-retainable.audit --> |
| 1892 | |
| 1893 | </div> <!-- misc.c-retainable --> |
| 1894 | |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 1895 | </div> <!-- misc --> |
John McCall | 98a48cf | 2011-06-19 09:36:02 +0000 | [diff] [blame] | 1896 | |
| 1897 | <div id="runtime"> |
| 1898 | <h1>Runtime support</h1> |
| 1899 | |
John McCall | 085d09d | 2011-06-19 10:12:24 +0000 | [diff] [blame] | 1900 | <p>This section describes the interaction between the ARC runtime and |
| 1901 | the code generated by the ARC compiler. This is not part of the ARC |
| 1902 | language specification; instead, it is effectively a language-specific |
| 1903 | ABI supplement, akin to the <q>Itanium</q> generic ABI for C++.</p> |
John McCall | 98a48cf | 2011-06-19 09:36:02 +0000 | [diff] [blame] | 1904 | |
| 1905 | <p>Ownership qualification does not alter the storage requirements for |
John McCall | 085d09d | 2011-06-19 10:12:24 +0000 | [diff] [blame] | 1906 | objects, except that it is undefined behavior if a <tt>__weak</tt> |
| 1907 | object is inadequately aligned for an object of type <tt>id</tt>. The |
| 1908 | other qualifiers may be used on explicitly under-aligned memory.</p> |
John McCall | 98a48cf | 2011-06-19 09:36:02 +0000 | [diff] [blame] | 1909 | |
| 1910 | <p>The runtime tracks <tt>__weak</tt> objects which holds non-null |
John McCall | 3914a30 | 2011-06-19 09:59:33 +0000 | [diff] [blame] | 1911 | values. It is undefined behavior to direct modify a <tt>__weak</tt> |
| 1912 | object which is being tracked by the runtime except through an |
| 1913 | <a href="#runtime.objc_storeWeak"><tt>objc_storeWeak</tt></a>, |
| 1914 | <a href="#runtime.objc_destroyWeak"><tt>objc_destroyWeak</tt></a>, |
| 1915 | or <a href="#runtime.objc_moveWeak"><tt>objc_moveWeak</tt></a> |
John McCall | 98a48cf | 2011-06-19 09:36:02 +0000 | [diff] [blame] | 1916 | call.</p> |
| 1917 | |
John McCall | 3914a30 | 2011-06-19 09:59:33 +0000 | [diff] [blame] | 1918 | <p>The runtime must provide a number of new entrypoints which the |
| 1919 | compiler may emit, which are described in the remainder of this |
| 1920 | section.</p> |
| 1921 | |
| 1922 | <div class="rationale"><p>Rationale: Several of these functions are |
| 1923 | semantically equivalent to a message send; we emit calls to C |
| 1924 | functions instead because:</p> |
| 1925 | <ul> |
| 1926 | <li>the machine code to do so is significantly smaller,</li> |
| 1927 | <li>it is much easier to recognize the C functions in the ARC optimizer, and</li> |
| 1928 | <li>a sufficient sophisticated runtime may be able to avoid the |
| 1929 | message send in common cases.</li> |
| 1930 | </ul> |
| 1931 | |
| 1932 | <p>Several other of these functions are <q>fused</q> operations which |
| 1933 | can be described entirely in terms of other operations. We use the |
| 1934 | fused operations primarily as a code-size optimization, although in |
| 1935 | some cases there is also a real potential for avoiding redundant |
| 1936 | operations in the runtime.</p> |
| 1937 | |
| 1938 | </div> |
| 1939 | |
John McCall | 98a48cf | 2011-06-19 09:36:02 +0000 | [diff] [blame] | 1940 | <div id="runtime.objc_autorelease"> |
| 1941 | <h1><tt>id objc_autorelease(id value);</tt></h1> |
| 1942 | <p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a |
| 1943 | valid object.</p> |
| 1944 | <p>If <tt>value</tt> is null, this call has no effect. Otherwise, it |
| 1945 | adds the object to the innermost autorelease pool exactly as if the |
| 1946 | object had been sent the <tt>autorelease</tt> message.</p> |
| 1947 | <p>Always returns <tt>value</tt>.</p> |
| 1948 | </div> <!-- runtime.objc_autorelease --> |
| 1949 | |
| 1950 | <div id="runtime.objc_autoreleasePoolPop"> |
| 1951 | <h1><tt>void objc_autoreleasePoolPop(void *pool);</tt></h1> |
| 1952 | <p><i>Precondition:</i> <tt>pool</tt> is the result of a previous call to |
| 1953 | <a href="runtime.objc_autoreleasePoolPush"><tt>objc_autoreleasePoolPush</tt></a> |
| 1954 | on the current thread, where neither <tt>pool</tt> nor any enclosing |
| 1955 | pool have previously been popped.</p> |
| 1956 | <p>Releases all the objects added to the given autorelease pool and |
| 1957 | any autorelease pools it encloses, then sets the current autorelease |
| 1958 | pool to the pool directly enclosing <tt>pool</tt>.</p> |
| 1959 | </div> <!-- runtime.objc_autoreleasePoolPop --> |
| 1960 | |
| 1961 | <div id="runtime.objc_autoreleasePoolPush"> |
| 1962 | <h1><tt>void *objc_autoreleasePoolPush(void);</tt></h1> |
| 1963 | <p>Creates a new autorelease pool that is enclosed by the current |
| 1964 | pool, makes that the current pool, and returns an opaque <q>handle</q> |
| 1965 | to it.</p> |
| 1966 | |
| 1967 | <div class="rationale"><p>Rationale: while the interface is described |
| 1968 | as an explicit hierarchy of pools, the rules allow the implementation |
| 1969 | to just keep a stack of objects, using the stack depth as the opaque |
| 1970 | pool handle.</p></div> |
| 1971 | |
| 1972 | </div> <!-- runtime.objc_autoreleasePoolPush --> |
| 1973 | |
| 1974 | <div id="runtime.objc_autoreleaseReturnValue"> |
| 1975 | <h1><tt>id objc_autoreleaseReturnValue(id value);</tt></h1> |
| 1976 | <p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a |
| 1977 | valid object.</p> |
| 1978 | <p>If <tt>value</tt> is null, this call has no effect. Otherwise, it |
| 1979 | makes a best effort to hand off ownership of a retain count on the |
| 1980 | object to a call |
| 1981 | to <a href="runtime.objc_retainAutoreleasedReturnValue"><tt>objc_retainAutoreleasedReturnValue</tt></a> |
| 1982 | for the same object in an enclosing call frame. If this is not |
| 1983 | possible, the object is autoreleased as above.</p> |
| 1984 | <p>Always returns <tt>value</tt>.</p> |
| 1985 | </div> <!-- runtime.objc_autoreleaseReturnValue --> |
| 1986 | |
| 1987 | <div id="runtime.objc_copyWeak"> |
| 1988 | <h1><tt>void objc_copyWeak(id *dest, id *src);</tt></h1> |
| 1989 | <p><i>Precondition:</i> <tt>src</tt> is a valid pointer which either |
| 1990 | contains a null pointer or has been registered as a <tt>__weak</tt> |
| 1991 | object. <tt>dest</tt> is a valid pointer which has not been |
| 1992 | registered as a <tt>__weak</tt> object.</p> |
| 1993 | <p><tt>dest</tt> is initialized to be equivalent to <tt>src</tt>, |
| 1994 | potentially registering it with the runtime. Equivalent to the |
| 1995 | following code:</p> |
| 1996 | <pre>void objc_copyWeak(id *dest, id *src) { |
| 1997 | objc_release(objc_initWeak(dest, objc_loadWeakRetained(src))); |
| 1998 | }</pre> |
| 1999 | <p>Must be atomic with respect to calls to <tt>objc_storeWeak</tt> |
| 2000 | on <tt>src</tt>.</p> |
| 2001 | </div> <!-- runtime.objc_copyWeak --> |
| 2002 | |
| 2003 | <div id="runtime.objc_destroyWeak"> |
| 2004 | <h1><tt>void objc_destroyWeak(id *object);</tt></h1> |
| 2005 | <p><i>Precondition:</i> <tt>object</tt> is a valid pointer which |
| 2006 | either contains a null pointer or has been registered as |
| 2007 | a <tt>__weak</tt> object.</p> |
| 2008 | <p><tt>object</tt> is unregistered as a weak object, if it ever was. |
| 2009 | The current value of <tt>object</tt> is left unspecified; otherwise, |
| 2010 | equivalent to the following code:</p> |
| 2011 | <pre>void objc_destroyWeak(id *object) { |
| 2012 | objc_storeWeak(object, nil); |
| 2013 | }</pre> |
| 2014 | <p>Does not need to be atomic with respect to calls |
| 2015 | to <tt>objc_storeWeak</tt> on <tt>object</tt>.</p> |
| 2016 | </div> <!-- runtime.objc_destroyWeak --> |
| 2017 | |
| 2018 | <div id="runtime.objc_initWeak"> |
| 2019 | <h1><tt>id objc_initWeak(id *object, id value);</tt></h1> |
| 2020 | <p><i>Precondition:</i> <tt>object</tt> is a valid pointer which has |
| 2021 | not been registered as a <tt>__weak</tt> object. <tt>value</tt> is |
| 2022 | null or a pointer to a valid object.</p> |
| 2023 | <p>If <tt>value</tt> is a null pointer or the object to which it |
| 2024 | points has begun deallocation, <tt>object</tt> is zero-initialized. |
| 2025 | Otherwise, <tt>object</tt> is registered as a <tt>__weak</tt> object |
| 2026 | pointing to <tt>value</tt>. Equivalent to the following code:</p> |
| 2027 | <pre>id objc_initWeak(id *object, id value) { |
| 2028 | *object = nil; |
| 2029 | return objc_storeWeak(object, value); |
| 2030 | }</pre> |
| 2031 | <p>Returns the value of <tt>object</tt> after the call.</p> |
| 2032 | <p>Does not need to be atomic with respect to calls |
| 2033 | to <tt>objc_storeWeak</tt> on <tt>object</tt>.</p> |
| 2034 | </div> <!-- runtime.objc_initWeak --> |
| 2035 | |
| 2036 | <div id="runtime.objc_loadWeak"> |
| 2037 | <h1><tt>id objc_loadWeak(id *object);</tt></h1> |
| 2038 | <p><i>Precondition:</i> <tt>object</tt> is a valid pointer which |
| 2039 | either contains a null pointer or has been registered as |
| 2040 | a <tt>__weak</tt> object.</p> |
| 2041 | <p>If <tt>object</tt> is registered as a <tt>__weak</tt> object, and |
| 2042 | the last value stored into <tt>object</tt> has not yet been |
| 2043 | deallocated or begun deallocation, retains and autoreleases that value |
| 2044 | and returns it. Otherwise returns null. Equivalent to the following |
| 2045 | code:</p> |
| 2046 | <pre>id objc_loadWeak(id *object) { |
| 2047 | return objc_autorelease(objc_loadWeakRetained(object)); |
| 2048 | }</pre> |
| 2049 | <p>Must be atomic with respect to calls to <tt>objc_storeWeak</tt> |
| 2050 | on <tt>object</tt>.</p> |
| 2051 | <div class="rationale">Rationale: loading weak references would be |
| 2052 | inherently prone to race conditions without the retain.</div> |
| 2053 | </div> <!-- runtime.objc_loadWeak --> |
| 2054 | |
| 2055 | <div id="runtime.objc_loadWeakRetained"> |
| 2056 | <h1><tt>id objc_loadWeakRetained(id *object);</tt></h1> |
| 2057 | <p><i>Precondition:</i> <tt>object</tt> is a valid pointer which |
| 2058 | either contains a null pointer or has been registered as |
| 2059 | a <tt>__weak</tt> object.</p> |
| 2060 | <p>If <tt>object</tt> is registered as a <tt>__weak</tt> object, and |
| 2061 | the last value stored into <tt>object</tt> has not yet been |
| 2062 | deallocated or begun deallocation, retains that value and returns it. |
| 2063 | Otherwise returns null.</p> |
| 2064 | <p>Must be atomic with respect to calls to <tt>objc_storeWeak</tt> |
| 2065 | on <tt>object</tt>.</p> |
| 2066 | </div> <!-- runtime.objc_loadWeakRetained --> |
| 2067 | |
| 2068 | <div id="runtime.objc_moveWeak"> |
| 2069 | <h1><tt>void objc_moveWeak(id *dest, id *src);</tt></h1> |
| 2070 | <p><i>Precondition:</i> <tt>src</tt> is a valid pointer which either |
| 2071 | contains a null pointer or has been registered as a <tt>__weak</tt> |
| 2072 | object. <tt>dest</tt> is a valid pointer which has not been |
| 2073 | registered as a <tt>__weak</tt> object.</p> |
| 2074 | <p><tt>dest</tt> is initialized to be equivalent to <tt>src</tt>, |
| 2075 | potentially registering it with the runtime. <tt>src</tt> may then be |
| 2076 | left in its original state, in which case this call is equivalent |
| 2077 | to <a href="#runtime.objc_copyWeak"><tt>objc_copyWeak</tt></a>, or it |
| 2078 | may be left as null.</p> |
| 2079 | <p>Must be atomic with respect to calls to <tt>objc_storeWeak</tt> |
| 2080 | on <tt>src</tt>.</p> |
| 2081 | </div> <!-- runtime.objc_moveWeak --> |
| 2082 | |
John McCall | 085d09d | 2011-06-19 10:12:24 +0000 | [diff] [blame] | 2083 | <div id="runtime.objc_release"> |
| 2084 | <h1><tt>void objc_release(id value);</tt></h1> |
| 2085 | <p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a |
| 2086 | valid object.</p> |
| 2087 | <p>If <tt>value</tt> is null, this call has no effect. Otherwise, it |
| 2088 | performs a release operation exactly as if the object had been sent |
| 2089 | the <tt>release</tt> message.</p> |
| 2090 | </div> <!-- runtime.objc_release --> |
| 2091 | |
John McCall | 98a48cf | 2011-06-19 09:36:02 +0000 | [diff] [blame] | 2092 | <div id="runtime.objc_retain"> |
| 2093 | <h1><tt>id objc_retain(id value);</tt></h1> |
| 2094 | <p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a |
| 2095 | valid object.</p> |
| 2096 | <p>If <tt>value</tt> is null, this call has no effect. Otherwise, it |
| 2097 | performs a retain operation exactly as if the object had been sent |
| 2098 | the <tt>retain</tt> message.</p> |
| 2099 | <p>Always returns <tt>value</tt>.</p> |
| 2100 | </div> <!-- runtime.objc_retain --> |
| 2101 | |
| 2102 | <div id="runtime.objc_retainAutorelease"> |
| 2103 | <h1><tt>id objc_retainAutorelease(id value);</tt></h1> |
| 2104 | <p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a |
| 2105 | valid object.</p> |
| 2106 | <p>If <tt>value</tt> is null, this call has no effect. Otherwise, it |
| 2107 | performs a retain operation followed by an autorelease operation. |
| 2108 | Equivalent to the following code:</p> |
| 2109 | <pre>id objc_retainAutorelease(id value) { |
| 2110 | return objc_autorelease(objc_retain(value)); |
| 2111 | }</pre> |
| 2112 | <p>Always returns <tt>value</tt>.</p> |
| 2113 | </div> <!-- runtime.objc_retainAutorelease --> |
| 2114 | |
| 2115 | <div id="runtime.objc_retainAutoreleaseReturnValue"> |
| 2116 | <h1><tt>id objc_retainAutoreleaseReturnValue(id value);</tt></h1> |
| 2117 | <p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a |
| 2118 | valid object.</p> |
| 2119 | <p>If <tt>value</tt> is null, this call has no effect. Otherwise, it |
| 2120 | performs a retain operation followed by the operation described in |
| 2121 | <a href="#runtime.objc_autoreleaseReturnValue"><tt>objc_autoreleaseReturnValue</tt></a>. |
| 2122 | Equivalent to the following code:</p> |
| 2123 | <pre>id objc_retainAutoreleaseReturnValue(id value) { |
| 2124 | return objc_autoreleaseReturnValue(objc_retain(value)); |
| 2125 | }</pre> |
| 2126 | <p>Always returns <tt>value</tt>.</p> |
| 2127 | </div> <!-- runtime.objc_retainAutoreleaseReturnValue --> |
| 2128 | |
| 2129 | <div id="runtime.objc_retainAutoreleasedReturnValue"> |
| 2130 | <h1><tt>id objc_retainAutoreleasedReturnValue(id value);</tt></h1> |
| 2131 | <p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a |
| 2132 | valid object.</p> |
| 2133 | <p>If <tt>value</tt> is null, this call has no effect. Otherwise, it |
| 2134 | attempts to accept a hand off of a retain count from a call to |
| 2135 | <a href="#runtime.objc_autoreleaseReturnValue"><tt>objc_autoreleaseReturnValue</tt></a> |
| 2136 | on <tt>value</tt> in a recently-called function or something it |
| 2137 | calls. If that fails, it performs a retain operation exactly |
| 2138 | like <a href="#runtime.objc_retain"><tt>objc_retain</tt></a>.</p> |
| 2139 | <p>Always returns <tt>value</tt>.</p> |
| 2140 | </div> <!-- runtime.objc_retainAutoreleasedReturnValue --> |
| 2141 | |
| 2142 | <div id="runtime.objc_retainBlock"> |
| 2143 | <h1><tt>id objc_retainBlock(id value);</tt></h1> |
| 2144 | <p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a |
| 2145 | valid block object.</p> |
| 2146 | <p>If <tt>value</tt> is null, this call has no effect. Otherwise, if |
| 2147 | the block pointed to by <tt>value</tt> is still on the stack, it is |
| 2148 | copied to the heap and the address of the copy is returned. Otherwise |
| 2149 | a retain operation is performed on the block exactly as if it had been |
| 2150 | sent the <tt>retain</tt> message.</p> |
| 2151 | </div> <!-- runtime.objc_retainBlock --> |
| 2152 | |
John McCall | 98a48cf | 2011-06-19 09:36:02 +0000 | [diff] [blame] | 2153 | <div id="runtime.objc_storeStrong"> |
| 2154 | <h1><tt>id objc_storeStrong(id *object, id value);</tt></h1> |
| 2155 | <p><i>Precondition:</i> <tt>object</tt> is a valid pointer to |
| 2156 | a <tt>__strong</tt> object which is adequately aligned for a |
| 2157 | pointer. <tt>value</tt> is null or a pointer to a valid object.</p> |
| 2158 | <p>Performs the complete sequence for assigning to a <tt>__strong</tt> |
| 2159 | object of non-block type. Equivalent to the following code:</p> |
| 2160 | <pre>id objc_storeStrong(id *object, id value) { |
| 2161 | value = [value retain]; |
| 2162 | id oldValue = *object; |
| 2163 | *object = value; |
| 2164 | [oldValue release]; |
| 2165 | return value; |
| 2166 | }</pre> |
| 2167 | <p>Always returns <tt>value</tt>.</p> |
| 2168 | </div> <!-- runtime.objc_storeStrong --> |
| 2169 | |
| 2170 | <div id="runtime.objc_storeWeak"> |
| 2171 | <h1><tt>id objc_storeWeak(id *object, id value);</tt></h1> |
| 2172 | <p><i>Precondition:</i> <tt>object</tt> is a valid pointer which |
| 2173 | either contains a null pointer or has been registered as |
| 2174 | a <tt>__weak</tt> object. <tt>value</tt> is null or a pointer to a |
| 2175 | valid object.</p> |
| 2176 | <p>If <tt>value</tt> is a null pointer or the object to which it |
| 2177 | points has begun deallocation, <tt>object</tt> is assigned null |
| 2178 | and unregistered as a <tt>__weak</tt> object. Otherwise, |
| 2179 | <tt>object</tt> is registered as a <tt>__weak</tt> object or has its |
| 2180 | registration updated to point to <tt>value</tt>.</p> |
| 2181 | <p>Returns the value of <tt>object</tt> after the call.</p> |
| 2182 | </div> <!-- runtime.objc_storeWeak --> |
| 2183 | |
| 2184 | </div> <!-- runtime --> |
John McCall | 8246702 | 2011-06-15 21:21:53 +0000 | [diff] [blame] | 2185 | </div> <!-- root --> |
| 2186 | </body> |
| 2187 | </html> |