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