From b34b805b13ab54c7397379caaf3f84d86813f95e Mon Sep 17 00:00:00 2001 From: Sean Silva <silvas@purdue.edu> Date: Sun, 16 Dec 2012 00:23:40 +0000 Subject: [PATCH] docs: Fix completely broken adornment structure. The adornment: === Foo === is for titles, not sections. git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@170278 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/AutomaticReferenceCounting.rst | 128 +++++++++++++--------------- 1 file changed, 60 insertions(+), 68 deletions(-) diff --git a/docs/AutomaticReferenceCounting.rst b/docs/AutomaticReferenceCounting.rst index 5c1e7d3dfa1..7996d5c509e 100644 --- a/docs/AutomaticReferenceCounting.rst +++ b/docs/AutomaticReferenceCounting.rst @@ -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 @@ stray into marketing speculation. .. _arc.meta.background: Background -========== +---------- This document assumes a basic familiarity with C. @@ -133,7 +132,7 @@ implements ``retain`` by adjusting the reference count, not by calling .. _arc.meta.evolution: Evolution -========= +--------- ARC is under continual evolution, and this document must be updated as the language progresses. @@ -160,7 +159,6 @@ changes are generally to be avoided. .. _arc.general: -======= General ======= @@ -180,7 +178,6 @@ preprocessor. For more information about ``__has_feature``, see the .. _arc.objects: -========================== Retainable object pointers ========================== @@ -242,7 +239,7 @@ typedef, and do not assume that it will be preserved by language features like .. _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 @@ 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: @@ -323,7 +320,7 @@ 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 @@ -378,7 +375,7 @@ function. .. _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 @@ its result from the implementation of the called block or function. .. _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 @@ 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: @@ -492,12 +489,12 @@ 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 @@ -519,7 +516,7 @@ 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 @@ -590,7 +587,7 @@ retain-agnostic, the conversion is treated as a ``__bridge`` cast. .. _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 @@ ill-formed as discussed above unless the result is immediately used: .. _arc.ownership: -======================= Ownership qualification ======================= @@ -661,7 +657,7 @@ A type is :arc-term:`nontrivially ownership-qualified` if it is qualified with .. _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 @@ the type there. .. _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 @@ 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 @@ -810,12 +806,12 @@ 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 @@ -845,7 +841,7 @@ 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 @@ -866,7 +862,7 @@ 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 @@ -924,7 +920,7 @@ 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 @@ -984,7 +980,7 @@ A pass-by-writeback is evaluated as follows: .. _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 @@ nontrivially ownership-qualified member. .. _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 @@ qualification instead. .. _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 @@ ill-formed. .. _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 @@ whether the template argument was deduced or explicitly specified. .. _arc.method-families: -=============== Method families =============== @@ -1145,7 +1140,7 @@ overrides do not all have the same method family. .. _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 @@ naming convention. .. _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 @@ attribute. .. _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 @@ perform at most one delegate init call. .. _arc.family.semantics.result_type: Related result types --------------------- +^^^^^^^^^^^^^^^^^^^^ Certain methods are candidates to have :arc-term:`related result types`: @@ -1260,7 +1255,6 @@ This is a new rule of the Objective-C language and applies outside of ARC. .. _arc.optimization: -============ Optimization ============ @@ -1289,7 +1283,7 @@ useful to document them here. .. _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 @@ it should be considered to be an object with precise lifetime semantics. .. _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 @@ A program is ill-formed if it contains a method definition, message send, or .. _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 @@ both within a single class and between subclasses and superclasses. .. _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 @@ A program is ill-formed if it refers to the ``NSAutoreleasePool`` class. .. _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 @@ To make this safe, for Objective-C instance methods ``self`` is implicitly .. _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 @@ enumeration are not actually retained. .. _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 @@ result is used only as an argument to a call. .. _arc.misc.exceptions: Exceptions -========== +---------- By default in Objective C, ARC is not exception-safe for normal releases: @@ -1588,7 +1581,7 @@ their scope unless exceptions are disabled in the compiler. .. _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 @@ from a ``__strong`` object with :ref:`precise lifetime semantics .. _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 @@ or ``class`` type. .. _arc.misc.c-retainable.audit: Auditing of C retainable pointer interfaces -------------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :when-revised:`[beginning Apple 4.0, LLVM 3.1]` @@ -1712,7 +1705,6 @@ It is possible to test for all the features in this section with .. _arc.runtime: -=============== Runtime support =============== @@ -1754,7 +1746,7 @@ emit, which are described in the remainder of this section. .. _arc.runtime.objc_autorelease: ``id objc_autorelease(id value);`` -================================== +---------------------------------- *Precondition:* ``value`` is null or a pointer to a valid object. @@ -1767,7 +1759,7 @@ Always returns ``value``. .. _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 @@ pool directly enclosing ``pool``. .. _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 @@ 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. @@ -1811,7 +1803,7 @@ Always returns ``value``. .. _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 @@ Must be atomic with respect to calls to ``objc_storeWeak`` on ``src``. .. _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 @@ Does not need to be atomic with respect to calls to ``objc_storeWeak`` on .. _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 @@ Does not need to be atomic with respect to calls to ``objc_storeWeak`` on .. _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 @@ Must be atomic with respect to calls to ``objc_storeWeak`` on ``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. @@ -1916,7 +1908,7 @@ Must be atomic with respect to calls to ``objc_storeWeak`` on ``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 @@ -1932,7 +1924,7 @@ Must be atomic with respect to calls to ``objc_storeWeak`` on ``src``. .. _arc.runtime.objc_release: ``void objc_release(id value);`` -================================ +-------------------------------- *Precondition:* ``value`` is null or a pointer to a valid object. @@ -1943,7 +1935,7 @@ message. .. _arc.runtime.objc_retain: ``id objc_retain(id value);`` -============================= +----------------------------- *Precondition:* ``value`` is null or a pointer to a valid object. @@ -1955,7 +1947,7 @@ Always returns ``value``. .. _arc.runtime.objc_retainAutorelease: ``id objc_retainAutorelease(id value);`` -======================================== +---------------------------------------- *Precondition:* ``value`` is null or a pointer to a valid object. @@ -1974,7 +1966,7 @@ Always returns ``value``. .. _arc.runtime.objc_retainAutoreleaseReturnValue: ``id objc_retainAutoreleaseReturnValue(id value);`` -=================================================== +--------------------------------------------------- *Precondition:* ``value`` is null or a pointer to a valid object. @@ -1994,7 +1986,7 @@ Always returns ``value``. .. _arc.runtime.objc_retainAutoreleasedReturnValue: ``id objc_retainAutoreleasedReturnValue(id value);`` -==================================================== +---------------------------------------------------- *Precondition:* ``value`` is null or a pointer to a valid object. @@ -2010,7 +2002,7 @@ Always returns ``value``. .. _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 @@ block exactly as if it had been sent the ``retain`` message. .. _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 @@ Always returns ``value``. .. _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 -- GitLab