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