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