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