Blame - docs/AutomaticReferenceCounting.html - fp2-dev/platform/external/clang

blob: 74506b04b15b0c38482eaef39f1b6af211288316 [file] [log] [blame]

Benjamin Kramer	665a8dc	2012-01-15 15:26:07 +0000	[diff] [blame]	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
				2	"http://www.w3.org/TR/html4/strict.dtd">
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	3	<html>
				4	<head>
				5	<title>Objective-C Automatic Reference Counting (ARC)</title>
Benjamin Kramer	665a8dc	2012-01-15 15:26:07 +0000	[diff] [blame]	6	<link type="text/css" rel="stylesheet" href="../menu.css">
				7	<link type="text/css" rel="stylesheet" href="../content.css">
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	8	<style type="text/css">
				9	/* Collapse the items in the ToC to the left. */
				10	div#toc ul {
				11	padding-left: 0
				12	}
				13
				14	/* Rationales appear in italic. */
				15	div.rationale {
				16	font-style: italic
				17	}
				18
John McCall	f3d08a6	2011-06-18 07:31:30 +0000	[diff] [blame]	19	div.rationale em {
				20	font-style: normal
				21	}
				22
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	23	div h1 { font-size: 2em; margin: .67em 0 }
				24	div div h1 { font-size: 1.5em; margin: .75em 0 }
				25	div div div h1 { font-size: 1.17em; margin: .83em 0 }
				26	div div div div h1 { margin: 1.12em 0 }
				27
				28	span.term { font-style: italic; font-weight: bold }
				29	</style>
				30
Benjamin Kramer	665a8dc	2012-01-15 15:26:07 +0000	[diff] [blame]	31	<script type="text/javascript">
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	32	/// A little script to recursively build a table of contents.
				33	function buildTOC(div, toc, ancestry) {
				34	var children = div.childNodes;
				35	var len = children.length;
				36
				37	var childNumber = 0;
				38
				39	var list = null;
				40	for (var i = 0; i < len; ++i) {
				41	var child = children[i];
				42	if (child.nodeName != "DIV") continue;
				43	if (child.getAttribute("class") == "rationale") continue;
				44	if (child.id == "toc") continue;
				45
				46	// Okay, we're actually going to build a list node.
				47	if (list === null) list = document.createElement("ul");
				48
				49	var childAncestry = ancestry + ++childNumber + ".";
				50
				51	var headerNode = child.childNodes[1];
				52	var title = headerNode.innerHTML;
				53	headerNode.insertBefore(document.createTextNode(childAncestry + " "),
				54	headerNode.firstChild);
				55
				56	var item = document.createElement("li");
				57	item.appendChild(document.createTextNode(childAncestry + " "));
				58
				59	var anchor = document.createElement("a");
				60	anchor.href = "#" + child.id;
				61	anchor.innerHTML = title;
				62	item.appendChild(anchor);
				63
				64	buildTOC(child, item, childAncestry);
				65
				66	list.appendChild(item);
				67	}
				68	if (list) toc.appendChild(list);
				69	}
				70
				71	function onLoad() {
				72	var toc = document.getElementById("toc");
				73	var content = document.getElementById("content");
				74	buildTOC(content, toc, "");
				75	}
				76	window.onload = onLoad;
				77
				78	</script>
				79	</head>
				80	<body>
				81
				82	<!--#include virtual="../menu.html.incl"-->
				83
				84	<div id="content">
				85	<h1>Automatic Reference Counting</h1>
				86
				87	<div id="toc">
				88	</div>
				89
				90	<div id="meta">
				91	<h1>About this document</h1>
				92
				93	<div id="meta.purpose">
				94	<h1>Purpose</h1>
				95
				96	<p>The first and primary purpose of this document is to serve as a
				97	complete technical specification of Automatic Reference Counting.
				98	Given a core Objective-C compiler and runtime, it should be possible
				99	to write a compiler and runtime which implements these new
				100	semantics.</p>
				101
				102	<p>The secondary purpose is to act as a rationale for why ARC was
				103	designed in this way. This should remain tightly focused on the
				104	technical design and should not stray into marketing speculation.</p>
				105
				106	</div> <!-- meta.purpose -->
				107
				108	<div id="meta.background">
				109	<h1>Background</h1>
				110
				111	<p>This document assumes a basic familiarity with C.</p>
				112
				113	<p><span class="term">Blocks</span> are a C language extension for
				114	creating anonymous functions. Users interact with and transfer block
				115	objects using <span class="term">block pointers</span>, which are
				116	represented like a normal pointer. A block may capture values from
				117	local variables; when this occurs, memory must be dynamically
				118	allocated. The initial allocation is done on the stack, but the
				119	runtime provides a <tt>Block_copy</tt> function which, given a block
				120	pointer, either copies the underlying block object to the heap,
				121	setting its reference count to 1 and returning the new block pointer,
				122	or (if the block object is already on the heap) increases its
				123	reference count by 1. The paired function is <tt>Block_release</tt>,
				124	which decreases the reference count by 1 and destroys the object if
				125	the count reaches zero and is on the heap.</p>
				126
				127	<p>Objective-C is a set of language extensions, significant enough to
				128	be considered a different language. It is a strict superset of C.
				129	The extensions can also be imposed on C++, producing a language called
				130	Objective-C++. The primary feature is a single-inheritance object
				131	system; we briefly describe the modern dialect.</p>
				132
				133	<p>Objective-C defines a new type kind, collectively called
				134	the <span class="term">object pointer types</span>. This kind has two
				135	notable builtin members, <tt>id</tt> and <tt>Class</tt>; <tt>id</tt>
				136	is the final supertype of all object pointers. The validity of
				137	conversions between object pointer types is not checked at runtime.
				138	Users may define <span class="term">classes</span>; each class is a
				139	type, and the pointer to that type is an object pointer type. A class
				140	may have a superclass; its pointer type is a subtype of its
				141	superclass's pointer type. A class has a set
				142	of <span class="term">ivars</span>, fields which appear on all
				143	instances of that class. For every class <i>T</i> there's an
				144	associated metaclass; it has no fields, its superclass is the
				145	metaclass of <i>T</i>'s superclass, and its metaclass is a global
				146	class. Every class has a global object whose class is the
				147	class's metaclass; metaclasses have no associated type, so pointers to
				148	this object have type <tt>Class</tt>.</p>
				149
				150	<p>A class declaration (<tt>@interface</tt>) declares a set
				151	of <span class="term">methods</span>. A method has a return type, a
				152	list of argument types, and a <span class="term">selector</span>: a
				153	name like <tt>foo:bar:baz:</tt>, where the number of colons
				154	corresponds to the number of formal arguments. A method may be an
				155	instance method, in which case it can be invoked on objects of the
				156	class, or a class method, in which case it can be invoked on objects
				157	of the metaclass. A method may be invoked by providing an object
				158	(called the <span class="term">receiver</span>) and a list of formal
				159	arguments interspersed with the selector, like so:</p>
				160
				161	<pre>[receiver foo: fooArg bar: barArg baz: bazArg]</pre>
				162
				163	<p>This looks in the dynamic class of the receiver for a method with
				164	this name, then in that class's superclass, etc., until it finds
				165	something it can execute. The receiver <q>expression</q> may also be
				166	the name of a class, in which case the actual receiver is the class
				167	object for that class, or (within method definitions) it may
				168	be <tt>super</tt>, in which case the lookup algorithm starts with the
				169	static superclass instead of the dynamic class. The actual methods
				170	dynamically found in a class are not those declared in the
				171	<tt>@interface</tt>, but those defined in a separate
				172	<tt>@implementation</tt> declaration; however, when compiling a
				173	call, typechecking is done based on the methods declared in the
				174	<tt>@interface</tt>.</p>
				175
				176	<p>Method declarations may also be grouped into
				177	<span class="term">protocols</span>, which are not inherently
				178	associated with any class, but which classes may claim to follow.
				179	Object pointer types may be qualified with additional protocols that
				180	the object is known to support.</p>
				181
				182	<p><span class="term">Class extensions</span> are collections of ivars
				183	and methods, designed to allow a class's <tt>@interface</tt> to be
				184	split across multiple files; however, there is still a primary
				185	implementation file which must see the <tt>@interface</tt>s of all
				186	class extensions.
				187	<span class="term">Categories</span> allow methods (but not ivars) to
				188	be declared <i>post hoc</i> on an arbitrary class; the methods in the
				189	category's <tt>@implementation</tt> will be dynamically added to that
				190	class's method tables which the category is loaded at runtime,
				191	replacing those methods in case of a collision.</p>
				192
				193	<p>In the standard environment, objects are allocated on the heap, and
				194	their lifetime is manually managed using a reference count. This is
				195	done using two instance methods which all classes are expected to
				196	implement: <tt>retain</tt> increases the object's reference count by
				197	1, whereas <tt>release</tt> decreases it by 1 and calls the instance
				198	method <tt>dealloc</tt> if the count reaches 0. To simplify certain
				199	operations, there is also an <span class="term">autorelease
				200	pool</span>, a thread-local list of objects to call <tt>release</tt>
				201	on later; an object can be added to this pool by
				202	calling <tt>autorelease</tt> on it.</p>
				203
				204	<p>Block pointers may be converted to type <tt>id</tt>; block objects
				205	are laid out in a way that makes them compatible with Objective-C
				206	objects. There is a builtin class that all block objects are
				207	considered to be objects of; this class implements <tt>retain</tt> by
				208	adjusting the reference count, not by calling <tt>Block_copy</tt>.</p>
				209
				210	</div> <!-- meta.background -->
				211
				212	</div> <!-- meta -->
				213
				214	<div id="general">
				215	<h1>General</h1>
				216
				217	<p>Automatic Reference Counting implements automatic memory management
				218	for Objective-C objects and blocks, freeing the programmer from the
				219	need explicitly insert retains and releases. It does not provide a
				220	cycle collector; users must explicitly manage lifetime instead.</p>
				221
				222	<p>ARC may be explicitly enabled with the compiler
				223	flag <tt>-fobjc-arc</tt>. It may also be explicitly disabled with the
				224	compiler flag <tt>-fno-objc-arc</tt>. The last of these two flags
				225	appearing on the compile line <q>wins</q>.</p>
				226
				227	<p>If ARC is enabled, <tt>__has_feature(objc_arc)</tt> will expand to
				228	1 in the preprocessor. For more information about <tt>__has_feature</tt>,
				229	see the <a href="LanguageExtensions.html#__has_feature_extension">language
				230	extensions</a> document.</p>
				231
				232	</div>
				233
				234	<div id="objects">
				235	<h1>Retainable object pointers</h1>
				236
				237	<p>This section describes retainable object pointers, their basic
				238	operations, and the restrictions imposed on their use under ARC. Note
				239	in particular that it covers the rules for pointer <em>values</em>
				240	(patterns of bits indicating the location of a pointed-to object), not
				241	pointer
				242	<em>objects</em> (locations in memory which store pointer values).
				243	The rules for objects are covered in the next section.</p>
				244
				245	<p>A <span class="term">retainable object pointer</span>
				246	(or <q>retainable pointer</q>) is a value of
				247	a <span class="term">retainable object pointer type</span>
				248	(<q>retainable type</q>). There are three kinds of retainable object
				249	pointer types:</p>
				250	<ul>
				251	<li>block pointers (formed by applying the caret (<tt>^</tt>)
				252	declarator sigil to a function type)</li>
				253	<li>Objective-C object pointers (<tt>id</tt>, <tt>Class</tt>, <tt>NSFoo*</tt>, etc.)</li>
				254	<li>typedefs marked with <tt>__attribute__((NSObject))</tt></li>
				255	</ul>
				256
				257	<p>Other pointer types, such as <tt>int*</tt> and <tt>CFStringRef</tt>,
				258	are not subject to ARC's semantics and restrictions.</p>
				259
				260	<div class="rationale">
				261
				262	<p>Rationale: We are not at liberty to require
				263	all code to be recompiled with ARC; therefore, ARC must interoperate
				264	with Objective-C code which manages retains and releases manually. In
				265	general, there are three requirements in order for a
				266	compiler-supported reference-count system to provide reliable
				267	interoperation:</p>
				268
				269	<ul>
				270	<li>The type system must reliably identify which objects are to be
				271	managed. An <tt>int*</tt> might be a pointer to a <tt>malloc</tt>'ed
				272	array, or it might be a interior pointer to such an array, or it might
				273	point to some field or local variable. In contrast, values of the
				274	retainable object pointer types are never interior.</li>
				275	<li>The type system must reliably indicate how to
				276	manage objects of a type. This usually means that the type must imply
				277	a procedure for incrementing and decrementing retain counts.
				278	Supporting single-ownership objects requires a lot more explicit
				279	mediation in the language.</li>
				280	<li>There must be reliable conventions for whether and
				281	when <q>ownership</q> is passed between caller and callee, for both
				282	arguments and return values. Objective-C methods follow such a
				283	convention very reliably, at least for system libraries on Mac OS X,
				284	and functions always pass objects at +0. The C-based APIs for Core
				285	Foundation objects, on the other hand, have much more varied transfer
				286	semantics.</li>
				287	</ul>
				288	</div> <!-- rationale -->
				289
				290	<p>The use of <tt>__attribute__((NSObject))</tt> typedefs is not
				291	recommended. If it's absolutely necessary to use this attribute, be
				292	very explicit about using the typedef, and do not assume that it will
				293	be preserved by language features like <tt>__typeof</tt> and C++
				294	template argument substitution.</p>
				295
				296	<div class="rationale"><p>Rationale: any compiler operation which
				297	incidentally strips type <q>sugar</q> from a type will yield a type
				298	without the attribute, which may result in unexpected
				299	behavior.</p></div>
				300
				301	<div id="objects.retains">
				302	<h1>Retain count semantics</h1>
				303
				304	<p>A retainable object pointer is either a <span class="term">null
				305	pointer</span> or a pointer to a valid object. Furthermore, if it has
				306	block pointer type and is not <tt>null</tt> then it must actually be a
				307	pointer to a block object, and if it has <tt>Class</tt> type (possibly
				308	protocol-qualified) then it must actually be a pointer to a class
				309	object. Otherwise ARC does not enforce the Objective-C type system as
				310	long as the implementing methods follow the signature of the static
				311	type. It is undefined behavior if ARC is exposed to an invalid
				312	pointer.</p>
				313
				314	<p>For ARC's purposes, a valid object is one with <q>well-behaved</q>
				315	retaining operations. Specifically, the object must be laid out such
				316	that the Objective-C message send machinery can successfully send it
				317	the following messages:</p>
				318
				319	<ul>
				320	<li><tt>retain</tt>, taking no arguments and returning a pointer to
				321	the object.</li>
				322	<li><tt>release</tt>, taking no arguments and returning <tt>void</tt>.</li>
				323	<li><tt>autorelease</tt>, taking no arguments and returning a pointer
				324	to the object.</li>
				325	</ul>
				326
				327	<p>The behavior of these methods is constrained in the following ways.
				328	The term <span class="term">high-level semantics</span> is an
				329	intentionally vague term; the intent is that programmers must
				330	implement these methods in a way such that the compiler, modifying
				331	code in ways it deems safe according to these constraints, will not
				332	violate their requirements. For example, if the user puts logging
				333	statements in <tt>retain</tt>, they should not be surprised if those
				334	statements are executed more or less often depending on optimization
				335	settings. These constraints are not exhaustive of the optimization
				336	opportunities: values held in local variables are subject to
				337	additional restrictions, described later in this document.</p>
				338
				339	<p>It is undefined behavior if a computation history featuring a send
				340	of <tt>retain</tt> followed by a send of <tt>release</tt> to the same
				341	object, with no intervening <tt>release</tt> on that object, is not
				342	equivalent under the high-level semantics to a computation
				343	history in which these sends are removed. Note that this implies that
				344	these methods may not raise exceptions.</p>
				345
				346	<p>It is undefined behavior if a computation history features any use
				347	whatsoever of an object following the completion of a send
				348	of <tt>release</tt> that is not preceded by a send of <tt>retain</tt>
				349	to the same object.</p>
				350
				351	<p>The behavior of <tt>autorelease</tt> must be equivalent to sending
				352	<tt>release</tt> when one of the autorelease pools currently in scope
				353	is popped. It may not throw an exception.</p>
				354
				355	<p>When the semantics call for performing one of these operations on a
				356	retainable object pointer, if that pointer is <tt>null</tt> then the
				357	effect is a no-op.</p>
				358
				359	<p>All of the semantics described in this document are subject to
				360	additional <a href="#optimization">optimization rules</a> which permit
				361	the removal or optimization of operations based on local knowledge of
				362	data flow. The semantics describe the high-level behaviors that the
				363	compiler implements, not an exact sequence of operations that a
				364	program will be compiled into.</p>
				365
				366	</div> <!-- objects.retains -->
				367
				368	<div id="objects.operands">
				369	<h1>Retainable object pointers as operands and arguments</h1>
				370
				371	<p>In general, ARC does not perform retain or release operations when
				372	simply using a retainable object pointer as an operand within an
				373	expression. This includes:</p>
				374	<ul>
				375	<li>loading a retainable pointer from an object with non-weak
				376	<a href="#ownership">ownership</a>,</li>
				377	<li>passing a retainable pointer as an argument to a function or
				378	method, and</li>
				379	<li>receiving a retainable pointer as the result of a function or
				380	method call.</li>
				381	</ul>
				382
				383	<div class="rationale"><p>Rationale: while this might seem
				384	uncontroversial, it is actually unsafe when multiple expressions are
				385	evaluated in <q>parallel</q>, as with binary operators and calls,
				386	because (for example) one expression might load from an object while
				387	another writes to it. However, C and C++ already call this undefined
				388	behavior because the evaluations are unsequenced, and ARC simply
				389	exploits that here to avoid needing to retain arguments across a large
				390	number of calls.</p></div>
				391
				392	<p>The remainder of this section describes exceptions to these rules,
				393	how those exceptions are detected, and what those exceptions imply
				394	semantically.</p>
				395
				396	<div id="objects.operands.consumed">
				397	<h1>Consumed parameters</h1>
				398
				399	<p>A function or method parameter of retainable object pointer type
				400	may be marked as <span class="term">consumed</span>, signifying that
				401	the callee expects to take ownership of a +1 retain count. This is
				402	done by adding the <tt>ns_consumed</tt> attribute to the parameter
				403	declaration, like so:</p>
				404
				405	<pre>void foo(__attribute((ns_consumed)) id x);
				406	- (void) foo: (id) __attribute((ns_consumed)) x;</pre>
				407
				408	<p>This attribute is part of the type of the function or method, not
				409	the type of the parameter. It controls only how the argument is
				410	passed and received.</p>
				411
				412	<p>When passing such an argument, ARC retains the argument prior to
				413	making the call.</p>
				414
				415	<p>When receiving such an argument, ARC releases the argument at the
				416	end of the function, subject to the usual optimizations for local
				417	values.</p>
				418
				419	<div class="rationale"><p>Rationale: this formalizes direct transfers
				420	of ownership from a caller to a callee. The most common scenario here
				421	is passing the <tt>self</tt> parameter to <tt>init</tt>, but it is
				422	useful to generalize. Typically, local optimization will remove any
				423	extra retains and releases: on the caller side the retain will be
				424	merged with a +1 source, and on the callee side the release will be
				425	rolled into the initialization of the parameter.</p></div>
				426
				427	<p>The implicit <tt>self</tt> parameter of a method may be marked as
				428	consumed by adding <tt>__attribute__((ns_consumes_self))</tt> to the
John McCall	be16b89	2011-06-18 08:15:19 +0000	[diff] [blame]	429	method declaration. Methods in the <tt>init</tt>
				430	<a href="#family">family</a> are treated as if they were implicitly
				431	marked with this attribute.</p>
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	432
John McCall	be16b89	2011-06-18 08:15:19 +0000	[diff] [blame]	433	<p>It is undefined behavior if an Objective-C message send to a method
				434	with <tt>ns_consumed</tt> parameters (other than self) is made with a
				435	null receiver. It is undefined behavior if the method to which an
				436	Objective-C message send statically resolves to has a different set
				437	of <tt>ns_consumed</tt> parameters than the method it dynamically
				438	resolves to. It is undefined behavior if a block or function call is
				439	made through a static type with a different set of <tt>ns_consumed</tt>
				440	parameters than the implementation of the called block or function.</p>
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	441
John McCall	be16b89	2011-06-18 08:15:19 +0000	[diff] [blame]	442	<div class="rationale"><p>Rationale: consumed parameters with null
				443	receiver are a guaranteed leak. Mismatches with consumed parameters
				444	will cause over-retains or over-releases, depending on the direction.
				445	The rule about function calls is really just an application of the
				446	existing C/C++ rule about calling functions through an incompatible
				447	function type, but it's useful to state it explicitly.</p></div>
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	448
				449	</div>
				450
John McCall	be16b89	2011-06-18 08:15:19 +0000	[diff] [blame]	451	<div id="objects.operands.retained_returns">
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	452	<h1>Retained return values</h1>
				453
				454	<p>A function or method which returns a retainable object pointer type
				455	may be marked as returning a retained value, signifying that the
				456	caller expects to take ownership of a +1 retain count. This is done
				457	by adding the <tt>ns_returns_retained</tt> attribute to the function or
				458	method declaration, like so:</p>
				459
				460	<pre>id foo(void) __attribute((ns_returns_retained));
				461	- (id) foo __attribute((ns_returns_retained));</pre>
				462
				463	<p>This attribute is part of the type of the function or method.</p>
				464
				465	<p>When returning from such a function or method, ARC retains the
				466	value at the point of evaluation of the return statement, before
				467	leaving all local scopes.</p>
				468
				469	<p>When receiving a return result from such a function or method, ARC
				470	releases the value at the end of the full-expression it is contained
				471	within, subject to the usual optimizations for local values.</p>
				472
				473	<div class="rationale"><p>Rationale: this formalizes direct transfers of
				474	ownership from a callee to a caller. The most common scenario this
				475	models is the retained return from <tt>init</tt>, <tt>alloc</tt>,
				476	<tt>new</tt>, and <tt>copy</tt> methods, but there are other cases in
				477	the frameworks. After optimization there are typically no extra
				478	retains and releases required.</p></div>
				479
				480	<p>Methods in
				481	the <tt>alloc</tt>, <tt>copy</tt>, <tt>init</tt>, <tt>mutableCopy</tt>,
				482	and <tt>new</tt> <a href="#family">families</a> are implicitly marked
				483	<tt>__attribute__((ns_returns_retained))</tt>. This may be suppressed
				484	by explicitly marking the
				485	method <tt>__attribute__((ns_returns_not_retained))</tt>.</p>
				486	</div>
				487
John McCall	be16b89	2011-06-18 08:15:19 +0000	[diff] [blame]	488	<p>It is undefined behavior if the method to which an Objective-C
				489	message send statically resolves has different retain semantics on its
				490	result from the method it dynamically resolves to. It is undefined
				491	behavior if a block or function call is made through a static type
				492	with different retain semantics on its result from the implementation
				493	of the called block or function.</p>
				494
				495	<div class="rationale"><p>Rationale: Mismatches with returned results
				496	will cause over-retains or over-releases, depending on the direction.
				497	Again, the rule about function calls is really just an application of
				498	the existing C/C++ rule about calling functions through an
				499	incompatible function type.</p></div>
				500
				501
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	502	<div id="objects.operands.other-returns">
				503	<h1>Unretained return values</h1>
				504
				505	<p>A method or function which returns a retainable object type but
				506	does not return a retained value must ensure that the object is
				507	still valid across the return boundary.</p>
				508
				509	<p>When returning from such a function or method, ARC retains the
				510	value at the point of evaluation of the return statement, then leaves
				511	all local scopes, and then balances out the retain while ensuring that
				512	the value lives across the call boundary. In the worst case, this may
				513	involve an <tt>autorelease</tt>, but callers must not assume that the
				514	value is actually in the autorelease pool.</p>
				515
				516	<p>ARC performs no extra mandatory work on the caller side, although
				517	it may elect to do something to shorten the lifetime of the returned
				518	value.</p>
				519
				520	<div class="rationale"><p>Rationale: it is common in non-ARC code to not
				521	return an autoreleased value; therefore the convention does not force
				522	either path. It is convenient to not be required to do unnecessary
				523	retains and autoreleases; this permits optimizations such as eliding
				524	retain/autoreleases when it can be shown that the original pointer
				525	will still be valid at the point of return.</p></div>
				526
				527	<p>A method or function may be marked
				528	with <tt>__attribute__((ns_returns_autoreleased))</tt> to indicate
				529	that it returns a pointer which is guaranteed to be valid at least as
				530	long as the innermost autorelease pool. There are no additional
				531	semantics enforced in the definition of such a method; it merely
				532	enables optimizations in callers.</p>
				533	</div>
				534
				535	<div id="objects.operands.casts">
				536	<h1>Bridged casts</h1>
				537
				538	<p>A <span class="term">bridged cast</span> is a C-style cast
				539	annotated with one of three keywords:</p>
				540
				541	<ul>
				542	<li><tt>(__bridge T) op</tt> casts the operand to the destination
				543	type <tt>T</tt>. If <tt>T</tt> is a retainable object pointer type,
				544	then <tt>op</tt> must have a non-retainable pointer type.
				545	If <tt>T</tt> is a non-retainable pointer type, then <tt>op</tt> must
				546	have a retainable object pointer type. Otherwise the cast is
				547	ill-formed. There is no transfer of ownership, and ARC inserts
				548	no retain operations.</li>
				549
				550	<li><tt>(__bridge_retained T) op</tt> casts the operand, which must
				551	have retainable object pointer type, to the destination type, which
				552	must be a non-retainable pointer type. ARC retains the value, subject
				553	to the usual optimizations on local values, and the recipient is
				554	responsible for balancing that +1.</li>
				555
				556	<li><tt>(__bridge_transfer T) op</tt> casts the operand, which must
				557	have non-retainable pointer type, to the destination type, which must
				558	be a retainable object pointer type. ARC will release the value at
				559	the end of the enclosing full-expression, subject to the usual
				560	optimizations on local values.</li>
				561	</ul>
				562
				563	<p>These casts are required in order to transfer objects in and out of
				564	ARC control; see the rationale in the section
				565	on <a href="#objects.restrictions.conversion">conversion of retainable
				566	object pointers</a>.</p>
				567
				568	<p>Using a <tt>__bridge_retained</tt> or <tt>__bridge_transfer</tt>
				569	cast purely to convince ARC to emit an unbalanced retain or release,
				570	respectively, is poor form.</p>
				571
				572	</div>
				573
				574	</div>
				575
				576	<div id="objects.restrictions">
				577	<h1>Restrictions</h1>
				578
				579	<div id="objects.restrictions.conversion">
				580	<h1>Conversion of retainable object pointers</h1>
				581
				582	<p>In general, a program which attempts to implicitly or explicitly
				583	convert a value of retainable object pointer type to any
				584	non-retainable type, or vice-versa, is ill-formed. For example, an
Fariborz Jahanian	a26b2e5	2011-07-06 21:58:44 +0000	[diff] [blame]	585	Objective-C object pointer shall not be converted to <tt>void*</tt>.
David Blaikie	0ff6495	2011-11-24 00:37:54 +0000	[diff] [blame]	586	As an exception, cast to <tt>intptr_t</tt> is allowed because such
Fariborz Jahanian	a26b2e5	2011-07-06 21:58:44 +0000	[diff] [blame]	587	casts are not transferring ownership. The <a href="#objects.operands.casts">bridged
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	588	casts</a> may be used to perform these conversions where
				589	necessary.</p>
				590
				591	<div class="rationale"><p>Rationale: we cannot ensure the correct
				592	management of the lifetime of objects if they may be freely passed
				593	around as unmanaged types. The bridged casts are provided so that the
				594	programmer may explicitly describe whether the cast transfers control
				595	into or out of ARC.</p></div>
				596	</div>
				597
				598	<p>An unbridged cast to a retainable object pointer type of the return
				599	value of a Objective-C message send which yields a non-retainable
				600	pointer is treated as a <tt>__bridge_transfer</tt> cast
				601	if:</p>
				602
				603	<ul>
				604	<li>the method has the <tt>cf_returns_retained</tt> attribute, or if
				605	not that,</li>
				606	<li>the method does not have the <tt>cf_returns_not_retained</tt>
				607	attribute and</li>
				608	<li>the method's <a href="#family">selector family</a> would imply
				609	the <tt>ns_returns_retained</tt> attribute on a method which returned
				610	a retainable object pointer type.</li>
				611	</ul>
				612
				613	<p>Otherwise the cast is treated as a <tt>__bridge</tt> cast.</p>
				614
				615	</div>
				616
				617	</div>
				618
				619	<div id="ownership">
				620	<h1>Ownership qualification</h1>
				621
				622	<p>This section describes the behavior of <em>objects</em> of
				623	retainable object pointer type; that is, locations in memory which
				624	store retainable object pointers.</p>
				625
				626	<p>A type is a <span class="term">retainable object owner type</span>
				627	if it is a retainable object pointer type or an array type whose
				628	element type is a retainable object owner type.</p>
				629
				630	<p>An <span class="term">ownership qualifier</span> is a type
Douglas Gregor	4020cae	2011-06-17 23:16:24 +0000	[diff] [blame]	631	qualifier which applies only to retainable object owner types. An array type is
				632	ownership-qualified according to its element type, and adding an ownership
				633	qualifier to an array type so qualifies its element type.</p>
				634
				635	<p>A program is ill-formed if it attempts to apply an ownership qualifier
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	636	to a type which is already ownership-qualified, even if it is the same
Douglas Gregor	4020cae	2011-06-17 23:16:24 +0000	[diff] [blame]	637	qualifier. There is a single exception to this rule: an ownership qualifier
				638	may be applied to a substituted template type parameter, which overrides the
				639	ownership qualifier provided by the template argument.</p>
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	640
				641	<p>Except as described under
				642	the <a href="#ownership.inference">inference rules</a>, a program is
				643	ill-formed if it attempts to form a pointer or reference type to a
				644	retainable object owner type which lacks an ownership qualifier.</p>
				645
				646	<div class="rationale"><p>Rationale: these rules, together with the
				647	inference rules, ensure that all objects and lvalues of retainable
Douglas Gregor	4020cae	2011-06-17 23:16:24 +0000	[diff] [blame]	648	object pointer type have an ownership qualifier. The ability to override an ownership qualifier during template substitution is required to counteract the <a href="#ownership.inference.template_arguments">inference of <tt>__strong</tt> for template type arguments</a>. </p></div>
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	649
				650	<p>There are four ownership qualifiers:</p>
				651
				652	<ul>
				653	<li><tt>__autoreleasing</tt></li>
				654	<li><tt>__strong</tt></li>
				655	<li><tt>__unsafe_unretained</tt></li>
				656	<li><tt>__weak</tt></li>
				657	</ul>
				658
				659	<p>A type is <span class="term">nontrivially ownership-qualified</span>
				660	if it is qualified with <tt>__autoreleasing</tt>, <tt>__strong</tt>, or
				661	<tt>__weak</tt>.</p>
				662
				663	<div id="ownership.spelling">
				664	<h1>Spelling</h1>
				665
				666	<p>The names of the ownership qualifiers are reserved for the
				667	implementation. A program may not assume that they are or are not
				668	implemented with macros, or what those macros expand to.</p>
				669
				670	<p>An ownership qualifier may be written anywhere that any other type
				671	qualifier may be written.</p>
				672
				673	<p>If an ownership qualifier appears in
				674	the <i>declaration-specifiers</i>, the following rules apply:</p>
				675
				676	<ul>
				677	<li>if the type specifier is a retainable object owner type, the
				678	qualifier applies to that type;</li>
				679	<li>if the outermost non-array part of the declarator is a pointer or
				680	block pointer, the qualifier applies to that type;</li>
				681	<li>otherwise the program is ill-formed.</li>
				682	</ul>
				683
				684	<p>If an ownership qualifier appears on the declarator name, or on the
				685	declared object, it is applied to outermost pointer or block-pointer
				686	type.</p>
				687
				688	<p>If an ownership qualifier appears anywhere else in a declarator, it
				689	applies to the type there.</p>
				690
John McCall	4f26495	2011-07-13 23:15:32 +0000	[diff] [blame]	691	<div id="ownership.spelling.property">
				692	<h1>Property declarations</h1>
				693
				694	<p>A property of retainable object pointer type may have ownership.
				695	If the property's type is ownership-qualified, then the property has
				696	that ownership. If the property has one of the following modifiers,
				697	then the property has the corresponding ownership. A property is
				698	ill-formed if it has conflicting sources of ownership, or if it has
				699	redundant ownership modifiers, or if it has <tt>__autoreleasing</tt>
				700	ownership.</p>
				701
				702	<ul>
				703	<li><tt>assign</tt> implies <tt>__unsafe_unretained</tt> ownership.</li>
				704	<li><tt>copy</tt> implies <tt>__strong</tt> ownership, as well as the
				705	usual behavior of copy semantics on the setter.</li>
				706	<li><tt>retain</tt> implies <tt>__strong</tt> ownership.</li>
				707	<li><tt>strong</tt> implies <tt>__strong</tt> ownership.</li>
				708	<li><tt>unsafe_unretained</tt> implies <tt>__unsafe_unretained</tt>
				709	ownership.</li>
				710	<li><tt>weak</tt> implies <tt>__weak</tt> ownership.</li>
				711	</ul>
				712
				713	<p>With the exception of <tt>weak</tt>, these modifiers are available
				714	in non-ARC modes.</p>
				715
				716	<p>A property's specified ownership is preserved in its metadata, but
				717	otherwise the meaning is purely conventional unless the property is
				718	synthesized. If a property is synthesized, then the
				719	<span class="term">associated instance variable</span> is the
				720	instance variable which is named, possibly implicitly, by the
				721	<tt>@synthesize</tt> declaration. If the associated instance variable
				722	already exists, then its ownership qualification must equal the
				723	ownership of the property; otherwise, the instance variable is created
				724	with that ownership qualification.</p>
				725
				726	</div> <!-- ownership.spelling.property -->
				727
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	728	</div> <!-- ownership.spelling -->
				729
				730	<div id="ownership.semantics">
				731	<h1>Semantics</h1>
				732
				733	<p>There are five <span class="term">managed operations</span> which
				734	may be performed on an object of retainable object pointer type. Each
				735	qualifier specifies different semantics for each of these operations.
				736	It is still undefined behavior to access an object outside of its
				737	lifetime.</p>
				738
				739	<p>A load or store with <q>primitive semantics</q> has the same
				740	semantics as the respective operation would have on an <tt>void*</tt>
				741	lvalue with the same alignment and non-ownership qualification.</p>
				742
				743	<p><span class="term">Reading</span> occurs when performing a
Benjamin Kramer	665a8dc	2012-01-15 15:26:07 +0000	[diff] [blame]	744	lvalue-to-rvalue conversion on an object lvalue.</p>
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	745
				746	<ul>
				747	<li>For <tt>__weak</tt> objects, the current pointee is retained and
				748	then released at the end of the current full-expression. This must
				749	execute atomically with respect to assignments and to the final
				750	release of the pointee.</li>
				751	<li>For all other objects, the lvalue is loaded with primitive
				752	semantics.</li>
				753	</ul>
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	754
				755	<p><span class="term">Assignment</span> occurs when evaluating
Benjamin Kramer	665a8dc	2012-01-15 15:26:07 +0000	[diff] [blame]	756	an assignment operator. The semantics vary based on the qualification:</p>
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	757	<ul>
				758	<li>For <tt>__strong</tt> objects, the new pointee is first retained;
				759	second, the lvalue is loaded with primitive semantics; third, the new
				760	pointee is stored into the lvalue with primitive semantics; and
				761	finally, the old pointee is released. This is not performed
				762	atomically; external synchronization must be used to make this safe in
				763	the face of concurrent loads and stores.</li>
				764	<li>For <tt>__weak</tt> objects, the lvalue is updated to point to the
				765	new pointee, unless that object is currently undergoing deallocation,
				766	in which case it the lvalue is updated to a null pointer. This must
				767	execute atomically with respect to other assignments to the object, to
				768	reads from the object, and to the final release of the new pointed-to
John McCall	2fad783	2011-07-07 00:03:42 +0000	[diff] [blame]	769	value.</li>
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	770	<li>For <tt>__unsafe_unretained</tt> objects, the new pointee is
				771	stored into the lvalue using primitive semantics.</li>
				772	<li>For <tt>__autoreleasing</tt> objects, the new pointee is retained,
				773	autoreleased, and stored into the lvalue using primitive semantics.</li>
				774	</ul>
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	775
				776	<p><span class="term">Initialization</span> occurs when an object's
				777	lifetime begins, which depends on its storage duration.
Benjamin Kramer	665a8dc	2012-01-15 15:26:07 +0000	[diff] [blame]	778	Initialization proceeds in two stages:</p>
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	779	<ol>
				780	<li>First, a null pointer is stored into the lvalue using primitive
				781	semantics. This step is skipped if the object
				782	is <tt>__unsafe_unretained</tt>.</li>
				783	<li>Second, if the object has an initializer, that expression is
				784	evaluated and then assigned into the object using the usual assignment
				785	semantics.</li>
				786	</ol>
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	787
				788	<p><span class="term">Destruction</span> occurs when an object's
				789	lifetime ends. In all cases it is semantically equivalent to
				790	assigning a null pointer to the object, with the proviso that of
				791	course the object cannot be legally read after the object's lifetime
				792	ends.</p>
				793
				794	<p><span class="term">Moving</span> occurs in specific situations
				795	where an lvalue is <q>moved from</q>, meaning that its current pointee
				796	will be used but the object may be left in a different (but still
				797	valid) state. This arises with <tt>__block</tt> variables and rvalue
				798	references in C++. For <tt>__strong</tt> lvalues, moving is equivalent
				799	to loading the lvalue with primitive semantics, writing a null pointer
				800	to it with primitive semantics, and then releasing the result of the
				801	load at the end of the current full-expression. For all other
				802	lvalues, moving is equivalent to reading the object.</p>
				803
				804	</div> <!-- ownership.semantics -->
				805
				806	<div id="ownership.restrictions">
				807	<h1>Restrictions</h1>
				808
John McCall	2fad783	2011-07-07 00:03:42 +0000	[diff] [blame]	809	<div id="ownership.restrictions.weak">
				810	<h1>Weak-unavailable types</h1>
				811
				812	<p>It is explicitly permitted for Objective-C classes to not
				813	support <tt>__weak</tt> references. It is undefined behavior to
				814	perform an operation with weak assignment semantics with a pointer to
				815	an Objective-C object whose class does not support <tt>__weak</tt>
				816	references.</p>
				817
				818	<div class="rationale"><p>Rationale: historically, it has been
				819	possible for a class to provide its own reference-count implementation
				820	by overriding <tt>retain</tt>, <tt>release</tt>, etc. However, weak
				821	references to an object require coordination with its class's
				822	reference-count implementation because, among other things, weak loads
				823	and stores must be atomic with respect to the final release.
				824	Therefore, existing custom reference-count implementations will
				825	generally not support weak references without additional effort. This
				826	is unavoidable without breaking binary compatibility.</p></div>
				827
				828	<p>A class may indicate that it does not support weak references by
				829	providing the <tt>objc_arc_weak_unavailable</tt> attribute on the
				830	class's interface declaration. A retainable object pointer type
				831	is <span class="term">weak-unavailable</span> if is a pointer to an
				832	(optionally protocol-qualified) Objective-C class <tt>T</tt>
				833	where <tt>T</tt> or one of its superclasses has
				834	the <tt>objc_arc_weak_unavailable</tt> attribute. A program is
				835	ill-formed if it applies the <tt>__weak</tt> ownership qualifier to a
				836	weak-unavailable type or if the value operand of a weak assignment
				837	operation has a weak-unavailable type.</p>
				838	</div> <!-- ownership.restrictions.weak -->
				839
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	840	<div id="ownership.restrictions.autoreleasing">
John McCall	2fad783	2011-07-07 00:03:42 +0000	[diff] [blame]	841	<h1>Storage duration of <tt>__autoreleasing</tt> objects</h1>
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	842
				843	<p>A program is ill-formed if it declares an <tt>__autoreleasing</tt>
				844	object of non-automatic storage duration.</p>
				845
				846	<div class="rationale"><p>Rationale: autorelease pools are tied to the
				847	current thread and scope by their nature. While it is possible to
				848	have temporary objects whose instance variables are filled with
				849	autoreleased objects, there is no way that ARC can provide any sort of
				850	safety guarantee there.</p></div>
				851
				852	<p>It is undefined behavior if a non-null pointer is assigned to
				853	an <tt>__autoreleasing</tt> object while an autorelease pool is in
				854	scope and then that object is read after the autorelease pool's scope
				855	is left.</p>
				856
				857	</div>
				858
				859	<div id="ownership.restrictions.conversion.indirect">
				860	<h1>Conversion of pointers to ownership-qualified types</h1>
				861
				862	<p>A program is ill-formed if an expression of type <tt>T*</tt> is
				863	converted, explicitly or implicitly, to the type <tt>U*</tt>,
				864	where <tt>T</tt> and <tt>U</tt> have different ownership
Benjamin Kramer	665a8dc	2012-01-15 15:26:07 +0000	[diff] [blame]	865	qualification, unless:</p>
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	866	<ul>
				867	<li><tt>T</tt> is qualified with <tt>__strong</tt>,
				868	<tt>__autoreleasing</tt>, or <tt>__unsafe_unretained</tt>, and
				869	<tt>U</tt> is qualified with both <tt>const</tt> and
				870	<tt>__unsafe_unretained</tt>; or</li>
				871	<li>either <tt>T</tt> or <tt>U</tt> is <tt>cv void</tt>, where
				872	<tt>cv</tt> is an optional sequence of non-ownership qualifiers; or</li>
				873	<li>the conversion is requested with a <tt>reinterpret_cast</tt> in
				874	Objective-C++; or</li>
				875	<li>the conversion is a
				876	well-formed <a href="#ownership.restrictions.pass_by_writeback">pass-by-writeback</a>.</li>
				877	</ul>
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	878
Benjamin Kramer	665a8dc	2012-01-15 15:26:07 +0000	[diff] [blame]	879	<p>The analogous rule applies to <tt>T&</tt> and <tt>U&</tt> in
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	880	Objective-C++.</p>
				881
				882	<div class="rationale"><p>Rationale: these rules provide a reasonable
				883	level of type-safety for indirect pointers, as long as the underlying
				884	memory is not deallocated. The conversion to <tt>const
				885	__unsafe_unretained</tt> is permitted because the semantics of reads
				886	are equivalent across all these ownership semantics, and that's a very
				887	useful and common pattern. The interconversion with <tt>void*</tt> is
				888	useful for allocating memory or otherwise escaping the type system,
				889	but use it carefully. <tt>reinterpret_cast</tt> is considered to be
				890	an obvious enough sign of taking responsibility for any
				891	problems.</p></div>
				892
				893	<p>It is undefined behavior to access an ownership-qualified object
				894	through an lvalue of a differently-qualified type, except that any
				895	non-<tt>__weak</tt> object may be read through
				896	an <tt>__unsafe_unretained</tt> lvalue.</p>
				897
				898	<p>It is undefined behavior if a managed operation is performed on
				899	a <tt>__strong</tt> or <tt>__weak</tt> object without a guarantee that
				900	it contains a primitive zero bit-pattern, or if the storage for such
				901	an object is freed or reused without the object being first assigned a
				902	null pointer.</p>
				903
				904	<div class="rationale"><p>Rationale: ARC cannot differentiate between
				905	an assignment operator which is intended to <q>initialize</q> dynamic
				906	memory and one which is intended to potentially replace a value.
				907	Therefore the object's pointer must be valid before letting ARC at it.
				908	Similarly, C and Objective-C do not provide any language hooks for
				909	destroying objects held in dynamic memory, so it is the programmer's
				910	responsibility to avoid leaks (<tt>__strong</tt> objects) and
				911	consistency errors (<tt>__weak</tt> objects).</p>
				912
				913	<p>These requirements are followed automatically in Objective-C++ when
				914	creating objects of retainable object owner type with <tt>new</tt>
				915	or <tt>new[]</tt> and destroying them with <tt>delete</tt>,
				916	<tt>delete[]</tt>, or a pseudo-destructor expression. Note that
				917	arrays of nontrivially-ownership-qualified type are not ABI compatible
				918	with non-ARC code because the element type is non-POD: such arrays
				919	that are <tt>new[]</tt>'d in ARC translation units cannot
				920	be <tt>delete[]</tt>'d in non-ARC translation units and
				921	vice-versa.</p></div>
				922
				923	</div>
				924
				925	<div id="ownership.restrictions.pass_by_writeback">
				926	<h1>Passing to an out parameter by writeback</h1>
				927
				928	<p>If the argument passed to a parameter of type
				929	<tt>T __autoreleasing </tt> has type <tt>U oq </tt>,
				930	where <tt>oq</tt> is an ownership qualifier, then the argument is a
				931	candidate for <span class="term">pass-by-writeback</span> if:</p>
				932
				933	<ul>
Benjamin Kramer	665a8dc	2012-01-15 15:26:07 +0000	[diff] [blame]	934	<li><tt>oq</tt> is <tt>__strong</tt> or <tt>__weak</tt>, and</li>
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	935	<li>it would be legal to initialize a <tt>T __strong *</tt> with
				936	a <tt>U __strong *</tt>.</li>
				937	</ul>
				938
				939	<p>For purposes of overload resolution, an implicit conversion
				940	sequence requiring a pass-by-writeback is always worse than an
				941	implicit conversion sequence not requiring a pass-by-writeback.</p>
				942
				943	<p>The pass-by-writeback is ill-formed if the argument expression does
				944	not have a legal form:</p>
				945
				946	<ul>
Benjamin Kramer	665a8dc	2012-01-15 15:26:07 +0000	[diff] [blame]	947	<li><tt>&var</tt>, where <tt>var</tt> is a scalar variable of
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	948	automatic storage duration with retainable object pointer type</li>
				949	<li>a conditional expression where the second and third operands are
				950	both legal forms</li>
				951	<li>a cast whose operand is a legal form</li>
				952	<li>a null pointer constant</li>
				953	</ul>
				954
				955	<div class="rationale"><p>Rationale: the restriction in the form of
				956	the argument serves two purposes. First, it makes it impossible to
				957	pass the address of an array to the argument, which serves to protect
				958	against an otherwise serious risk of mis-inferring an <q>array</q>
				959	argument as an out-parameter. Second, it makes it much less likely
				960	that the user will see confusing aliasing problems due to the
				961	implementation, below, where their store to the writeback temporary is
				962	not immediately seen in the original argument variable.</p></div>
				963
Benjamin Kramer	665a8dc	2012-01-15 15:26:07 +0000	[diff] [blame]	964	<p>A pass-by-writeback is evaluated as follows:</p>
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	965	<ol>
				966	<li>The argument is evaluated to yield a pointer <tt>p</tt> of
				967	type <tt>U oq *</tt>.</li>
				968	<li>If <tt>p</tt> is a null pointer, then a null pointer is passed as
				969	the argument, and no further work is required for the pass-by-writeback.</li>
				970	<li>Otherwise, a temporary of type <tt>T __autoreleasing</tt> is
				971	created and initialized to a null pointer.</li>
				972	<li>If the argument is not an Objective-C method parameter marked
				973	<tt>out</tt>, then <tt>*p</tt> is read, and the result is written
				974	into the temporary with primitive semantics.</li>
				975	<li>The address of the temporary is passed as the argument to the
				976	actual call.</li>
				977	<li>After the call completes, the temporary is loaded with primitive
				978	semantics, and that value is assigned into <tt>*p</tt>.</li>
Benjamin Kramer	665a8dc	2012-01-15 15:26:07 +0000	[diff] [blame]	979	</ol>
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	980
				981	<div class="rationale"><p>Rationale: this is all admittedly
				982	convoluted. In an ideal world, we would see that a local variable is
				983	being passed to an out-parameter and retroactively modify its type to
				984	be <tt>__autoreleasing</tt> rather than <tt>__strong</tt>. This would
				985	be remarkably difficult and not always well-founded under the C type
				986	system. However, it was judged unacceptably invasive to require
				987	programmers to write <tt>__autoreleasing</tt> on all the variables
				988	they intend to use for out-parameters. This was the least bad
				989	solution.</p></div>
				990
				991	</div>
				992
				993	<div id="ownership.restrictions.records">
				994	<h1>Ownership-qualified fields of structs and unions</h1>
				995
				996	<p>A program is ill-formed if it declares a member of a C struct or
				997	union to have a nontrivially ownership-qualified type.</p>
				998
				999	<div class="rationale"><p>Rationale: the resulting type would be
				1000	non-POD in the C++ sense, but C does not give us very good language
				1001	tools for managing the lifetime of aggregates, so it is more
				1002	convenient to simply forbid them. It is still possible to manage this
				1003	with a <tt>void*</tt> or an <tt>__unsafe_unretained</tt>
				1004	object.</p></div>
				1005
				1006	<p>This restriction does not apply in Objective-C++. However,
David Blaikie	5090e9f	2011-10-18 05:49:30 +0000	[diff] [blame]	1007	nontrivally ownership-qualified types are considered non-POD: in C++11
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	1008	terms, they are not trivially default constructible, copy
				1009	constructible, move constructible, copy assignable, move assignable,
				1010	or destructible. It is a violation of C++ One Definition Rule to use
				1011	a class outside of ARC that, under ARC, would have an
				1012	ownership-qualified member.</p>
				1013
				1014	<div class="rationale"><p>Rationale: unlike in C, we can express all
				1015	the necessary ARC semantics for ownership-qualified subobjects as
				1016	suboperations of the (default) special member functions for the class.
				1017	These functions then become non-trivial. This has the non-obvious
				1018	repercussion that the class will have a non-trivial copy constructor
				1019	and non-trivial destructor; if it wouldn't outside of ARC, this means
				1020	that objects of the type will be passed and returned in an
				1021	ABI-incompatible manner.</p></div>
				1022
				1023	</div>
				1024
				1025	</div>
				1026
				1027	<div id="ownership.inference">
				1028	<h1>Ownership inference</h1>
				1029
				1030	<div id="ownership.inference.variables">
				1031	<h1>Objects</h1>
				1032
				1033	<p>If an object is declared with retainable object owner type, but
				1034	without an explicit ownership qualifier, its type is implicitly
				1035	adjusted to have <tt>__strong</tt> qualification.</p>
				1036
				1037	<p>As a special case, if the object's base type is <tt>Class</tt>
				1038	(possibly protocol-qualified), the type is adjusted to
				1039	have <tt>__unsafe_unretained</tt> qualification instead.</p>
				1040
				1041	</div>
				1042
				1043	<div id="ownership.inference.indirect_parameters">
				1044	<h1>Indirect parameters</h1>
				1045
				1046	<p>If a function or method parameter has type <tt>T*</tt>, where
				1047	<tt>T</tt> is an ownership-unqualified retainable object pointer type,
				1048	then:</p>
				1049
				1050	<ul>
				1051	<li>if <tt>T</tt> is <tt>const</tt>-qualified or <tt>Class</tt>, then
				1052	it is implicitly qualified with <tt>__unsafe_unretained</tt>;</li>
				1053	<li>otherwise, it is implicitly qualified
				1054	with <tt>__autoreleasing</tt>.</li>
				1055	</ul>
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	1056
				1057	<div class="rationale"><p>Rationale: <tt>__autoreleasing</tt> exists
				1058	mostly for this case, the Cocoa convention for out-parameters. Since
				1059	a pointer to <tt>const</tt> is obviously not an out-parameter, we
				1060	instead use a type more useful for passing arrays. If the user
				1061	instead intends to pass in a <em>mutable</em> array, inferring
				1062	<tt>__autoreleasing</tt> is the wrong thing to do; this directs some
				1063	of the caution in the following rules about writeback.</p></div>
				1064
				1065	<p>Such a type written anywhere else would be ill-formed by the
				1066	general rule requiring ownership qualifiers.</p>
				1067
				1068	<p>This rule does not apply in Objective-C++ if a parameter's type is
				1069	dependent in a template pattern and is only <em>instantiated</em> to
				1070	a type which would be a pointer to an unqualified retainable object
				1071	pointer type. Such code is still ill-formed.</p>
				1072
				1073	<div class="rationale"><p>Rationale: the convention is very unlikely
				1074	to be intentional in template code.</p></div>
				1075
				1076	</div> <!-- ownership.inference.indirect_parameters -->
Douglas Gregor	e559ca1	2011-06-17 22:11:49 +0000	[diff] [blame]	1077
				1078	<div id="ownership.inference.template_arguments">
				1079	<h1>Template arguments</h1>
				1080
				1081	<p>If a template argument for a template type parameter is an
				1082	retainable object owner type that does not have an explicit ownership
				1083	qualifier, it is adjusted to have <tt>__strong</tt>
Douglas Gregor	54fb28a	2011-06-17 22:19:27 +0000	[diff] [blame]	1084	qualification. This adjustment occurs regardless of whether the
Douglas Gregor	e559ca1	2011-06-17 22:11:49 +0000	[diff] [blame]	1085	template argument was deduced or explicitly specified. </p>
				1086
				1087	<div class="rationale"><p>Rationale: <tt>__strong</tt> is a useful default for containers (e.g., <tt>std::vector<id></tt>), which would otherwise require explicit qualification. Moreover, unqualified retainable object pointer types are unlikely to be useful within templates, since they generally need to have a qualifier applied to the before being used.</p></div>
				1088
				1089	</div> <!-- ownership.inference.template_arguments -->
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	1090	</div> <!-- ownership.inference -->
				1091	</div> <!-- ownership -->
				1092
Douglas Gregor	e559ca1	2011-06-17 22:11:49 +0000	[diff] [blame]	1093
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	1094	<div id="family">
				1095	<h1>Method families</h1>
				1096
				1097	<p>An Objective-C method may fall into a <span class="term">method
				1098	family</span>, which is a conventional set of behaviors ascribed to it
				1099	by the Cocoa conventions.</p>
				1100
Benjamin Kramer	665a8dc	2012-01-15 15:26:07 +0000	[diff] [blame]	1101	<p>A method is in a certain method family if:</p>
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	1102	<ul>
				1103	<li>it has a <tt>objc_method_family</tt> attribute placing it in that
				1104	family; or if not that,</li>
				1105	<li>it does not have an <tt>objc_method_family</tt> attribute placing
				1106	it in a different or no family, and</li>
				1107	<li>its selector falls into the corresponding selector family, and</li>
				1108	<li>its signature obeys the added restrictions of the method family.</li>
Benjamin Kramer	665a8dc	2012-01-15 15:26:07 +0000	[diff] [blame]	1109	</ul>
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	1110
				1111	<p>A selector is in a certain selector family if, ignoring any leading
				1112	underscores, the first component of the selector either consists
				1113	entirely of the name of the method family or it begins with that name
				1114	followed by a character other than a lowercase letter. For
				1115	example, <tt>_perform:with:</tt> and <tt>performWith:</tt> would fall
				1116	into the <tt>perform</tt> family (if we recognized one),
				1117	but <tt>performing:with</tt> would not.</p>
				1118
				1119	<p>The families and their added restrictions are:</p>
				1120
				1121	<ul>
				1122	<li><tt>alloc</tt> methods must return a retainable object pointer type.</li>
				1123	<li><tt>copy</tt> methods must return a retainable object pointer type.</li>
				1124	<li><tt>mutableCopy</tt> methods must return a retainable object pointer type.</li>
				1125	<li><tt>new</tt> methods must return a retainable object pointer type.</li>
				1126	<li><tt>init</tt> methods must be instance methods and must return an
				1127	Objective-C pointer type. Additionally, a program is ill-formed if it
				1128	declares or contains a call to an <tt>init</tt> method whose return
				1129	type is neither <tt>id</tt> nor a pointer to a super-class or
John McCall	be16b89	2011-06-18 08:15:19 +0000	[diff] [blame]	1130	sub-class of the declaring class (if the method was declared on
				1131	a class) or the static receiver type of the call (if it was declared
Benjamin Kramer	665a8dc	2012-01-15 15:26:07 +0000	[diff] [blame]	1132	on a protocol).
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	1133
				1134	<div class="rationale"><p>Rationale: there are a fair number of existing
				1135	methods with <tt>init</tt>-like selectors which nonetheless don't
				1136	follow the <tt>init</tt> conventions. Typically these are either
				1137	accidental naming collisions or helper methods called during
				1138	initialization. Because of the peculiar retain/release behavior
				1139	of <tt>init</tt> methods, it's very important not to treat these
				1140	methods as <tt>init</tt> methods if they aren't meant to be. It was
				1141	felt that implicitly defining these methods out of the family based on
				1142	the exact relationship between the return type and the declaring class
John McCall	be16b89	2011-06-18 08:15:19 +0000	[diff] [blame]	1143	would be much too subtle and fragile. Therefore we identify a small
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	1144	number of legitimate-seeming return types and call everything else an
				1145	error. This serves the secondary purpose of encouraging programmers
John McCall	be16b89	2011-06-18 08:15:19 +0000	[diff] [blame]	1146	not to accidentally give methods names in the <tt>init</tt> family.</p>
				1147
				1148	<p>Note that a method with an <tt>init</tt>-family selector which
				1149	returns a non-Objective-C type (e.g. <tt>void</tt>) is perfectly
				1150	well-formed; it simply isn't in the <tt>init</tt> family.</p></div>
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	1151	</li>
				1152	</ul>
				1153
				1154	<p>A program is ill-formed if a method's declarations,
				1155	implementations, and overrides do not all have the same method
				1156	family.</p>
				1157
				1158	<div id="family.attribute">
				1159	<h1>Explicit method family control</h1>
				1160
				1161	<p>A method may be annotated with the <tt>objc_method_family</tt>
				1162	attribute to precisely control which method family it belongs to. If
				1163	a method in an <tt>@implementation</tt> does not have this attribute,
				1164	but there is a method declared in the corresponding <tt>@interface</tt>
				1165	that does, then the attribute is copied to the declaration in the
				1166	<tt>@implementation</tt>. The attribute is available outside of ARC,
				1167	and may be tested for with the preprocessor query
				1168	<tt>__has_attribute(objc_method_family)</tt>.</p>
				1169
				1170	<p>The attribute is spelled
				1171	<tt>__attribute__((objc_method_family(<i>family</i>)))</tt>.
				1172	If <i>family</i> is <tt>none</tt>, the method has no family, even if
				1173	it would otherwise be considered to have one based on its selector and
				1174	type. Otherwise, <i>family</i> must be one
				1175	of <tt>alloc</tt>, <tt>copy</tt>, <tt>init</tt>,
				1176	<tt>mutableCopy</tt>, or <tt>new</tt>, in which case the method is
				1177	considered to belong to the corresponding family regardless of its
				1178	selector. It is an error if a method that is explicitly added to a
				1179	family in this way does not meet the requirements of the family other
				1180	than the selector naming convention.</p>
				1181
				1182	<div class="rationale"><p>Rationale: the rules codified in this document
				1183	describe the standard conventions of Objective-C. However, as these
				1184	conventions have not heretofore been enforced by an unforgiving
				1185	mechanical system, they are only imperfectly kept, especially as they
				1186	haven't always even been precisely defined. While it is possible to
				1187	define low-level ownership semantics with attributes like
				1188	<tt>ns_returns_retained</tt>, this attribute allows the user to
				1189	communicate semantic intent, which of use both to ARC (which, e.g.,
				1190	treats calls to <tt>init</tt> specially) and the static analyzer.</p></div>
				1191	</div>
				1192
				1193	<div id="family.semantics">
				1194	<h1>Semantics of method families</h1>
				1195
				1196	<p>A method's membership in a method family may imply non-standard
				1197	semantics for its parameters and return type.</p>
				1198
				1199	<p>Methods in the <tt>alloc</tt>, <tt>copy</tt>, <tt>mutableCopy</tt>,
				1200	and <tt>new</tt> families — that is, methods in all the
John McCall	be16b89	2011-06-18 08:15:19 +0000	[diff] [blame]	1201	currently-defined families except <tt>init</tt> — implicitly
				1202	<a href="#objects.operands.retained_returns">return a retained
				1203	object</a> as if they were annotated with
				1204	the <tt>ns_returns_retained</tt> attribute. This can be overridden by
				1205	annotating the method with either of
				1206	the <tt>ns_returns_autoreleased</tt> or
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	1207	<tt>ns_returns_not_retained</tt> attributes.</p>
				1208
Fariborz Jahanian	acd4aaf	2011-07-06 22:47:46 +0000	[diff] [blame]	1209	<p>Properties also follow same naming rules as methods. This means that
				1210	those in the <tt>alloc</tt>, <tt>copy</tt>, <tt>mutableCopy</tt>,
				1211	and <tt>new</tt> families provide access to
				1212	<a href="#objects.operands.retained_returns">retained objects</a>.
				1213	This can be overridden by annotating the property with
				1214	<tt>ns_returns_not_retained</tt> attribute.</p>
				1215
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	1216	<div id="family.semantics.init">
				1217	<h1>Semantics of <tt>init</tt></h1>
John McCall	be16b89	2011-06-18 08:15:19 +0000	[diff] [blame]	1218	<p>Methods in the <tt>init</tt> family implicitly
				1219	<a href="#objects.operands.consumed">consume</a> their <tt>self</tt>
				1220	parameter and <a href="#objects.operands.retained_returns">return a
				1221	retained object</a>. Neither of these properties can be altered
				1222	through attributes.</p>
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	1223
				1224	<p>A call to an <tt>init</tt> method with a receiver that is either
				1225	<tt>self</tt> (possibly parenthesized or casted) or <tt>super</tt> is
				1226	called a <span class="term">delegate init call</span>. It is an error
				1227	for a delegate init call to be made except from an <tt>init</tt>
				1228	method, and excluding blocks within such methods.</p>
				1229
John McCall	be16b89	2011-06-18 08:15:19 +0000	[diff] [blame]	1230	<p>As an exception to the <a href="misc.self">usual rule</a>, the
				1231	variable <tt>self</tt> is mutable in an <tt>init</tt> method and has
				1232	the usual semantics for a <tt>__strong</tt> variable. However, it is
				1233	undefined behavior and the program is ill-formed, no diagnostic
				1234	required, if an <tt>init</tt> method attempts to use the previous
				1235	value of <tt>self</tt> after the completion of a delegate init call.
				1236	It is conventional, but not required, for an <tt>init</tt> method to
				1237	return <tt>self</tt>.</p>
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	1238
John McCall	be16b89	2011-06-18 08:15:19 +0000	[diff] [blame]	1239	<p>It is undefined behavior for a program to cause two or more calls
				1240	to <tt>init</tt> methods on the same object, except that
				1241	each <tt>init</tt> method invocation may perform at most one delegate
				1242	init call.</p>
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	1243
John McCall	f3d08a6	2011-06-18 07:31:30 +0000	[diff] [blame]	1244	</div> <!-- family.semantics.init -->
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	1245
				1246	<div id="family.semantics.result_type">
				1247	<h1>Related result types</h1>
				1248
				1249	<p>Certain methods are candidates to have <span class="term">related
				1250	result types</span>:</p>
				1251	<ul>
				1252	<li>class methods in the <tt>alloc</tt> and <tt>new</tt> method families</li>
				1253	<li>instance methods in the <tt>init</tt> family</li>
				1254	<li>the instance method <tt>self</tt></li>
				1255	<li>outside of ARC, the instance methods <tt>retain</tt> and <tt>autorelease</tt></li>
				1256	</ul>
				1257
				1258	<p>If the formal result type of such a method is <tt>id</tt> or
				1259	protocol-qualified <tt>id</tt>, or a type equal to the declaring class
				1260	or a superclass, then it is said to have a related result type. In
				1261	this case, when invoked in an explicit message send, it is assumed to
				1262	return a type related to the type of the receiver:</p>
				1263
				1264	<ul>
				1265	<li>if it is a class method, and the receiver is a class
				1266	name <tt>T</tt>, the message send expression has type <tt>T*</tt>;
				1267	otherwise</li>
				1268	<li>if it is an instance method, and the receiver has type <tt>T</tt>,
				1269	the message send expression has type <tt>T</tt>; otherwise</li>
				1270	<li>the message send expression has the normal result type of the
				1271	method.</li>
				1272	</ul>
				1273
				1274	<p>This is a new rule of the Objective-C language and applies outside
				1275	of ARC.</p>
				1276
				1277	<div class="rationale"><p>Rationale: ARC's automatic code emission is
				1278	more prone than most code to signature errors, i.e. errors where a
				1279	call was emitted against one method signature, but the implementing
				1280	method has an incompatible signature. Having more precise type
				1281	information helps drastically lower this risks, as well as catching
				1282	a number of latent bugs.</p></div>
				1283
				1284	</div> <!-- family.semantics.result_type -->
				1285	</div> <!-- family.semantics -->
				1286	</div> <!-- family -->
				1287
				1288	<div id="optimization">
				1289	<h1>Optimization</h1>
				1290
				1291	<p>ARC applies aggressive rules for the optimization of local
				1292	behavior. These rules are based around a core assumption of
				1293	<span class="term">local balancing</span>: that other code will
				1294	perform retains and releases as necessary (and only as necessary) for
				1295	its own safety, and so the optimizer does not need to consider global
				1296	properties of the retain and release sequence. For example, if a
				1297	retain and release immediately bracket a call, the optimizer can
				1298	delete the retain and release on the assumption that the called
				1299	function will not do a constant number of unmotivated releases
				1300	followed by a constant number of <q>balancing</q> retains, such that
				1301	the local retain/release pair is the only thing preventing the called
				1302	function from ending up with a dangling reference.</p>
				1303
				1304	<p>The optimizer assumes that when a new value enters local control,
				1305	e.g. from a load of a non-local object or as the result of a function
				1306	call, it is instaneously valid. Subsequently, a retain and release of
				1307	a value are necessary on a computation path only if there is a use of
				1308	that value before the release and after any operation which might
				1309	cause a release of the value (including indirectly or non-locally),
				1310	and only if the value is not demonstrably already retained.</p>
				1311
				1312	<p>The complete optimization rules are quite complicated, but it would
				1313	still be useful to document them here.</p>
				1314
John McCall	dc7c5ad	2011-07-22 08:53:00 +0000	[diff] [blame]	1315	<div id="optimization.precise">
				1316	<h1>Precise lifetime semantics</h1>
				1317
				1318	<p>In general, ARC maintains an invariant that a retainable object
				1319	pointer held in a <tt>__strong</tt> object will be retained for the
				1320	full formal lifetime of the object. Objects subject to this invariant
				1321	have <span class="term">precise lifetime semantics</span>.</p>
				1322
				1323	<p>By default, local variables of automatic storage duration do not
				1324	have precise lifetime semantics. Such objects are simply strong
				1325	references which hold values of retainable object pointer type, and
				1326	these values are still fully subject to the optimizations on values
				1327	under local control.</p>
				1328
				1329	<div class="rationale"><p>Rationale: applying these precise-lifetime
				1330	semantics strictly would be prohibitive. Many useful optimizations
				1331	that might theoretically decrease the lifetime of an object would be
				1332	rendered impossible. Essentially, it promises too much.</p></div>
				1333
				1334	<p>A local variable of retainable object owner type and automatic
				1335	storage duration may be annotated with the <tt>objc_precise_lifetime</tt>
				1336	attribute to indicate that it should be considered to be an object
				1337	with precise lifetime semantics.</p>
				1338
				1339	<div class="rationale"><p>Rationale: nonetheless, it is sometimes
				1340	useful to be able to force an object to be released at a precise time,
				1341	even if that object does not appear to be used. This is likely to be
				1342	uncommon enough that the syntactic weight of explicitly requesting
				1343	these semantics will not be burdensome, and may even make the code
				1344	clearer.</p></div>
				1345
				1346	</div> <!-- optimization.precise -->
				1347
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	1348	</div>
				1349
				1350	<div id="misc">
				1351	<h1>Miscellaneous</h1>
				1352
John McCall	f3d08a6	2011-06-18 07:31:30 +0000	[diff] [blame]	1353	<div id="misc.special_methods">
				1354	<h1>Special methods</h1>
				1355
				1356	<div id="misc.special_methods.retain">
				1357	<h1>Memory management methods</h1>
				1358
				1359	<p>A program is ill-formed if it contains a method definition, message
				1360	send, or <tt>@selector</tt> expression for any of the following
Benjamin Kramer	665a8dc	2012-01-15 15:26:07 +0000	[diff] [blame]	1361	selectors:</p>
John McCall	f3d08a6	2011-06-18 07:31:30 +0000	[diff] [blame]	1362	<ul>
				1363	<li><tt>autorelease</tt></li>
				1364	<li><tt>release</tt></li>
				1365	<li><tt>retain</tt></li>
				1366	<li><tt>retainCount</tt></li>
				1367	</ul>
John McCall	f3d08a6	2011-06-18 07:31:30 +0000	[diff] [blame]	1368
				1369	<div class="rationale"><p>Rationale: <tt>retainCount</tt> is banned
				1370	because ARC robs it of consistent semantics. The others were banned
				1371	after weighing three options for how to deal with message sends:</p>
				1372
				1373	<p><b>Honoring</b> them would work out very poorly if a programmer
				1374	naively or accidentally tried to incorporate code written for manual
				1375	retain/release code into an ARC program. At best, such code would do
				1376	twice as much work as necessary; quite frequently, however, ARC and
				1377	the explicit code would both try to balance the same retain, leading
				1378	to crashes. The cost is losing the ability to perform <q>unrooted</q>
				1379	retains, i.e. retains not logically corresponding to a strong
				1380	reference in the object graph.</p>
				1381
				1382	<p><b>Ignoring</b> them would badly violate user expectations about their
				1383	code. While it <em>would</em> make it easier to develop code simultaneously
				1384	for ARC and non-ARC, there is very little reason to do so except for
				1385	certain library developers. ARC and non-ARC translation units share
				1386	an execution model and can seamlessly interoperate. Within a
				1387	translation unit, a developer who faithfully maintains their code in
				1388	non-ARC mode is suffering all the restrictions of ARC for zero
				1389	benefit, while a developer who isn't testing the non-ARC mode is
				1390	likely to be unpleasantly surprised if they try to go back to it.</p>
				1391
				1392	<p><b>Banning</b> them has the disadvantage of making it very awkward
				1393	to migrate existing code to ARC. The best answer to that, given a
				1394	number of other changes and restrictions in ARC, is to provide a
				1395	specialized tool to assist users in that migration.</p>
				1396
				1397	<p>Implementing these methods was banned because they are too integral
				1398	to the semantics of ARC; many tricks which worked tolerably under
				1399	manual reference counting will misbehave if ARC performs an ephemeral
				1400	extra retain or two. If absolutely required, it is still possible to
				1401	implement them in non-ARC code, for example in a category; the
				1402	implementations must obey the <a href="#objects.retains">semantics</a>
				1403	laid out elsewhere in this document.</p>
				1404
				1405	</div>
				1406	</div> <!-- misc.special_methods.retain -->
				1407
				1408	<div id="misc.special_methods.dealloc">
				1409	<h1><tt>dealloc</tt></h1>
				1410
				1411	<p>A program is ill-formed if it contains a message send
				1412	or <tt>@selector</tt> expression for the selector <tt>dealloc</tt>.</p>
				1413
				1414	<div class="rationale"><p>Rationale: there are no legitimate reasons
				1415	to call <tt>dealloc</tt> directly.</p></div>
				1416
				1417	<p>A class may provide a method definition for an instance method
				1418	named <tt>dealloc</tt>. This method will be called after the final
				1419	<tt>release</tt> of the object but before it is deallocated or any of
				1420	its instance variables are destroyed. The superclass's implementation
				1421	of <tt>dealloc</tt> will be called automatically when the method
				1422	returns.</p>
				1423
				1424	<div class="rationale"><p>Rationale: even though ARC destroys instance
				1425	variables automatically, there are still legitimate reasons to write
				1426	a <tt>dealloc</tt> method, such as freeing non-retainable resources.
				1427	Failing to call <tt>[super dealloc]</tt> in such a method is nearly
				1428	always a bug. Sometimes, the object is simply trying to prevent
				1429	itself from being destroyed, but <tt>dealloc</tt> is really far too
				1430	late for the object to be raising such objections. Somewhat more
				1431	legitimately, an object may have been pool-allocated and should not be
				1432	deallocated with <tt>free</tt>; for now, this can only be supported
				1433	with a <tt>dealloc</tt> implementation outside of ARC. Such an
				1434	implementation must be very careful to do all the other work
				1435	that <tt>NSObject</tt>'s <tt>dealloc</tt> would, which is outside the
				1436	scope of this document to describe.</p></div>
				1437
				1438	</div>
				1439
				1440	</div> <!-- misc.special_methods -->
				1441
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	1442	<div id="autoreleasepool">
				1443	<h1><tt>@autoreleasepool</tt></h1>
				1444
				1445	<p>To simplify the use of autorelease pools, and to bring them under
				1446	the control of the compiler, a new kind of statement is available in
				1447	Objective-C. It is written <tt>@autoreleasepool</tt> followed by
				1448	a <i>compound-statement</i>, i.e. by a new scope delimited by curly
				1449	braces. Upon entry to this block, the current state of the
				1450	autorelease pool is captured. When the block is exited normally,
				1451	whether by fallthrough or directed control flow (such
				1452	as <tt>return</tt> or <tt>break</tt>), the autorelease pool is
				1453	restored to the saved state, releasing all the objects in it. When
				1454	the block is exited with an exception, the pool is not drained.</p>
				1455
John McCall	f3d08a6	2011-06-18 07:31:30 +0000	[diff] [blame]	1456	<p><tt>@autoreleasepool</tt> may be used in non-ARC translation units,
				1457	with equivalent semantics.</p>
				1458
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	1459	<p>A program is ill-formed if it refers to the
				1460	<tt>NSAutoreleasePool</tt> class.</p>
				1461
				1462	<div class="rationale"><p>Rationale: autorelease pools are clearly
				1463	important for the compiler to reason about, but it is far too much to
				1464	expect the compiler to accurately reason about control dependencies
				1465	between two calls. It is also very easy to accidentally forget to
				1466	drain an autorelease pool when using the manual API, and this can
				1467	significantly inflate the process's high-water-mark. The introduction
				1468	of a new scope is unfortunate but basically required for sane
				1469	interaction with the rest of the language. Not draining the pool
				1470	during an unwind is apparently required by the Objective-C exceptions
				1471	implementation.</p></div>
				1472
				1473	</div> <!-- autoreleasepool -->
				1474
				1475	<div id="misc.self">
				1476	<h1><tt>self</tt></h1>
				1477
				1478	<p>The <tt>self</tt> parameter variable of an Objective-C method is
				1479	never actually retained by the implementation. It is undefined
				1480	behavior, or at least dangerous, to cause an object to be deallocated
Ted Kremenek	2bbcd5c	2011-11-14 21:59:25 +0000	[diff] [blame]	1481	during a message send to that object.</p>
				1482
				1483	<p>To make this safe, for Objective-C instance methods <tt>self</tt> is
				1484	implicitly <tt>const</tt> unless the method is in the <a
				1485	href="#family.semantics.init"><tt>init</tt> family</a>. Further, <tt>self</tt>
				1486	is <b>always</b> implicitly <tt>const</tt> within a class method.</p>
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	1487
				1488	<div class="rationale"><p>Rationale: the cost of
				1489	retaining <tt>self</tt> in all methods was found to be prohibitive, as
				1490	it tends to be live across calls, preventing the optimizer from
				1491	proving that the retain and release are unnecessary — for good
				1492	reason, as it's quite possible in theory to cause an object to be
				1493	deallocated during its execution without this retain and release.
				1494	Since it's extremely uncommon to actually do so, even unintentionally,
				1495	and since there's no natural way for the programmer to remove this
				1496	retain/release pair otherwise (as there is for other parameters by,
				1497	say, making the variable <tt>__unsafe_unretained</tt>), we chose to
				1498	make this optimizing assumption and shift some amount of risk to the
				1499	user.</p></div>
				1500
				1501	</div> <!-- misc.self -->
				1502
				1503	<div id="misc.enumeration">
				1504	<h1>Fast enumeration iteration variables</h1>
				1505
				1506	<p>If a variable is declared in the condition of an Objective-C fast
				1507	enumeration loop, and the variable has no explicit ownership
				1508	qualifier, then it is qualified with <tt>const __strong</tt> and
				1509	objects encountered during the enumeration are not actually
				1510	retained.</p>
				1511
				1512	<div class="rationale"><p>Rationale: this is an optimization made
				1513	possible because fast enumeration loops promise to keep the objects
				1514	retained during enumeration, and the collection itself cannot be
				1515	synchronously modified. It can be overridden by explicitly qualifying
				1516	the variable with <tt>__strong</tt>, which will make the variable
				1517	mutable again and cause the loop to retain the objects it
Benjamin Kramer	665a8dc	2012-01-15 15:26:07 +0000	[diff] [blame]	1518	encounters.</p></div>
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	1519
				1520	</div>
				1521
				1522	<div id="misc.blocks">
				1523	<h1>Blocks</h1>
				1524
				1525	<p>The implicit <tt>const</tt> capture variables created when
				1526	evaluating a block literal expression have the same ownership
				1527	semantics as the local variables they capture. The capture is
				1528	performed by reading from the captured variable and initializing the
				1529	capture variable with that value; the capture variable is destroyed
				1530	when the block literal is, i.e. at the end of the enclosing scope.</p>
				1531
				1532	<p>The <a href="#ownership.inference">inference</a> rules apply
				1533	equally to <tt>__block</tt> variables, which is a shift in semantics
				1534	from non-ARC, where <tt>__block</tt> variables did not implicitly
				1535	retain during capture.</p>
				1536
				1537	<p><tt>__block</tt> variables of retainable object owner type are
				1538	moved off the stack by initializing the heap copy with the result of
Benjamin Kramer	665a8dc	2012-01-15 15:26:07 +0000	[diff] [blame]	1539	moving from the stack copy.</p>
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	1540
				1541	<p>With the exception of retains done as part of initializing
				1542	a <tt>__strong</tt> parameter variable or reading a <tt>__weak</tt>
				1543	variable, whenever these semantics call for retaining a value of
				1544	block-pointer type, it has the effect of a <tt>Block_copy</tt>. The
				1545	optimizer may remove such copies when it sees that the result is
				1546	used only as an argument to a call.</p>
				1547
				1548	</div> <!-- misc.blocks -->
				1549
				1550	<div id="misc.exceptions">
				1551	<h1>Exceptions</h1>
				1552
				1553	<p>By default in Objective C, ARC is not exception-safe for normal
Benjamin Kramer	665a8dc	2012-01-15 15:26:07 +0000	[diff] [blame]	1554	releases:</p>
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	1555	<ul>
				1556	<li>It does not end the lifetime of <tt>__strong</tt> variables when
				1557	their scopes are abnormally terminated by an exception.</li>
				1558	<li>It does not perform releases which would occur at the end of
				1559	a full-expression if that full-expression throws an exception.</li>
				1560	</ul>
				1561
				1562	<p>A program may be compiled with the option
				1563	<tt>-fobjc-arc-exceptions</tt> in order to enable these, or with the
				1564	option <tt>-fno-objc-arc-exceptions</tt> to explicitly disable them,
				1565	with the last such argument <q>winning</q>.</p>
				1566
				1567	<div class="rationale"><p>Rationale: the standard Cocoa convention is
				1568	that exceptions signal programmer error and are not intended to be
				1569	recovered from. Making code exceptions-safe by default would impose
				1570	severe runtime and code size penalties on code that typically does not
				1571	actually care about exceptions safety. Therefore, ARC-generated code
				1572	leaks by default on exceptions, which is just fine if the process is
				1573	going to be immediately terminated anyway. Programs which do care
				1574	about recovering from exceptions should enable the option.</p></div>
				1575
				1576	<p>In Objective-C++, <tt>-fobjc-arc-exceptions</tt> is enabled by
				1577	default.</p>
				1578
				1579	<div class="rationale"><p>Rationale: C++ already introduces pervasive
				1580	exceptions-cleanup code of the sort that ARC introduces. C++
				1581	programmers who have not already disabled exceptions are much more
				1582	likely to actual require exception-safety.</p></div>
				1583
				1584	<p>ARC does end the lifetimes of <tt>__weak</tt> objects when an
				1585	exception terminates their scope unless exceptions are disabled in the
				1586	compiler.</p>
				1587
				1588	<div class="rationale"><p>Rationale: the consequence of a
				1589	local <tt>__weak</tt> object not being destroyed is very likely to be
				1590	corruption of the Objective-C runtime, so we want to be safer here.
				1591	Of course, potentially massive leaks are about as likely to take down
				1592	the process as this corruption is if the program does try to recover
				1593	from exceptions.</p></div>
				1594
				1595	</div> <!-- misc.exceptions -->
				1596
John McCall	dc7c5ad	2011-07-22 08:53:00 +0000	[diff] [blame]	1597	<div id="misc.interior">
				1598	<h1>Interior pointers</h1>
				1599
				1600	<p>An Objective-C method returning a non-retainable pointer may be
				1601	annotated with the <tt>objc_returns_inner_pointer</tt> attribute to
				1602	indicate that it returns a handle to the internal data of an object,
				1603	and that this reference will be invalidated if the object is
				1604	destroyed. When such a message is sent to an object, the object's
				1605	lifetime will be extended until at least the earliest of:</p>
				1606
				1607	<ul>
				1608	<li>the last use of the returned pointer, or any pointer derived from
				1609	it, in the calling function or</li>
				1610	<li>the autorelease pool is restored to a previous state.</li>
				1611	</ul>
				1612
				1613	<div class="rationale"><p>Rationale: not all memory and resources are
				1614	managed with reference counts; it is common for objects to manage
				1615	private resources in their own, private way. Typically these
				1616	resources are completely encapsulated within the object, but some
				1617	classes offer their users direct access for efficiency. If ARC is not
				1618	aware of methods that return such <q>interior</q> pointers, its
				1619	optimizations can cause the owning object to be reclaimed too soon.
				1620	This attribute informs ARC that it must tread lightly.</p>
				1621
				1622	<p>The extension rules are somewhat intentionally vague. The
				1623	autorelease pool limit is there to permit a simple implementation to
				1624	simply retain and autorelease the receiver. The other limit permits
				1625	some amount of optimization. The phrase <q>derived from</q> is
				1626	intended to encompass the results both of pointer transformations,
				1627	such as casts and arithmetic, and of loading from such derived
				1628	pointers; furthermore, it applies whether or not such derivations are
				1629	applied directly in the calling code or by other utility code (for
				1630	example, the C library routine <tt>strchr</tt>). However, the
				1631	implementation never need account for uses after a return from the
				1632	code which calls the method returning an interior pointer.</p></div>
				1633
				1634	<p>As an exception, no extension is required if the receiver is loaded
				1635	directly from a <tt>__strong</tt> object
				1636	with <a href="#optimization.precise">precise lifetime semantics</a>.</p>
				1637
				1638	<div class="rationale"><p>Rationale: implicit autoreleases carry the
				1639	risk of significantly inflating memory use, so it's important to
				1640	provide users a way of avoiding these autoreleases. Tying this to
				1641	precise lifetime semantics is ideal, as for local variables this
				1642	requires a very explicit annotation, which allows ARC to trust the
				1643	user with good cheer.</p></div>
				1644
				1645	</div> <!-- misc.interior -->
				1646
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	1647	</div> <!-- misc -->
John McCall	98a48cf	2011-06-19 09:36:02 +0000	[diff] [blame]	1648
				1649	<div id="runtime">
				1650	<h1>Runtime support</h1>
				1651
John McCall	085d09d	2011-06-19 10:12:24 +0000	[diff] [blame]	1652	<p>This section describes the interaction between the ARC runtime and
				1653	the code generated by the ARC compiler. This is not part of the ARC
				1654	language specification; instead, it is effectively a language-specific
				1655	ABI supplement, akin to the <q>Itanium</q> generic ABI for C++.</p>
John McCall	98a48cf	2011-06-19 09:36:02 +0000	[diff] [blame]	1656
				1657	<p>Ownership qualification does not alter the storage requirements for
John McCall	085d09d	2011-06-19 10:12:24 +0000	[diff] [blame]	1658	objects, except that it is undefined behavior if a <tt>__weak</tt>
				1659	object is inadequately aligned for an object of type <tt>id</tt>. The
				1660	other qualifiers may be used on explicitly under-aligned memory.</p>
John McCall	98a48cf	2011-06-19 09:36:02 +0000	[diff] [blame]	1661
				1662	<p>The runtime tracks <tt>__weak</tt> objects which holds non-null
John McCall	3914a30	2011-06-19 09:59:33 +0000	[diff] [blame]	1663	values. It is undefined behavior to direct modify a <tt>__weak</tt>
				1664	object which is being tracked by the runtime except through an
				1665	<a href="#runtime.objc_storeWeak"><tt>objc_storeWeak</tt></a>,
				1666	<a href="#runtime.objc_destroyWeak"><tt>objc_destroyWeak</tt></a>,
				1667	or <a href="#runtime.objc_moveWeak"><tt>objc_moveWeak</tt></a>
John McCall	98a48cf	2011-06-19 09:36:02 +0000	[diff] [blame]	1668	call.</p>
				1669
John McCall	3914a30	2011-06-19 09:59:33 +0000	[diff] [blame]	1670	<p>The runtime must provide a number of new entrypoints which the
				1671	compiler may emit, which are described in the remainder of this
				1672	section.</p>
				1673
				1674	<div class="rationale"><p>Rationale: Several of these functions are
				1675	semantically equivalent to a message send; we emit calls to C
				1676	functions instead because:</p>
				1677	<ul>
				1678	<li>the machine code to do so is significantly smaller,</li>
				1679	<li>it is much easier to recognize the C functions in the ARC optimizer, and</li>
				1680	<li>a sufficient sophisticated runtime may be able to avoid the
				1681	message send in common cases.</li>
				1682	</ul>
				1683
				1684	<p>Several other of these functions are <q>fused</q> operations which
				1685	can be described entirely in terms of other operations. We use the
				1686	fused operations primarily as a code-size optimization, although in
				1687	some cases there is also a real potential for avoiding redundant
				1688	operations in the runtime.</p>
				1689
				1690	</div>
				1691
John McCall	98a48cf	2011-06-19 09:36:02 +0000	[diff] [blame]	1692	<div id="runtime.objc_autorelease">
				1693	<h1><tt>id objc_autorelease(id value);</tt></h1>
				1694	<p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a
				1695	valid object.</p>
				1696	<p>If <tt>value</tt> is null, this call has no effect. Otherwise, it
				1697	adds the object to the innermost autorelease pool exactly as if the
				1698	object had been sent the <tt>autorelease</tt> message.</p>
				1699	<p>Always returns <tt>value</tt>.</p>
				1700	</div> <!-- runtime.objc_autorelease -->
				1701
				1702	<div id="runtime.objc_autoreleasePoolPop">
				1703	<h1><tt>void objc_autoreleasePoolPop(void *pool);</tt></h1>
				1704	<p><i>Precondition:</i> <tt>pool</tt> is the result of a previous call to
				1705	<a href="runtime.objc_autoreleasePoolPush"><tt>objc_autoreleasePoolPush</tt></a>
				1706	on the current thread, where neither <tt>pool</tt> nor any enclosing
				1707	pool have previously been popped.</p>
				1708	<p>Releases all the objects added to the given autorelease pool and
				1709	any autorelease pools it encloses, then sets the current autorelease
				1710	pool to the pool directly enclosing <tt>pool</tt>.</p>
				1711	</div> <!-- runtime.objc_autoreleasePoolPop -->
				1712
				1713	<div id="runtime.objc_autoreleasePoolPush">
				1714	<h1><tt>void *objc_autoreleasePoolPush(void);</tt></h1>
				1715	<p>Creates a new autorelease pool that is enclosed by the current
				1716	pool, makes that the current pool, and returns an opaque <q>handle</q>
				1717	to it.</p>
				1718
				1719	<div class="rationale"><p>Rationale: while the interface is described
				1720	as an explicit hierarchy of pools, the rules allow the implementation
				1721	to just keep a stack of objects, using the stack depth as the opaque
				1722	pool handle.</p></div>
				1723
				1724	</div> <!-- runtime.objc_autoreleasePoolPush -->
				1725
				1726	<div id="runtime.objc_autoreleaseReturnValue">
				1727	<h1><tt>id objc_autoreleaseReturnValue(id value);</tt></h1>
				1728	<p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a
				1729	valid object.</p>
				1730	<p>If <tt>value</tt> is null, this call has no effect. Otherwise, it
				1731	makes a best effort to hand off ownership of a retain count on the
				1732	object to a call
				1733	to <a href="runtime.objc_retainAutoreleasedReturnValue"><tt>objc_retainAutoreleasedReturnValue</tt></a>
				1734	for the same object in an enclosing call frame. If this is not
				1735	possible, the object is autoreleased as above.</p>
				1736	<p>Always returns <tt>value</tt>.</p>
				1737	</div> <!-- runtime.objc_autoreleaseReturnValue -->
				1738
				1739	<div id="runtime.objc_copyWeak">
				1740	<h1><tt>void objc_copyWeak(id dest, id src);</tt></h1>
				1741	<p><i>Precondition:</i> <tt>src</tt> is a valid pointer which either
				1742	contains a null pointer or has been registered as a <tt>__weak</tt>
				1743	object. <tt>dest</tt> is a valid pointer which has not been
				1744	registered as a <tt>__weak</tt> object.</p>
				1745	<p><tt>dest</tt> is initialized to be equivalent to <tt>src</tt>,
				1746	potentially registering it with the runtime. Equivalent to the
				1747	following code:</p>
				1748	<pre>void objc_copyWeak(id dest, id src) {
				1749	objc_release(objc_initWeak(dest, objc_loadWeakRetained(src)));
				1750	}</pre>
				1751	<p>Must be atomic with respect to calls to <tt>objc_storeWeak</tt>
				1752	on <tt>src</tt>.</p>
				1753	</div> <!-- runtime.objc_copyWeak -->
				1754
				1755	<div id="runtime.objc_destroyWeak">
				1756	<h1><tt>void objc_destroyWeak(id *object);</tt></h1>
				1757	<p><i>Precondition:</i> <tt>object</tt> is a valid pointer which
				1758	either contains a null pointer or has been registered as
				1759	a <tt>__weak</tt> object.</p>
				1760	<p><tt>object</tt> is unregistered as a weak object, if it ever was.
				1761	The current value of <tt>object</tt> is left unspecified; otherwise,
				1762	equivalent to the following code:</p>
				1763	<pre>void objc_destroyWeak(id *object) {
				1764	objc_storeWeak(object, nil);
				1765	}</pre>
				1766	<p>Does not need to be atomic with respect to calls
				1767	to <tt>objc_storeWeak</tt> on <tt>object</tt>.</p>
				1768	</div> <!-- runtime.objc_destroyWeak -->
				1769
				1770	<div id="runtime.objc_initWeak">
				1771	<h1><tt>id objc_initWeak(id *object, id value);</tt></h1>
				1772	<p><i>Precondition:</i> <tt>object</tt> is a valid pointer which has
				1773	not been registered as a <tt>__weak</tt> object. <tt>value</tt> is
				1774	null or a pointer to a valid object.</p>
				1775	<p>If <tt>value</tt> is a null pointer or the object to which it
				1776	points has begun deallocation, <tt>object</tt> is zero-initialized.
				1777	Otherwise, <tt>object</tt> is registered as a <tt>__weak</tt> object
				1778	pointing to <tt>value</tt>. Equivalent to the following code:</p>
				1779	<pre>id objc_initWeak(id *object, id value) {
				1780	*object = nil;
				1781	return objc_storeWeak(object, value);
				1782	}</pre>
				1783	<p>Returns the value of <tt>object</tt> after the call.</p>
				1784	<p>Does not need to be atomic with respect to calls
				1785	to <tt>objc_storeWeak</tt> on <tt>object</tt>.</p>
				1786	</div> <!-- runtime.objc_initWeak -->
				1787
				1788	<div id="runtime.objc_loadWeak">
				1789	<h1><tt>id objc_loadWeak(id *object);</tt></h1>
				1790	<p><i>Precondition:</i> <tt>object</tt> is a valid pointer which
				1791	either contains a null pointer or has been registered as
				1792	a <tt>__weak</tt> object.</p>
				1793	<p>If <tt>object</tt> is registered as a <tt>__weak</tt> object, and
				1794	the last value stored into <tt>object</tt> has not yet been
				1795	deallocated or begun deallocation, retains and autoreleases that value
				1796	and returns it. Otherwise returns null. Equivalent to the following
				1797	code:</p>
				1798	<pre>id objc_loadWeak(id *object) {
				1799	return objc_autorelease(objc_loadWeakRetained(object));
				1800	}</pre>
				1801	<p>Must be atomic with respect to calls to <tt>objc_storeWeak</tt>
				1802	on <tt>object</tt>.</p>
				1803	<div class="rationale">Rationale: loading weak references would be
				1804	inherently prone to race conditions without the retain.</div>
				1805	</div> <!-- runtime.objc_loadWeak -->
				1806
				1807	<div id="runtime.objc_loadWeakRetained">
				1808	<h1><tt>id objc_loadWeakRetained(id *object);</tt></h1>
				1809	<p><i>Precondition:</i> <tt>object</tt> is a valid pointer which
				1810	either contains a null pointer or has been registered as
				1811	a <tt>__weak</tt> object.</p>
				1812	<p>If <tt>object</tt> is registered as a <tt>__weak</tt> object, and
				1813	the last value stored into <tt>object</tt> has not yet been
				1814	deallocated or begun deallocation, retains that value and returns it.
				1815	Otherwise returns null.</p>
				1816	<p>Must be atomic with respect to calls to <tt>objc_storeWeak</tt>
				1817	on <tt>object</tt>.</p>
				1818	</div> <!-- runtime.objc_loadWeakRetained -->
				1819
				1820	<div id="runtime.objc_moveWeak">
				1821	<h1><tt>void objc_moveWeak(id dest, id src);</tt></h1>
				1822	<p><i>Precondition:</i> <tt>src</tt> is a valid pointer which either
				1823	contains a null pointer or has been registered as a <tt>__weak</tt>
				1824	object. <tt>dest</tt> is a valid pointer which has not been
				1825	registered as a <tt>__weak</tt> object.</p>
				1826	<p><tt>dest</tt> is initialized to be equivalent to <tt>src</tt>,
				1827	potentially registering it with the runtime. <tt>src</tt> may then be
				1828	left in its original state, in which case this call is equivalent
				1829	to <a href="#runtime.objc_copyWeak"><tt>objc_copyWeak</tt></a>, or it
				1830	may be left as null.</p>
				1831	<p>Must be atomic with respect to calls to <tt>objc_storeWeak</tt>
				1832	on <tt>src</tt>.</p>
				1833	</div> <!-- runtime.objc_moveWeak -->
				1834
John McCall	085d09d	2011-06-19 10:12:24 +0000	[diff] [blame]	1835	<div id="runtime.objc_release">
				1836	<h1><tt>void objc_release(id value);</tt></h1>
				1837	<p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a
				1838	valid object.</p>
				1839	<p>If <tt>value</tt> is null, this call has no effect. Otherwise, it
				1840	performs a release operation exactly as if the object had been sent
				1841	the <tt>release</tt> message.</p>
				1842	</div> <!-- runtime.objc_release -->
				1843
John McCall	98a48cf	2011-06-19 09:36:02 +0000	[diff] [blame]	1844	<div id="runtime.objc_retain">
				1845	<h1><tt>id objc_retain(id value);</tt></h1>
				1846	<p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a
				1847	valid object.</p>
				1848	<p>If <tt>value</tt> is null, this call has no effect. Otherwise, it
				1849	performs a retain operation exactly as if the object had been sent
				1850	the <tt>retain</tt> message.</p>
				1851	<p>Always returns <tt>value</tt>.</p>
				1852	</div> <!-- runtime.objc_retain -->
				1853
				1854	<div id="runtime.objc_retainAutorelease">
				1855	<h1><tt>id objc_retainAutorelease(id value);</tt></h1>
				1856	<p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a
				1857	valid object.</p>
				1858	<p>If <tt>value</tt> is null, this call has no effect. Otherwise, it
				1859	performs a retain operation followed by an autorelease operation.
				1860	Equivalent to the following code:</p>
				1861	<pre>id objc_retainAutorelease(id value) {
				1862	return objc_autorelease(objc_retain(value));
				1863	}</pre>
				1864	<p>Always returns <tt>value</tt>.</p>
				1865	</div> <!-- runtime.objc_retainAutorelease -->
				1866
				1867	<div id="runtime.objc_retainAutoreleaseReturnValue">
				1868	<h1><tt>id objc_retainAutoreleaseReturnValue(id value);</tt></h1>
				1869	<p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a
				1870	valid object.</p>
				1871	<p>If <tt>value</tt> is null, this call has no effect. Otherwise, it
				1872	performs a retain operation followed by the operation described in
				1873	<a href="#runtime.objc_autoreleaseReturnValue"><tt>objc_autoreleaseReturnValue</tt></a>.
				1874	Equivalent to the following code:</p>
				1875	<pre>id objc_retainAutoreleaseReturnValue(id value) {
				1876	return objc_autoreleaseReturnValue(objc_retain(value));
				1877	}</pre>
				1878	<p>Always returns <tt>value</tt>.</p>
				1879	</div> <!-- runtime.objc_retainAutoreleaseReturnValue -->
				1880
				1881	<div id="runtime.objc_retainAutoreleasedReturnValue">
				1882	<h1><tt>id objc_retainAutoreleasedReturnValue(id value);</tt></h1>
				1883	<p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a
				1884	valid object.</p>
				1885	<p>If <tt>value</tt> is null, this call has no effect. Otherwise, it
				1886	attempts to accept a hand off of a retain count from a call to
				1887	<a href="#runtime.objc_autoreleaseReturnValue"><tt>objc_autoreleaseReturnValue</tt></a>
				1888	on <tt>value</tt> in a recently-called function or something it
				1889	calls. If that fails, it performs a retain operation exactly
				1890	like <a href="#runtime.objc_retain"><tt>objc_retain</tt></a>.</p>
				1891	<p>Always returns <tt>value</tt>.</p>
				1892	</div> <!-- runtime.objc_retainAutoreleasedReturnValue -->
				1893
				1894	<div id="runtime.objc_retainBlock">
				1895	<h1><tt>id objc_retainBlock(id value);</tt></h1>
				1896	<p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a
				1897	valid block object.</p>
				1898	<p>If <tt>value</tt> is null, this call has no effect. Otherwise, if
				1899	the block pointed to by <tt>value</tt> is still on the stack, it is
				1900	copied to the heap and the address of the copy is returned. Otherwise
				1901	a retain operation is performed on the block exactly as if it had been
				1902	sent the <tt>retain</tt> message.</p>
				1903	</div> <!-- runtime.objc_retainBlock -->
				1904
John McCall	98a48cf	2011-06-19 09:36:02 +0000	[diff] [blame]	1905	<div id="runtime.objc_storeStrong">
				1906	<h1><tt>id objc_storeStrong(id *object, id value);</tt></h1>
				1907	<p><i>Precondition:</i> <tt>object</tt> is a valid pointer to
				1908	a <tt>__strong</tt> object which is adequately aligned for a
				1909	pointer. <tt>value</tt> is null or a pointer to a valid object.</p>
				1910	<p>Performs the complete sequence for assigning to a <tt>__strong</tt>
				1911	object of non-block type. Equivalent to the following code:</p>
				1912	<pre>id objc_storeStrong(id *object, id value) {
				1913	value = [value retain];
				1914	id oldValue = *object;
				1915	*object = value;
				1916	[oldValue release];
				1917	return value;
				1918	}</pre>
				1919	<p>Always returns <tt>value</tt>.</p>
				1920	</div> <!-- runtime.objc_storeStrong -->
				1921
				1922	<div id="runtime.objc_storeWeak">
				1923	<h1><tt>id objc_storeWeak(id *object, id value);</tt></h1>
				1924	<p><i>Precondition:</i> <tt>object</tt> is a valid pointer which
				1925	either contains a null pointer or has been registered as
				1926	a <tt>__weak</tt> object. <tt>value</tt> is null or a pointer to a
				1927	valid object.</p>
				1928	<p>If <tt>value</tt> is a null pointer or the object to which it
				1929	points has begun deallocation, <tt>object</tt> is assigned null
				1930	and unregistered as a <tt>__weak</tt> object. Otherwise,
				1931	<tt>object</tt> is registered as a <tt>__weak</tt> object or has its
				1932	registration updated to point to <tt>value</tt>.</p>
				1933	<p>Returns the value of <tt>object</tt> after the call.</p>
				1934	</div> <!-- runtime.objc_storeWeak -->
				1935
				1936	</div> <!-- runtime -->
John McCall	8246702	2011-06-15 21:21:53 +0000	[diff] [blame]	1937	</div> <!-- root -->
				1938	</body>
				1939	</html>