Clarify the point at which ARC destroys ivars vis-à-vis

[super dealloc].  rdar://problem/11141872

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

diff --git a/docs/AutomaticReferenceCounting.html b/docs/AutomaticReferenceCounting.html
index 2fd82dda65c577c68b60119627059cbaa378a9de..5cacbd5e3d0c407c1d165db08d7fd3cc96e4b629 100644 (file)
--- a/docs/AutomaticReferenceCounting.html
+++ b/docs/AutomaticReferenceCounting.html
@@ -1611,6 +1611,36 @@ implementation must be very careful to do all the other work
 that <tt>NSObject</tt>'s <tt>dealloc</tt> would, which is outside the
 scope of this document to describe.</p></div>
 
+<p>The instance variables for an ARC-compiled class will be destroyed
+at some point after control enters the <tt>dealloc</tt> method for the
+root class of the class.  The ordering of the destruction of instance
+variables is unspecified, both within a single class and between
+subclasses and superclasses.</p>
+
+<div class="rationale"><p>Rationale: the traditional, non-ARC pattern
+for destroying instance variables is to destroy them immediately
+before calling <tt>[super&nbsp;dealloc]</tt>.  Unfortunately, message
+sends from the superclass are quite capable of reaching methods in the
+subclass, and those methods may well read or write to those instance
+variables.  Making such message sends from dealloc is generally
+discouraged, since the subclass may well rely on other invariants that
+were broken during <tt>dealloc</tt>, but it's not so inescapably
+dangerous that we felt comfortable calling it undefined behavior.
+Therefore we chose to delay destroying the instance variables to a
+point at which message sends are clearly disallowed: the point at
+which the root class's deallocation routines take over.</p>
+
+<p>In most code, the difference is not observable.  It can, however,
+be observed if an instance variable holds a strong reference to an
+object whose deallocation will trigger a side-effect which must be
+carefully ordered with respect to the destruction of the super class.
+Such code violates the design principle that semantically important
+behavior should be explicit.  A simple fix is to clear the instance
+variable manually during <tt>dealloc</tt>; a more holistic solution is
+to move semantically important side-effects out of
+<tt>dealloc</tt> and into a separate teardown phase which can rely on
+working with well-formed objects.</p></div>
+
 </div>
 
 </div> <!-- misc.special_methods -->