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