AutomaticReferenceCounting.rst source code [clang_source_code/docs/AutomaticReferenceCounting.rst]

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

Clang Project