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

blob: ab7debf20c1b3956752a9c0d330ec8d2c71cd5ed [file] [log] [blame]

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