From 9d2f0e34fe46348f300ae2cdc4047f441739510b Mon Sep 17 00:00:00 2001
From: John McCall <rjmccall@apple.com>
Date: Wed, 29 Aug 2012 08:32:30 +0000
Subject: [PATCH] =?UTF-8?q?Clarify=20the=20point=20at=20which=20ARC=20dest?=
 =?UTF-8?q?roys=20ivars=20vis-=C3=A0-vis=20[super=20dealloc].=20=20rdar://?=
 =?UTF-8?q?problem/11141872?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

llvm-svn: 162833
---
 clang/docs/AutomaticReferenceCounting.html | 30 ++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/clang/docs/AutomaticReferenceCounting.html b/clang/docs/AutomaticReferenceCounting.html
index 2fd82dda65c5..5cacbd5e3d0c 100644
--- a/clang/docs/AutomaticReferenceCounting.html
+++ b/clang/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 -->