From: John McCall <rjmccall@apple.com>
Date: Sun, 19 Jun 2011 09:59:33 +0000 (+0000)
Subject: Improve the intro to the runtime-functions section.
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=3914a306e495358a3334a242de7d1781a62e3ba9;p=clang

Improve the intro to the runtime-functions section.



git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@133386 91177308-0d34-0410-b5e6-96231b3b80d8
---

diff --git a/docs/AutomaticReferenceCounting.html b/docs/AutomaticReferenceCounting.html
index 6b0e1bb9ba..cbc509f44a 100644
--- a/docs/AutomaticReferenceCounting.html
+++ b/docs/AutomaticReferenceCounting.html
@@ -1502,12 +1502,35 @@ an object, except that <tt>__weak</tt> objects must always be
 appropriately aligned for an object of type <tt>id</tt>.</p>
 
 <p>The runtime tracks <tt>__weak</tt> objects which holds non-null
-values.  It is undefined behavior to modify a <tt>__weak</tt> object
-which is being tracked by the runtime except through an
-<a href="#runtime.objc_storeWeak"><tt>objc_storeWeak</tt></a> or
-<a href="#runtime.objc_destroyWeak"><tt>objc_destroyWeak</tt></a>
+values.  It is undefined behavior to direct modify a <tt>__weak</tt>
+object which is being tracked by the runtime except through an
+<a href="#runtime.objc_storeWeak"><tt>objc_storeWeak</tt></a>,
+<a href="#runtime.objc_destroyWeak"><tt>objc_destroyWeak</tt></a>,
+or <a href="#runtime.objc_moveWeak"><tt>objc_moveWeak</tt></a>
 call.</p>
 
+<p>The runtime must provide a number of new entrypoints which the
+compiler may emit, which are described in the remainder of this
+section.</p>
+
+<div class="rationale"><p>Rationale: Several of these functions are
+semantically equivalent to a message send; we emit calls to C
+functions instead because:</p>
+<ul>
+<li>the machine code to do so is significantly smaller,</li>
+<li>it is much easier to recognize the C functions in the ARC optimizer, and</li>
+<li>a sufficient sophisticated runtime may be able to avoid the
+message send in common cases.</li>
+</ul>
+
+<p>Several other of these functions are <q>fused</q> operations which
+can be described entirely in terms of other operations.  We use the
+fused operations primarily as a code-size optimization, although in
+some cases there is also a real potential for avoiding redundant
+operations in the runtime.</p>
+
+</div>
+
 <div id="runtime.objc_autorelease">
 <h1><tt>id objc_autorelease(id value);</tt></h1>
 <p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a