.. _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
.. _arc.meta.background:
Background
-==========
+----------
This document assumes a basic familiarity with C.
.. _arc.meta.evolution:
Evolution
-=========
+---------
ARC is under continual evolution, and this document must be updated as the
language progresses.
.. _arc.general:
-=======
General
=======
.. _arc.objects:
-==========================
Retainable object pointers
==========================
.. _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
.. _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:
.. _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
.. _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
.. _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
.. _arc.objects.operands.casts:
Bridged casts
--------------
+^^^^^^^^^^^^^
A :arc-term:`bridged cast` is a C-style cast annotated with one of three
keywords:
.. _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
.. _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
.. _arc.objects.restrictions.conversion-exception-contextual:
Conversion from retainable object pointer type in certain contexts
-------------------------------------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
:when-revised:`[beginning Apple 4.0, LLVM 3.1]`
.. _arc.ownership:
-=======================
Ownership qualification
=======================
.. _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
.. _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.
.. _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
.. _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
.. _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
.. _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
.. _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
.. _arc.ownership.restrictions.records:
Ownership-qualified fields of structs and unions
-------------------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A program is ill-formed if it declares a member of a C struct or union to have
a nontrivially ownership-qualified type.
.. _arc.ownership.inference:
Ownership inference
-===================
+-------------------
.. _arc.ownership.inference.variables:
Objects
--------
+^^^^^^^
If an object is declared with retainable object owner type, but without an
explicit ownership qualifier, its type is implicitly adjusted to have
.. _arc.ownership.inference.indirect_parameters:
Indirect parameters
--------------------
+^^^^^^^^^^^^^^^^^^^
If a function or method parameter has type ``T*``, where ``T`` is an
ownership-unqualified retainable object pointer type, then:
.. _arc.ownership.inference.template.arguments:
Template arguments
-------------------
+^^^^^^^^^^^^^^^^^^
If a template argument for a template type parameter is an retainable object
owner type that does not have an explicit ownership qualifier, it is adjusted
.. _arc.method-families:
-===============
Method families
===============
.. _arc.family.attribute:
Explicit method family control
-==============================
+------------------------------
A method may be annotated with the ``objc_method_family`` attribute to
precisely control which method family it belongs to. If a method in an
.. _arc.family.semantics:
Semantics of method families
-============================
+----------------------------
A method's membership in a method family may imply non-standard semantics for
its parameters and return type.
.. _arc.family.semantics.init:
Semantics of ``init``
----------------------
+^^^^^^^^^^^^^^^^^^^^^
Methods in the ``init`` family implicitly :ref:`consume
<arc.objects.operands.consumed>` their ``self`` parameter and :ref:`return a
.. _arc.family.semantics.result_type:
Related result types
---------------------
+^^^^^^^^^^^^^^^^^^^^
Certain methods are candidates to have :arc-term:`related result types`:
.. _arc.optimization:
-============
Optimization
============
.. _arc.optimization.precise:
Precise lifetime semantics
-==========================
+--------------------------
In general, ARC maintains an invariant that a retainable object pointer held in
a ``__strong`` object will be retained for the full formal lifetime of the
.. _arc.misc:
-=============
Miscellaneous
=============
.. _arc.misc.special_methods:
Special methods
-===============
+---------------
.. _arc.misc.special_methods.retain:
Memory management methods
--------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^
A program is ill-formed if it contains a method definition, message send, or
``@selector`` expression for any of the following selectors:
.. _arc.misc.special_methods.dealloc:
``dealloc``
------------
+^^^^^^^^^^^
A program is ill-formed if it contains a message send or ``@selector``
expression for the selector ``dealloc``.
.. _arc.misc.autoreleasepool:
``@autoreleasepool``
-====================
+--------------------
To simplify the use of autorelease pools, and to bring them under the control
of the compiler, a new kind of statement is available in Objective-C. It is
.. _arc.misc.self:
``self``
-========
+--------
The ``self`` parameter variable of an Objective-C method is never actually
retained by the implementation. It is undefined behavior, or at least
.. _arc.misc.enumeration:
Fast enumeration iteration variables
-====================================
+------------------------------------
If a variable is declared in the condition of an Objective-C fast enumeration
loop, and the variable has no explicit ownership qualifier, then it is
.. _arc.misc.blocks:
Blocks
-======
+------
The implicit ``const`` capture variables created when evaluating a block
literal expression have the same ownership semantics as the local variables
.. _arc.misc.exceptions:
Exceptions
-==========
+----------
By default in Objective C, ARC is not exception-safe for normal releases:
.. _arc.misc.interior:
Interior pointers
-=================
+-----------------
An Objective-C method returning a non-retainable pointer may be annotated with
the ``objc_returns_inner_pointer`` attribute to indicate that it returns a
.. _arc.misc.c-retainable:
C retainable pointer types
-==========================
+--------------------------
A type is a :arc-term:`C retainable pointer type`` if it is a pointer to
(possibly qualified) ``void`` or a pointer to a (possibly qualifier) ``struct``
.. _arc.misc.c-retainable.audit:
Auditing of C retainable pointer interfaces
--------------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
:when-revised:`[beginning Apple 4.0, LLVM 3.1]`
.. _arc.runtime:
-===============
Runtime support
===============
.. _arc.runtime.objc_autorelease:
``id objc_autorelease(id value);``
-==================================
+----------------------------------
*Precondition:* ``value`` is null or a pointer to a valid object.
.. _arc.runtime.objc_autoreleasePoolPop:
``void objc_autoreleasePoolPop(void *pool);``
-=============================================
+---------------------------------------------
*Precondition:* ``pool`` is the result of a previous call to
:ref:`objc_autoreleasePoolPush <arc.runtime.objc_autoreleasePoolPush>` on the
.. _arc.runtime.objc_autoreleasePoolPush:
``void *objc_autoreleasePoolPush(void);``
-=========================================
+-----------------------------------------
Creates a new autorelease pool that is enclosed by the current pool, makes that
the current pool, and returns an opaque "handle" to it.
.. _arc.runtime.objc_autoreleaseReturnValue:
``id objc_autoreleaseReturnValue(id value);``
-=============================================
+---------------------------------------------
*Precondition:* ``value`` is null or a pointer to a valid object.
.. _arc.runtime.objc_copyWeak:
``void objc_copyWeak(id *dest, id *src);``
-==========================================
+------------------------------------------
*Precondition:* ``src`` is a valid pointer which either contains a null pointer
or has been registered as a ``__weak`` object. ``dest`` is a valid pointer
.. _arc.runtime.objc_destroyWeak:
``void objc_destroyWeak(id *object);``
-======================================
+--------------------------------------
*Precondition:* ``object`` is a valid pointer which either contains a null
pointer or has been registered as a ``__weak`` object.
.. _arc.runtime.objc_initWeak:
``id objc_initWeak(id *object, id value);``
-===========================================
+-------------------------------------------
*Precondition:* ``object`` is a valid pointer which has not been registered as
a ``__weak`` object. ``value`` is null or a pointer to a valid object.
.. _arc.runtime.objc_loadWeak:
``id objc_loadWeak(id *object);``
-=================================
+---------------------------------
*Precondition:* ``object`` is a valid pointer which either contains a null
pointer or has been registered as a ``__weak`` object.
.. _arc.runtime.objc_loadWeakRetained:
``id objc_loadWeakRetained(id *object);``
-=========================================
+-----------------------------------------
*Precondition:* ``object`` is a valid pointer which either contains a null
pointer or has been registered as a ``__weak`` object.
.. _arc.runtime.objc_moveWeak:
``void objc_moveWeak(id *dest, id *src);``
-==========================================
+------------------------------------------
*Precondition:* ``src`` is a valid pointer which either contains a null pointer
or has been registered as a ``__weak`` object. ``dest`` is a valid pointer
.. _arc.runtime.objc_release:
``void objc_release(id value);``
-================================
+--------------------------------
*Precondition:* ``value`` is null or a pointer to a valid object.
.. _arc.runtime.objc_retain:
``id objc_retain(id value);``
-=============================
+-----------------------------
*Precondition:* ``value`` is null or a pointer to a valid object.
.. _arc.runtime.objc_retainAutorelease:
``id objc_retainAutorelease(id value);``
-========================================
+----------------------------------------
*Precondition:* ``value`` is null or a pointer to a valid object.
.. _arc.runtime.objc_retainAutoreleaseReturnValue:
``id objc_retainAutoreleaseReturnValue(id value);``
-===================================================
+---------------------------------------------------
*Precondition:* ``value`` is null or a pointer to a valid object.
.. _arc.runtime.objc_retainAutoreleasedReturnValue:
``id objc_retainAutoreleasedReturnValue(id value);``
-====================================================
+----------------------------------------------------
*Precondition:* ``value`` is null or a pointer to a valid object.
.. _arc.runtime.objc_retainBlock:
``id objc_retainBlock(id value);``
-==================================
+----------------------------------
*Precondition:* ``value`` is null or a pointer to a valid block object.
.. _arc.runtime.objc_storeStrong:
``id objc_storeStrong(id *object, id value);``
-==============================================
+----------------------------------------------
*Precondition:* ``object`` is a valid pointer to a ``__strong`` object which is
adequately aligned for a pointer. ``value`` is null or a pointer to a valid
.. _arc.runtime.objc_storeWeak:
``id objc_storeWeak(id *object, id value);``
-============================================
+--------------------------------------------
*Precondition:* ``object`` is a valid pointer which either contains a null
pointer or has been registered as a ``__weak`` object. ``value`` is null or a
projects / clang / commitdiff