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