[cfe-commits] r170278 - /cfe/trunk/docs/AutomaticReferenceCounting.rst
Sean Silva
silvas at purdue.edu
Sat Dec 15 16:23:40 PST 2012
Author: silvas
Date: Sat Dec 15 18:23:40 2012
New Revision: 170278
URL: http://llvm.org/viewvc/llvm-project?rev=170278&view=rev
Log:
docs: Fix completely broken adornment structure.
The adornment:
===
Foo
===
is for titles, not sections.
Modified:
cfe/trunk/docs/AutomaticReferenceCounting.rst
Modified: cfe/trunk/docs/AutomaticReferenceCounting.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/AutomaticReferenceCounting.rst?rev=170278&r1=170277&r2=170278&view=diff
==============================================================================
--- cfe/trunk/docs/AutomaticReferenceCounting.rst (original)
+++ cfe/trunk/docs/AutomaticReferenceCounting.rst Sat Dec 15 18:23:40 2012
@@ -20,14 +20,13 @@
.. _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
@@ -41,7 +40,7 @@
.. _arc.meta.background:
Background
-==========
+----------
This document assumes a basic familiarity with C.
@@ -133,7 +132,7 @@
.. _arc.meta.evolution:
Evolution
-=========
+---------
ARC is under continual evolution, and this document must be updated as the
language progresses.
@@ -160,7 +159,6 @@
.. _arc.general:
-=======
General
=======
@@ -180,7 +178,6 @@
.. _arc.objects:
-==========================
Retainable object pointers
==========================
@@ -242,7 +239,7 @@
.. _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
@@ -298,7 +295,7 @@
.. _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:
@@ -323,7 +320,7 @@
.. _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
@@ -378,7 +375,7 @@
.. _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
@@ -429,7 +426,7 @@
.. _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
@@ -461,7 +458,7 @@
.. _arc.objects.operands.casts:
Bridged casts
--------------
+^^^^^^^^^^^^^
A :arc-term:`bridged cast` is a C-style cast annotated with one of three
keywords:
@@ -492,12 +489,12 @@
.. _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
@@ -519,7 +516,7 @@
.. _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
@@ -590,7 +587,7 @@
.. _arc.objects.restrictions.conversion-exception-contextual:
Conversion from retainable object pointer type in certain contexts
-------------------------------------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
:when-revised:`[beginning Apple 4.0, LLVM 3.1]`
@@ -614,7 +611,6 @@
.. _arc.ownership:
-=======================
Ownership qualification
=======================
@@ -661,7 +657,7 @@
.. _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
@@ -688,7 +684,7 @@
.. _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.
@@ -748,7 +744,7 @@
.. _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
@@ -810,12 +806,12 @@
.. _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
@@ -845,7 +841,7 @@
.. _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
@@ -866,7 +862,7 @@
.. _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
@@ -924,7 +920,7 @@
.. _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
@@ -984,7 +980,7 @@
.. _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.
@@ -1016,12 +1012,12 @@
.. _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
@@ -1034,7 +1030,7 @@
.. _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:
@@ -1067,7 +1063,7 @@
.. _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
@@ -1084,7 +1080,6 @@
.. _arc.method-families:
-===============
Method families
===============
@@ -1145,7 +1140,7 @@
.. _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
@@ -1179,7 +1174,7 @@
.. _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.
@@ -1201,7 +1196,7 @@
.. _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
@@ -1227,7 +1222,7 @@
.. _arc.family.semantics.result_type:
Related result types
---------------------
+^^^^^^^^^^^^^^^^^^^^
Certain methods are candidates to have :arc-term:`related result types`:
@@ -1260,7 +1255,6 @@
.. _arc.optimization:
-============
Optimization
============
@@ -1289,7 +1283,7 @@
.. _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
@@ -1321,19 +1315,18 @@
.. _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:
@@ -1382,7 +1375,7 @@
.. _arc.misc.special_methods.dealloc:
``dealloc``
------------
+^^^^^^^^^^^
A program is ill-formed if it contains a message send or ``@selector``
expression for the selector ``dealloc``.
@@ -1442,7 +1435,7 @@
.. _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
@@ -1473,7 +1466,7 @@
.. _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
@@ -1501,7 +1494,7 @@
.. _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
@@ -1519,7 +1512,7 @@
.. _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
@@ -1543,7 +1536,7 @@
.. _arc.misc.exceptions:
Exceptions
-==========
+----------
By default in Objective C, ARC is not exception-safe for normal releases:
@@ -1588,7 +1581,7 @@
.. _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
@@ -1636,7 +1629,7 @@
.. _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``
@@ -1655,7 +1648,7 @@
.. _arc.misc.c-retainable.audit:
Auditing of C retainable pointer interfaces
--------------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
:when-revised:`[beginning Apple 4.0, LLVM 3.1]`
@@ -1712,7 +1705,6 @@
.. _arc.runtime:
-===============
Runtime support
===============
@@ -1754,7 +1746,7 @@
.. _arc.runtime.objc_autorelease:
``id objc_autorelease(id value);``
-==================================
+----------------------------------
*Precondition:* ``value`` is null or a pointer to a valid object.
@@ -1767,7 +1759,7 @@
.. _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
@@ -1781,7 +1773,7 @@
.. _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.
@@ -1795,7 +1787,7 @@
.. _arc.runtime.objc_autoreleaseReturnValue:
``id objc_autoreleaseReturnValue(id value);``
-=============================================
+---------------------------------------------
*Precondition:* ``value`` is null or a pointer to a valid object.
@@ -1811,7 +1803,7 @@
.. _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
@@ -1831,7 +1823,7 @@
.. _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.
@@ -1851,7 +1843,7 @@
.. _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.
@@ -1876,7 +1868,7 @@
.. _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.
@@ -1902,7 +1894,7 @@
.. _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.
@@ -1916,7 +1908,7 @@
.. _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
@@ -1932,7 +1924,7 @@
.. _arc.runtime.objc_release:
``void objc_release(id value);``
-================================
+--------------------------------
*Precondition:* ``value`` is null or a pointer to a valid object.
@@ -1943,7 +1935,7 @@
.. _arc.runtime.objc_retain:
``id objc_retain(id value);``
-=============================
+-----------------------------
*Precondition:* ``value`` is null or a pointer to a valid object.
@@ -1955,7 +1947,7 @@
.. _arc.runtime.objc_retainAutorelease:
``id objc_retainAutorelease(id value);``
-========================================
+----------------------------------------
*Precondition:* ``value`` is null or a pointer to a valid object.
@@ -1974,7 +1966,7 @@
.. _arc.runtime.objc_retainAutoreleaseReturnValue:
``id objc_retainAutoreleaseReturnValue(id value);``
-===================================================
+---------------------------------------------------
*Precondition:* ``value`` is null or a pointer to a valid object.
@@ -1994,7 +1986,7 @@
.. _arc.runtime.objc_retainAutoreleasedReturnValue:
``id objc_retainAutoreleasedReturnValue(id value);``
-====================================================
+----------------------------------------------------
*Precondition:* ``value`` is null or a pointer to a valid object.
@@ -2010,7 +2002,7 @@
.. _arc.runtime.objc_retainBlock:
``id objc_retainBlock(id value);``
-==================================
+----------------------------------
*Precondition:* ``value`` is null or a pointer to a valid block object.
@@ -2022,7 +2014,7 @@
.. _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
@@ -2046,7 +2038,7 @@
.. _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
More information about the cfe-commits
mailing list