AutomaticReferenceCounting.rst

.. FIXME: move to the stylesheet or Sphinx plugin

.. raw:: html

  <style>
    .arc-term { font-style: italic; font-weight: bold; }
    .revision { font-style: italic; }
    .when-revised { font-weight: bold; font-style: normal; }

    /*
     * Automatic numbering is described in this article:
     * http://dev.opera.com/articles/view/automatic-numbering-with-css-counters/
     */
    /*
     * Automatic numbering for the TOC.
     * This is wrong from the semantics point of view, since it is an ordered
     * list, but uses "ul" tag.
     */
    div#contents.contents.local ul {
      counter-reset: toc-section;
      list-style-type: none;
    }
    div#contents.contents.local ul li {
      counter-increment: toc-section;
      background: none; // Remove bullets
    }
    div#contents.contents.local ul li a.reference:before {
      content: counters(toc-section, ".") " ";
    }

    /* Automatic numbering for the body. */
    body {
      counter-reset: section subsection subsubsection;
    }
    .section h2 {
      counter-reset: subsection subsubsection;
      counter-increment: section;
    }
    .section h2 a.toc-backref:before {
      content: counter(section) " ";
    }
    .section h3 {
      counter-reset: subsubsection;
      counter-increment: subsection;
    }
    .section h3 a.toc-backref:before {
      content: counter(section) "." counter(subsection) " ";
    }
    .section h4 {
      counter-increment: subsubsection;
    }
    .section h4 a.toc-backref:before {
      content: counter(section) "." counter(subsection) "." counter(subsubsection) " ";
    }
  </style>

.. role:: arc-term
.. role:: revision
.. role:: when-revised

==============================================
Objective-C Automatic Reference Counting (ARC)
==============================================

.. contents::
   :local:

.. _arc.meta:

About this document
===================

.. _arc.meta.purpose:

Purpose
-------

The first and primary purpose of this document is to serve as a complete
technical specification of Automatic Reference Counting.  Given a core
Objective-C compiler and runtime, it should be possible to write a compiler and
runtime which implements these new semantics.

The secondary purpose is to act as a rationale for why ARC was designed in this
way.  This should remain tightly focused on the technical design and should not
stray into marketing speculation.

.. _arc.meta.background:

Background
----------

This document assumes a basic familiarity with C.

:arc-term:`Blocks` are a C language extension for creating anonymous functions.
Users interact with and transfer block objects using :arc-term:`block
pointers`, which are represented like a normal pointer.  A block may capture
values from local variables; when this occurs, memory must be dynamically
allocated.  The initial allocation is done on the stack, but the runtime
provides a ``Block_copy`` function which, given a block pointer, either copies
the underlying block object to the heap, setting its reference count to 1 and
returning the new block pointer, or (if the block object is already on the
heap) increases its reference count by 1.  The paired function is
``Block_release``, which decreases the reference count by 1 and destroys the
object if the count reaches zero and is on the heap.

Objective-C is a set of language extensions, significant enough to be
considered a different language.  It is a strict superset of C.  The extensions
can also be imposed on C++, producing a language called Objective-C++.  The
primary feature is a single-inheritance object system; we briefly describe the
modern dialect.

Objective-C defines a new type kind, collectively called the :arc-term:`object
pointer types`.  This kind has two notable builtin members, ``id`` and
``Class``; ``id`` is the final supertype of all object pointers.  The validity
of conversions between object pointer types is not checked at runtime.  Users
may define :arc-term:`classes`; each class is a type, and the pointer to that
type is an object pointer type.  A class may have a superclass; its pointer
type is a subtype of its superclass's pointer type.  A class has a set of
:arc-term:`ivars`, fields which appear on all instances of that class.  For
every class *T* there's an associated metaclass; it has no fields, its
superclass is the metaclass of *T*'s superclass, and its metaclass is a global
class.  Every class has a global object whose class is the class's metaclass;
metaclasses have no associated type, so pointers to this object have type
``Class``.

A class declaration (``@interface``) declares a set of :arc-term:`methods`.  A
method has a return type, a list of argument types, and a :arc-term:`selector`:
a name like ``foo:bar:baz:``, where the number of colons corresponds to the
number of formal arguments.  A method may be an instance method, in which case
it can be invoked on objects of the class, or a class method, in which case it
can be invoked on objects of the metaclass.  A method may be invoked by
providing an object (called the :arc-term:`receiver`) and a list of formal
arguments interspersed with the selector, like so:

.. code-block:: objc

  [receiver foo: fooArg bar: barArg baz: bazArg]

This looks in the dynamic class of the receiver for a method with this name,
then in that class's superclass, etc., until it finds something it can execute.
The receiver "expression" may also be the name of a class, in which case the
actual receiver is the class object for that class, or (within method
definitions) it may be ``super``, in which case the lookup algorithm starts
with the static superclass instead of the dynamic class.  The actual methods
dynamically found in a class are not those declared in the ``@interface``, but
those defined in a separate ``@implementation`` declaration; however, when
compiling a call, typechecking is done based on the methods declared in the
``@interface``.

Method declarations may also be grouped into :arc-term:`protocols`, which are not
inherently associated with any class, but which classes may claim to follow.
Object pointer types may be qualified with additional protocols that the object
is known to support.

:arc-term:`Class extensions` are collections of ivars and methods, designed to
allow a class's ``@interface`` to be split across multiple files; however,
there is still a primary implementation file which must see the
``@interface``\ s of all class extensions.  :arc-term:`Categories` allow
methods (but not ivars) to be declared *post hoc* on an arbitrary class; the
methods in the category's ``@implementation`` will be dynamically added to that
class's method tables which the category is loaded at runtime, replacing those
methods in case of a collision.

In the standard environment, objects are allocated on the heap, and their
lifetime is manually managed using a reference count.  This is done using two
instance methods which all classes are expected to implement: ``retain``
increases the object's reference count by 1, whereas ``release`` decreases it
by 1 and calls the instance method ``dealloc`` if the count reaches 0.  To
simplify certain operations, there is also an :arc-term:`autorelease pool`, a
thread-local list of objects to call ``release`` on later; an object can be
added to this pool by calling ``autorelease`` on it.

Block pointers may be converted to type ``id``; block objects are laid out in a
way that makes them compatible with Objective-C objects.  There is a builtin
class that all block objects are considered to be objects of; this class
implements ``retain`` by adjusting the reference count, not by calling
``Block_copy``.

.. _arc.meta.evolution:

Evolution
---------

ARC is under continual evolution, and this document must be updated as the
language progresses.

If a change increases the expressiveness of the language, for example by
lifting a restriction or by adding new syntax, the change will be annotated
with a revision marker, like so:

  ARC applies to Objective-C pointer types, block pointer types, and
  :when-revised:`[beginning Apple 8.0, LLVM 3.8]` :revision:`BPTRs declared
  within` ``extern "BCPL"`` blocks.

For now, it is sensible to version this document by the releases of its sole
implementation (and its host project), clang.  "LLVM X.Y" refers to an
open-source release of clang from the LLVM project.  "Apple X.Y" refers to an
Apple-provided release of the Apple LLVM Compiler.  Other organizations that
prepare their own, separately-versioned clang releases and wish to maintain
similar information in this document should send requests to cfe-dev.

If a change decreases the expressiveness of the language, for example by
imposing a new restriction, this should be taken as an oversight in the
original specification and something to be avoided in all versions.  Such
changes are generally to be avoided.

.. _arc.general:

General
=======

Automatic Reference Counting implements automatic memory management for
Objective-C objects and blocks, freeing the programmer from the need to
explicitly insert retains and releases.  It does not provide a cycle collector;
users must explicitly manage the lifetime of their objects, breaking cycles
manually or with weak or unsafe references.

ARC may be explicitly enabled with the compiler flag ``-fobjc-arc``.  It may
also be explicitly disabled with the compiler flag ``-fno-objc-arc``.  The last
of these two flags appearing on the compile line "wins".

If ARC is enabled, ``__has_feature(objc_arc)`` will expand to 1 in the
preprocessor.  For more information about ``__has_feature``, see the
:ref:`language extensions <langext-__has_feature-__has_extension>` document.

.. _arc.objects:

Retainable object pointers
==========================

This section describes retainable object pointers, their basic operations, and
the restrictions imposed on their use under ARC.  Note in particular that it
covers the rules for pointer *values* (patterns of bits indicating the location
of a pointed-to object), not pointer *objects* (locations in memory which store
pointer values).  The rules for objects are covered in the next section.

A :arc-term:`retainable object pointer` (or "retainable pointer") is a value of
a :arc-term:`retainable object pointer type` ("retainable type").  There are
three kinds of retainable object pointer types:

* block pointers (formed by applying the caret (``^``) declarator sigil to a
  function type)
* Objective-C object pointers (``id``, ``Class``, ``NSFoo*``, etc.)
* typedefs marked with ``__attribute__((NSObject))``

Other pointer types, such as ``int*`` and ``CFStringRef``, are not subject to
ARC's semantics and restrictions.

.. admonition:: Rationale

  We are not at liberty to require all code to be recompiled with ARC;
  therefore, ARC must interoperate with Objective-C code which manages retains
  and releases manually.  In general, there are three requirements in order for
  a compiler-supported reference-count system to provide reliable
  interoperation:

  * The type system must reliably identify which objects are to be managed.  An
    ``int*`` might be a pointer to a ``malloc``'ed array, or it might be an
    interior pointer to such an array, or it might point to some field or local
    variable.  In contrast, values of the retainable object pointer types are
    never interior.

  * The type system must reliably indicate how to manage objects of a type.
    This usually means that the type must imply a procedure for incrementing
    and decrementing retain counts.  Supporting single-ownership objects
    requires a lot more explicit mediation in the language.

  * There must be reliable conventions for whether and when "ownership" is
    passed between caller and callee, for both arguments and return values.
    Objective-C methods follow such a convention very reliably, at least for
    system libraries on Mac OS X, and functions always pass objects at +0.  The
    C-based APIs for Core Foundation objects, on the other hand, have much more
    varied transfer semantics.

The use of ``__attribute__((NSObject))`` typedefs is not recommended.  If it's
absolutely necessary to use this attribute, be very explicit about using the
typedef, and do not assume that it will be preserved by language features like
``__typeof`` and C++ template argument substitution.

.. admonition:: Rationale

  Any compiler operation which incidentally strips type "sugar" from a type
  will yield a type without the attribute, which may result in unexpected
  behavior.

.. _arc.objects.retains:

Retain count semantics
----------------------

A retainable object pointer is either a :arc-term:`null pointer` or a pointer
to a valid object.  Furthermore, if it has block pointer type and is not
``null`` then it must actually be a pointer to a block object, and if it has
``Class`` type (possibly protocol-qualified) then it must actually be a pointer
to a class object.  Otherwise ARC does not enforce the Objective-C type system
as long as the implementing methods follow the signature of the static type.
It is undefined behavior if ARC is exposed to an invalid pointer.

For ARC's purposes, a valid object is one with "well-behaved" retaining
operations.  Specifically, the object must be laid out such that the
Objective-C message send machinery can successfully send it the following
messages:

* ``retain``, taking no arguments and returning a pointer to the object.
* ``release``, taking no arguments and returning ``void``.
* ``autorelease``, taking no arguments and returning a pointer to the object.

The behavior of these methods is constrained in the following ways.  The term
:arc-term:`high-level semantics` is an intentionally vague term; the intent is
that programmers must implement these methods in a way such that the compiler,
modifying code in ways it deems safe according to these constraints, will not
violate their requirements.  For example, if the user puts logging statements
in ``retain``, they should not be surprised if those statements are executed
more or less often depending on optimization settings.  These constraints are
not exhaustive of the optimization opportunities: values held in local
variables are subject to additional restrictions, described later in this
document.

It is undefined behavior if a computation history featuring a send of
``retain`` followed by a send of ``release`` to the same object, with no
intervening ``release`` on that object, is not equivalent under the high-level
semantics to a computation history in which these sends are removed.  Note that
this implies that these methods may not raise exceptions.

It is undefined behavior if a computation history features any use whatsoever
of an object following the completion of a send of ``release`` that is not
preceded by a send of ``retain`` to the same object.

The behavior of ``autorelease`` must be equivalent to sending ``release`` when
one of the autorelease pools currently in scope is popped.  It may not throw an
exception.

When the semantics call for performing one of these operations on a retainable
object pointer, if that pointer is ``null`` then the effect is a no-op.

All of the semantics described in this document are subject to additional
:ref:`optimization rules <arc.optimization>` which permit the removal or
optimization of operations based on local knowledge of data flow.  The
semantics describe the high-level behaviors that the compiler implements, not
an exact sequence of operations that a program will be compiled into.

.. _arc.objects.operands:

Retainable object pointers as operands and arguments
----------------------------------------------------

In general, ARC does not perform retain or release operations when simply using
a retainable object pointer as an operand within an expression.  This includes:

* loading a retainable pointer from an object with non-weak :ref:`ownership
  <arc.ownership>`,
* passing a retainable pointer as an argument to a function or method, and
* receiving a retainable pointer as the result of a function or method call.

.. admonition:: Rationale

  While this might seem uncontroversial, it is actually unsafe when multiple
  expressions are evaluated in "parallel", as with binary operators and calls,
  because (for example) one expression might load from an object while another
  writes to it.  However, C and C++ already call this undefined behavior
  because the evaluations are unsequenced, and ARC simply exploits that here to
  avoid needing to retain arguments across a large number of calls.

The remainder of this section describes exceptions to these rules, how those
exceptions are detected, and what those exceptions imply semantically.

.. _arc.objects.operands.consumed:

Consumed parameters
^^^^^^^^^^^^^^^^^^^

A function or method parameter of retainable object pointer type may be marked
as :arc-term:`consumed`, signifying that the callee expects to take ownership
of a +1 retain count.  This is done by adding the ``ns_consumed`` attribute to
the parameter declaration, like so:

.. code-block:: objc

  void foo(__attribute((ns_consumed)) id x);
  - (void) foo: (id) __attribute((ns_consumed)) x;

This attribute is part of the type of the function or method, not the type of
the parameter.  It controls only how the argument is passed and received.

When passing such an argument, ARC retains the argument prior to making the
call.

When receiving such an argument, ARC releases the argument at the end of the
function, subject to the usual optimizations for local values.

.. admonition:: Rationale

  This formalizes direct transfers of ownership from a caller to a callee.  The
  most common scenario here is passing the ``self`` parameter to ``init``, but
  it is useful to generalize.  Typically, local optimization will remove any
  extra retains and releases: on the caller side the retain will be merged with
  a +1 source, and on the callee side the release will be rolled into the
  initialization of the parameter.

The implicit ``self`` parameter of a method may be marked as consumed by adding
``__attribute__((ns_consumes_self))`` to the method declaration.  Methods in
the ``init`` :ref:`family <arc.method-families>` are treated as if they were
implicitly marked with this attribute.

It is undefined behavior if an Objective-C message send to a method with
``ns_consumed`` parameters (other than self) is made with a null receiver.  It
is undefined behavior if the method to which an Objective-C message send
statically resolves to has a different set of ``ns_consumed`` parameters than
the method it dynamically resolves to.  It is undefined behavior if a block or
function call is made through a static type with a different set of
``ns_consumed`` parameters than the implementation of the called block or
function.

.. admonition:: Rationale

  Consumed parameters with null receiver are a guaranteed leak.  Mismatches
  with consumed parameters will cause over-retains or over-releases, depending
  on the direction.  The rule about function calls is really just an
  application of the existing C/C++ rule about calling functions through an
  incompatible function type, but it's useful to state it explicitly.

.. _arc.object.operands.retained-return-values:

Retained return values
^^^^^^^^^^^^^^^^^^^^^^

A function or method which returns a retainable object pointer type may be
marked as returning a retained value, signifying that the caller expects to take
ownership of a +1 retain count.  This is done by adding the
``ns_returns_retained`` attribute to the function or method declaration, like
so:

.. code-block:: objc

  id foo(void) __attribute((ns_returns_retained));
  - (id) foo __attribute((ns_returns_retained));

This attribute is part of the type of the function or method.

When returning from such a function or method, ARC retains the value at the
point of evaluation of the return statement, before leaving all local scopes.

When receiving a return result from such a function or method, ARC releases the
value at the end of the full-expression it is contained within, subject to the
usual optimizations for local values.

.. admonition:: Rationale

  This formalizes direct transfers of ownership from a callee to a caller.  The
  most common scenario this models is the retained return from ``init``,
  ``alloc``, ``new``, and ``copy`` methods, but there are other cases in the
  frameworks.  After optimization there are typically no extra retains and
  releases required.

Methods in the ``alloc``, ``copy``, ``init``, ``mutableCopy``, and ``new``
:ref:`families <arc.method-families>` are implicitly marked
``__attribute__((ns_returns_retained))``.  This may be suppressed by explicitly
marking the method ``__attribute__((ns_returns_not_retained))``.

It is undefined behavior if the method to which an Objective-C message send
statically resolves has different retain semantics on its result from the
method it dynamically resolves to.  It is undefined behavior if a block or
function call is made through a static type with different retain semantics on
its result from the implementation of the called block or function.

.. admonition:: Rationale

  Mismatches with returned results will cause over-retains or over-releases,
  depending on the direction.  Again, the rule about function calls is really
  just an application of the existing C/C++ rule about calling functions
  through an incompatible function type.

.. _arc.objects.operands.unretained-returns:

Unretained return values
^^^^^^^^^^^^^^^^^^^^^^^^

A method or function which returns a retainable object type but does not return
a retained value must ensure that the object is still valid across the return
boundary.

When returning from such a function or method, ARC retains the value at the
point of evaluation of the return statement, then leaves all local scopes, and
then balances out the retain while ensuring that the value lives across the
call boundary.  In the worst case, this may involve an ``autorelease``, but
callers must not assume that the value is actually in the autorelease pool.

ARC performs no extra mandatory work on the caller side, although it may elect
to do something to shorten the lifetime of the returned value.

.. admonition:: Rationale

  It is common in non-ARC code to not return an autoreleased value; therefore
  the convention does not force either path.  It is convenient to not be
  required to do unnecessary retains and autoreleases; this permits
  optimizations such as eliding retain/autoreleases when it can be shown that
  the original pointer will still be valid at the point of return.

A method or function may be marked with
``__attribute__((ns_returns_autoreleased))`` to indicate that it returns a
pointer which is guaranteed to be valid at least as long as the innermost
autorelease pool.  There are no additional semantics enforced in the definition
of such a method; it merely enables optimizations in callers.

.. _arc.objects.operands.casts:

Bridged casts
^^^^^^^^^^^^^

A :arc-term:`bridged cast` is a C-style cast annotated with one of three
keywords:

* ``(__bridge T) op`` casts the operand to the destination type ``T``.  If
  ``T`` is a retainable object pointer type, then ``op`` must have a
  non-retainable pointer type.  If ``T`` is a non-retainable pointer type,
  then ``op`` must have a retainable object pointer type.  Otherwise the cast
  is ill-formed.  There is no transfer of ownership, and ARC inserts no retain
  operations.
* ``(__bridge_retained T) op`` casts the operand, which must have retainable
  object pointer type, to the destination type, which must be a non-retainable
  pointer type.  ARC retains the value, subject to the usual optimizations on
  local values, and the recipient is responsible for balancing that +1.
* ``(__bridge_transfer T) op`` casts the operand, which must have
  non-retainable pointer type, to the destination type, which must be a
  retainable object pointer type.  ARC will release the value at the end of
  the enclosing full-expression, subject to the usual optimizations on local
  values.

These casts are required in order to transfer objects in and out of ARC
control; see the rationale in the section on :ref:`conversion of retainable
object pointers <arc.objects.restrictions.conversion>`.

Using a ``__bridge_retained`` or ``__bridge_transfer`` cast purely to convince
ARC to emit an unbalanced retain or release, respectively, is poor form.

.. _arc.objects.restrictions:

Restrictions
------------

.. _arc.objects.restrictions.conversion:

Conversion of retainable object pointers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In general, a program which attempts to implicitly or explicitly convert a
value of retainable object pointer type to any non-retainable type, or
vice-versa, is ill-formed.  For example, an Objective-C object pointer shall
not be converted to ``void*``.  As an exception, cast to ``intptr_t`` is
allowed because such casts are not transferring ownership.  The :ref:`bridged
casts <arc.objects.operands.casts>` may be used to perform these conversions
where necessary.

.. admonition:: Rationale

  We cannot ensure the correct management of the lifetime of objects if they
  may be freely passed around as unmanaged types.  The bridged casts are
  provided so that the programmer may explicitly describe whether the cast
  transfers control into or out of ARC.

However, the following exceptions apply.

.. _arc.objects.restrictions.conversion.with.known.semantics:

Conversion to retainable object pointer type of expressions with known semantics
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

:when-revised:`[beginning Apple 4.0, LLVM 3.1]`
:revision:`These exceptions have been greatly expanded; they previously applied
only to a much-reduced subset which is difficult to categorize but which
included null pointers, message sends (under the given rules), and the various
global constants.`

An unbridged conversion to a retainable object pointer type from a type other
than a retainable object pointer type is ill-formed, as discussed above, unless
the operand of the cast has a syntactic form which is known retained, known
unretained, or known retain-agnostic.

An expression is :arc-term:`known retain-agnostic` if it is:

* an Objective-C string literal,
* a load from a ``const`` system global variable of :ref:`C retainable pointer
  type <arc.misc.c-retainable>`, or
* a null pointer constant.

An expression is :arc-term:`known unretained` if it is an rvalue of :ref:`C
retainable pointer type <arc.misc.c-retainable>` and it is:

* a direct call to a function, and either that function has the
  ``cf_returns_not_retained`` attribute or it is an :ref:`audited
  <arc.misc.c-retainable.audit>` function that does not have the
  ``cf_returns_retained`` attribute and does not follow the create/copy naming
  convention,
* a message send, and the declared method either has the
  ``cf_returns_not_retained`` attribute or it has neither the
  ``cf_returns_retained`` attribute nor a :ref:`selector family
  <arc.method-families>` that implies a retained result.

An expression is :arc-term:`known retained` if it is an rvalue of :ref:`C
retainable pointer type <arc.misc.c-retainable>` and it is:

* a message send, and the declared method either has the
  ``cf_returns_retained`` attribute, or it does not have the
  ``cf_returns_not_retained`` attribute but it does have a :ref:`selector
  family <arc.method-families>` that implies a retained result.

Furthermore:

* a comma expression is classified according to its right-hand side,
* a statement expression is classified according to its result expression, if
  it has one,
* an lvalue-to-rvalue conversion applied to an Objective-C property lvalue is
  classified according to the underlying message send, and
* a conditional operator is classified according to its second and third
  operands, if they agree in classification, or else the other if one is known
  retain-agnostic.

If the cast operand is known retained, the conversion is treated as a
``__bridge_transfer`` cast.  If the cast operand is known unretained or known
retain-agnostic, the conversion is treated as a ``__bridge`` cast.

.. admonition:: Rationale

  Bridging casts are annoying.  Absent the ability to completely automate the
  management of CF objects, however, we are left with relatively poor attempts
  to reduce the need for a glut of explicit bridges.  Hence these rules.

  We've so far consciously refrained from implicitly turning retained CF
  results from function calls into ``__bridge_transfer`` casts.  The worry is
  that some code patterns  ---  for example, creating a CF value, assigning it
  to an ObjC-typed local, and then calling ``CFRelease`` when done  ---  are a
  bit too likely to be accidentally accepted, leading to mysterious behavior.

.. _arc.objects.restrictions.conversion-exception-contextual:

Conversion from retainable object pointer type in certain contexts
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

:when-revised:`[beginning Apple 4.0, LLVM 3.1]`

If an expression of retainable object pointer type is explicitly cast to a
:ref:`C retainable pointer type <arc.misc.c-retainable>`, the program is
ill-formed as discussed above unless the result is immediately used:

* to initialize a parameter in an Objective-C message send where the parameter
  is not marked with the ``cf_consumed`` attribute, or
* to initialize a parameter in a direct call to an
  :ref:`audited <arc.misc.c-retainable.audit>` function where the parameter is
  not marked with the ``cf_consumed`` attribute.

.. admonition:: Rationale

  Consumed parameters are left out because ARC would naturally balance them
  with a retain, which was judged too treacherous.  This is in part because
  several of the most common consuming functions are in the ``Release`` family,
  and it would be quite unfortunate for explicit releases to be silently
  balanced out in this way.

.. _arc.ownership:

Ownership qualification
=======================

This section describes the behavior of *objects* of retainable object pointer
type; that is, locations in memory which store retainable object pointers.

A type is a :arc-term:`retainable object owner type` if it is a retainable
object pointer type or an array type whose element type is a retainable object
owner type.

An :arc-term:`ownership qualifier` is a type qualifier which applies only to
retainable object owner types.  An array type is ownership-qualified according
to its element type, and adding an ownership qualifier to an array type so
qualifies its element type.

A program is ill-formed if it attempts to apply an ownership qualifier to a
type which is already ownership-qualified, even if it is the same qualifier.
There is a single exception to this rule: an ownership qualifier may be applied
to a substituted template type parameter, which overrides the ownership
qualifier provided by the template argument.

When forming a function type, the result type is adjusted so that any
top-level ownership qualifier is deleted.

Except as described under the :ref:`inference rules <arc.ownership.inference>`,
a program is ill-formed if it attempts to form a pointer or reference type to a
retainable object owner type which lacks an ownership qualifier.

.. admonition:: Rationale

  These rules, together with the inference rules, ensure that all objects and
  lvalues of retainable object pointer type have an ownership qualifier.  The
  ability to override an ownership qualifier during template substitution is
  required to counteract the :ref:`inference of __strong for template type
  arguments <arc.ownership.inference.template.arguments>`.  Ownership qualifiers
  on return types are dropped because they serve no purpose there except to
  cause spurious problems with overloading and templates.

There are four ownership qualifiers:

* ``__autoreleasing``
* ``__strong``
* ``__unsafe_unretained``
* ``__weak``

A type is :arc-term:`nontrivially ownership-qualified` if it is qualified with
``__autoreleasing``, ``__strong``, or ``__weak``.

.. _arc.ownership.spelling:

Spelling
--------

The names of the ownership qualifiers are reserved for the implementation.  A
program may not assume that they are or are not implemented with macros, or
what those macros expand to.

An ownership qualifier may be written anywhere that any other type qualifier
may be written.

If an ownership qualifier appears in the *declaration-specifiers*, the
following rules apply:

* if the type specifier is a retainable object owner type, the qualifier
  initially applies to that type;

* otherwise, if the outermost non-array declarator is a pointer
  or block pointer declarator, the qualifier initially applies to
  that type;

* otherwise the program is ill-formed.

* If the qualifier is so applied at a position in the declaration
  where the next-innermost declarator is a function declarator, and
  there is an block declarator within that function declarator, then
  the qualifier applies instead to that block declarator and this rule
  is considered afresh beginning from the new position.

If an ownership qualifier appears on the declarator name, or on the declared
object, it is applied to the innermost pointer or block-pointer type.

If an ownership qualifier appears anywhere else in a declarator, it applies to
the type there.

.. admonition:: Rationale

  Ownership qualifiers are like ``const`` and ``volatile`` in the sense
  that they may sensibly apply at multiple distinct positions within a
  declarator.  However, unlike those qualifiers, there are many
  situations where they are not meaningful, and so we make an effort
  to "move" the qualifier to a place where it will be meaningful.  The
  general goal is to allow the programmer to write, say, ``__strong``
  before the entire declaration and have it apply in the leftmost
  sensible place.

.. _arc.ownership.spelling.property:

Property declarations
^^^^^^^^^^^^^^^^^^^^^

A property of retainable object pointer type may have ownership.  If the
property's type is ownership-qualified, then the property has that ownership.
If the property has one of the following modifiers, then the property has the
corresponding ownership.  A property is ill-formed if it has conflicting
sources of ownership, or if it has redundant ownership modifiers, or if it has
``__autoreleasing`` ownership.

* ``assign`` implies ``__unsafe_unretained`` ownership.
* ``copy`` implies ``__strong`` ownership, as well as the usual behavior of
  copy semantics on the setter.
* ``retain`` implies ``__strong`` ownership.
* ``strong`` implies ``__strong`` ownership.
* ``unsafe_unretained`` implies ``__unsafe_unretained`` ownership.
* ``weak`` implies ``__weak`` ownership.

With the exception of ``weak``, these modifiers are available in non-ARC
modes.

A property's specified ownership is preserved in its metadata, but otherwise
the meaning is purely conventional unless the property is synthesized.  If a
property is synthesized, then the :arc-term:`associated instance variable` is
the instance variable which is named, possibly implicitly, by the
``@synthesize`` declaration.  If the associated instance variable already
exists, then its ownership qualification must equal the ownership of the
property; otherwise, the instance variable is created with that ownership
qualification.

A property of retainable object pointer type which is synthesized without a
source of ownership has the ownership of its associated instance variable, if it
already exists; otherwise, :when-revised:`[beginning Apple 3.1, LLVM 3.1]`
:revision:`its ownership is implicitly` ``strong``.  Prior to this revision, it
was ill-formed to synthesize such a property.

.. admonition:: Rationale

  Using ``strong`` by default is safe and consistent with the generic ARC rule
  about :ref:`inferring ownership <arc.ownership.inference.variables>`.  It is,
  unfortunately, inconsistent with the non-ARC rule which states that such
  properties are implicitly ``assign``.  However, that rule is clearly
  untenable in ARC, since it leads to default-unsafe code.  The main merit to
  banning the properties is to avoid confusion with non-ARC practice, which did
  not ultimately strike us as sufficient to justify requiring extra syntax and
  (more importantly) forcing novices to understand ownership rules just to
  declare a property when the default is so reasonable.  Changing the rule away
  from non-ARC practice was acceptable because we had conservatively banned the
  synthesis in order to give ourselves exactly this leeway.

Applying ``__attribute__((NSObject))`` to a property not of retainable object
pointer type has the same behavior it does outside of ARC: it requires the
property type to be some sort of pointer and permits the use of modifiers other
than ``assign``.  These modifiers only affect the synthesized getter and
setter; direct accesses to the ivar (even if synthesized) still have primitive
semantics, and the value in the ivar will not be automatically released during
deallocation.

.. _arc.ownership.semantics:

Semantics
---------

There are five :arc-term:`managed operations` which may be performed on an
object of retainable object pointer type.  Each qualifier specifies different
semantics for each of these operations.  It is still undefined behavior to
access an object outside of its lifetime.

A load or store with "primitive semantics" has the same semantics as the
respective operation would have on an ``void*`` lvalue with the same alignment
and non-ownership qualification.

:arc-term:`Reading` occurs when performing a lvalue-to-rvalue conversion on an
object lvalue.

* For ``__weak`` objects, the current pointee is retained and then released at
  the end of the current full-expression.  This must execute atomically with
  respect to assignments and to the final release of the pointee.
* For all other objects, the lvalue is loaded with primitive semantics.

:arc-term:`Assignment` occurs when evaluating an assignment operator.  The
semantics vary based on the qualification:

* For ``__strong`` objects, the new pointee is first retained; second, the
  lvalue is loaded with primitive semantics; third, the new pointee is stored
  into the lvalue with primitive semantics; and finally, the old pointee is
  released.  This is not performed atomically; external synchronization must be
  used to make this safe in the face of concurrent loads and stores.
* For ``__weak`` objects, the lvalue is updated to point to the new pointee,
  unless the new pointee is an object currently undergoing deallocation, in
  which case the lvalue is updated to a null pointer.  This must execute
  atomically with respect to other assignments to the object, to reads from the
  object, and to the final release of the new pointee.
* For ``__unsafe_unretained`` objects, the new pointee is stored into the
  lvalue using primitive semantics.
* For ``__autoreleasing`` objects, the new pointee is retained, autoreleased,
  and stored into the lvalue using primitive semantics.

:arc-term:`Initialization` occurs when an object's lifetime begins, which
depends on its storage duration.  Initialization proceeds in two stages:

#. First, a null pointer is stored into the lvalue using primitive semantics.
   This step is skipped if the object is ``__unsafe_unretained``.
#. Second, if the object has an initializer, that expression is evaluated and
   then assigned into the object using the usual assignment semantics.

:arc-term:`Destruction` occurs when an object's lifetime ends.  In all cases it
is semantically equivalent to assigning a null pointer to the object, with the
proviso that of course the object cannot be legally read after the object's
lifetime ends.

:arc-term:`Moving` occurs in specific situations where an lvalue is "moved
from", meaning that its current pointee will be used but the object may be left
in a different (but still valid) state.  This arises with ``__block`` variables
and rvalue references in C++.  For ``__strong`` lvalues, moving is equivalent
to loading the lvalue with primitive semantics, writing a null pointer to it
with primitive semantics, and then releasing the result of the load at the end
of the current full-expression.  For all other lvalues, moving is equivalent to
reading the object.

.. _arc.ownership.restrictions:

Restrictions
------------

.. _arc.ownership.restrictions.weak:

Weak-unavailable types
^^^^^^^^^^^^^^^^^^^^^^

It is explicitly permitted for Objective-C classes to not support ``__weak``
references.  It is undefined behavior to perform an operation with weak
assignment semantics with a pointer to an Objective-C object whose class does
not support ``__weak`` references.

.. admonition:: Rationale

  Historically, it has been possible for a class to provide its own
  reference-count implementation by overriding ``retain``, ``release``, etc.
  However, weak references to an object require coordination with its class's
  reference-count implementation because, among other things, weak loads and
  stores must be atomic with respect to the final release.  Therefore, existing
  custom reference-count implementations will generally not support weak
  references without additional effort.  This is unavoidable without breaking
  binary compatibility.

A class may indicate that it does not support weak references by providing the
``objc_arc_weak_unavailable`` attribute on the class's interface declaration.  A
retainable object pointer type is **weak-unavailable** if
is a pointer to an (optionally protocol-qualified) Objective-C class ``T`` where
``T`` or one of its superclasses has the ``objc_arc_weak_unavailable``
attribute.  A program is ill-formed if it applies the ``__weak`` ownership
qualifier to a weak-unavailable type or if the value operand of a weak
assignment operation has a weak-unavailable type.

.. _arc.ownership.restrictions.autoreleasing:

Storage duration of ``__autoreleasing`` objects
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A program is ill-formed if it declares an ``__autoreleasing`` object of
non-automatic storage duration.  A program is ill-formed if it captures an
``__autoreleasing`` object in a block or, unless by reference, in a C++11
lambda.

.. admonition:: Rationale

  Autorelease pools are tied to the current thread and scope by their nature.
  While it is possible to have temporary objects whose instance variables are
  filled with autoreleased objects, there is no way that ARC can provide any
  sort of safety guarantee there.

It is undefined behavior if a non-null pointer is assigned to an
``__autoreleasing`` object while an autorelease pool is in scope and then that
object is read after the autorelease pool's scope is left.

.. _arc.ownership.restrictions.conversion.indirect:

Conversion of pointers to ownership-qualified types
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A program is ill-formed if an expression of type ``T*`` is converted,
explicitly or implicitly, to the type ``U*``, where ``T`` and ``U`` have
different ownership qualification, unless:

* ``T`` is qualified with ``__strong``, ``__autoreleasing``, or
  ``__unsafe_unretained``, and ``U`` is qualified with both ``const`` and
  ``__unsafe_unretained``; or
* either ``T`` or ``U`` is ``cv void``, where ``cv`` is an optional sequence
  of non-ownership qualifiers; or
* the conversion is requested with a ``reinterpret_cast`` in Objective-C++; or
* the conversion is a well-formed :ref:`pass-by-writeback
  <arc.ownership.restrictions.pass_by_writeback>`.

The analogous rule applies to ``T&`` and ``U&`` in Objective-C++.

.. admonition:: Rationale

  These rules provide a reasonable level of type-safety for indirect pointers,
  as long as the underlying memory is not deallocated.  The conversion to
  ``const __unsafe_unretained`` is permitted because the semantics of reads are
  equivalent across all these ownership semantics, and that's a very useful and
  common pattern.  The interconversion with ``void*`` is useful for allocating
  memory or otherwise escaping the type system, but use it carefully.
  ``reinterpret_cast`` is considered to be an obvious enough sign of taking
  responsibility for any problems.

It is undefined behavior to access an ownership-qualified object through an
lvalue of a differently-qualified type, except that any non-``__weak`` object
may be read through an ``__unsafe_unretained`` lvalue.

It is undefined behavior if a managed operation is performed on a ``__strong``
or ``__weak`` object without a guarantee that it contains a primitive zero
bit-pattern, or if the storage for such an object is freed or reused without the
object being first assigned a null pointer.

.. admonition:: Rationale

  ARC cannot differentiate between an assignment operator which is intended to
  "initialize" dynamic memory and one which is intended to potentially replace
  a value.  Therefore the object's pointer must be valid before letting ARC at
  it.  Similarly, C and Objective-C do not provide any language hooks for
  destroying objects held in dynamic memory, so it is the programmer's
  responsibility to avoid leaks (``__strong`` objects) and consistency errors
  (``__weak`` objects).

These requirements are followed automatically in Objective-C++ when creating
objects of retainable object owner type with ``new`` or ``new[]`` and destroying
them with ``delete``, ``delete[]``, or a pseudo-destructor expression.  Note
that arrays of nontrivially-ownership-qualified type are not ABI compatible with
non-ARC code because the element type is non-POD: such arrays that are
``new[]``'d in ARC translation units cannot be ``delete[]``'d in non-ARC
translation units and vice-versa.

.. _arc.ownership.restrictions.pass_by_writeback:

Passing to an out parameter by writeback
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If the argument passed to a parameter of type ``T __autoreleasing *`` has type
``U oq *``, where ``oq`` is an ownership qualifier, then the argument is a
candidate for :arc-term:`pass-by-writeback`` if: