[SCM] WebKit Debian packaging branch, debian/experimental, updated. upstream/1.3.3-9427-gc2be6fc
darin at apple.com
darin at apple.com
Wed Dec 22 12:42:40 UTC 2010
The following commit has been merged in the debian/experimental branch:
commit f137ecc5de8c3bd69de072e3a7503a17440585a2
Author: darin at apple.com <darin at apple.com@268f45cc-cd09-0410-ab3c-d52691b4dbfc>
Date: Fri Aug 27 17:34:44 2010 +0000
* coding/RefPtr.html: Minor revision, improve clarity and mention some
recent developments.
git-svn-id: http://svn.webkit.org/repository/webkit/trunk@66233 268f45cc-cd09-0410-ab3c-d52691b4dbfc
diff --git a/WebKitSite/ChangeLog b/WebKitSite/ChangeLog
index b193d6e..34c4c02 100644
--- a/WebKitSite/ChangeLog
+++ b/WebKitSite/ChangeLog
@@ -1,3 +1,8 @@
+2010-08-27 Darin Adler <darin at apple.com>
+
+ * coding/RefPtr.html: Minor revision, improve clarity and mention some
+ recent developments.
+
2010-08-26 Daniel Bates <dbates at rim.com>
Reviewed by Dumitru Daniliuc.
diff --git a/WebKitSite/coding/RefPtr.html b/WebKitSite/coding/RefPtr.html
index 10906b4..b87bcd2 100644
--- a/WebKitSite/coding/RefPtr.html
+++ b/WebKitSite/coding/RefPtr.html
@@ -18,26 +18,20 @@
<h1><span class="class">RefPtr</span> and <span class="class">PassRefPtr</span> Basics</h1>
<div>Darin Adler</div>
-<div>Version 3, 2009-10-16</div>
+<div>Version 4, 2010-08-27</div>
<h2>History</h2>
<p>Many objects in WebKit are reference counted. The pattern used is that classes have
member functions <span class="function">ref</span> and <span class="function">deref</span>
that increment and decrement the reference count. Each call to <span class="function">ref</span>
-has to be matched by a call to <span class="function">deref</span>. When the reference count hits 0,
-the object is deleted. Some of these classes create new objects with a reference count of 0; this
-is referred to as the floating state. An object in floating state must have <span class="function">ref</span> and then
-<span class="function">deref</span> called on it before it will be deleted.</p>
-
-<p>Many classes in WebKit implement this pattern by deriving from the
-<span class="class">RefCounted</span> class template.</p>
+has to be matched by a call to <span class="function">deref</span>. When the function is called
+on an object with a reference count of 1, the object is deleted. Many classes in WebKit implement
+this pattern by deriving from the <span class="class">RefCounted</span> class template.</p>
<p>Back in 2005, we discovered that there were many memory leaks, especially in HTML
-editing code, caused either by mismatches of <span class="function">ref</span> and
-<span class="function">deref</span> calls or by objects that were created with
-<span class="function">new</span> that never got a <span class="function">ref</span>
-call at all and remained in the floating state.</p>
+editing code, caused by misuse of <span class="function">ref</span> and
+<span class="function">deref</span> calls.</p>
<p>We wanted
to use smart pointers to mitigate the problem. However, some early experiments showed that
@@ -65,7 +59,7 @@ Here’s the canonical setter function, written with raw pointers:</p>
<pre class="code"><span class="comment">// example, not preferred style</span>
class Document {
- <span class="comment">[...]</span>
+ <span class="comment">...</span>
Title* m_title;
}
@@ -101,7 +95,7 @@ Here’s the setter function example, written with <span class="class">RefPtr</s
<pre class="code"><span class="comment">// example, not preferred style</span>
class Document {
- <span class="comment">[...]</span>
+ <span class="comment">...</span>
RefPtr<Title> m_title;
}
@@ -112,7 +106,7 @@ void Document::setTitle(Title* title)
<p>Use of <span class="class">RefPtr</span> alone can lead to reference count churn.</p>
-<pre class="code"><span class="comment">// example, not preferred style</span>
+<pre class="code"><span class="comment">// example, not preferred style; should use RefCounted and adoptRef (see below)</span>
RefPtr<Node> createSpecialNode()
{
@@ -130,9 +124,9 @@ create the return value, then decremented back to 1 when <span class="variable">
Then the reference count is incremented to 2 to create <span class="variable">b</span>, and then decremented back
to 1 when the return value of <span class="function">createSpecialNode</span> is destroyed.</p>
-<p>(This analysis ignores the possibility that the compiler might implement the
-<a href="http://en.wikipedia.org/wiki/Return_value_optimization">return value optimization</a>.
-If the compiler does, some of the reference count churn may be mitigated.)</p>
+<p>(If the compiler implements the
+<a href="http://en.wikipedia.org/wiki/Return_value_optimization">return value optimization</a>,
+there may be one less increment and decrement of the reference count.)</p>
<p>The overhead of reference count churn is even greater when both function arguments and return
values are involved. The solution is <span class="class">PassRefPtr</span>.</p>
@@ -146,7 +140,7 @@ another <span class="class">PassRefPtr</span>, the original
pointer value is set to 0; the operation is done without any change to the reference count.
Let’s take a look at a new version of our example:</p>
-<pre class="code"><span class="comment">// example, not preferred style</span>
+<pre class="code"><span class="comment">// example, not preferred style; should use RefCounted and adoptRef (see below)</span>
PassRefPtr<Node> createSpecialNode()
{
@@ -165,7 +159,7 @@ value <span class="class">PassRefPtr</span> is created. Then the return value is
<p>However, as the Safari team learned when we started programming with <span class="class">PassRefPtr</span>,
the rule that a pointer becomes 0 when it’s assigned to another variable can easily lead to mistakes.</p>
-<pre class="code"><span class="comment">// example, not preferred style</span>
+<pre class="code"><span class="comment">// warning, will dereference a null pointer and will not work</span>
static RefPtr<Ring> g_oneRingToRuleThemAll;
@@ -201,7 +195,7 @@ and wish to transfer ownership as <span class="class">PassRefPtr</span> does.
<span class="class">RefPtr</span> to 0 and constructs a <span class="class">PassRefPtr</span>, without
changing reference counts.</p>
-<pre class="code"><span class="comment">// example, assuming new Node starts with reference count 0</span>
+<pre class="code"><span class="comment">// example, not preferred style; should use RefCounted and adoptRef (see below)</span>
PassRefPtr<Node> createSpecialNode()
{
@@ -263,20 +257,15 @@ RefPtr<Node> node = adoptRef(rawNodePointer);</pre>
<p>To transfer from a <span class="class">RefPtr</span> to a raw pointer without
changing the reference count, <span class="class">PassRefPtr</span> provides the
-<span class="function">releaseRef</span> function.</p>
+<span class="function">leakRef</span> function.</p>
<pre class="code"><span class="comment">// warning, results in a pointer that must get an explicit deref</span>
RefPtr<Node> node = createSpecialNode();
-Node* rawNodePointer = node.release().releaseRef();</pre>
+Node* rawNodePointer = node.release().leakRef();</pre>
-<p>Since <span class="function">releaseRef</span> is rarely used, it’s provided only in the
+<p>Since <span class="function">leakRef</span> is rarely used, it’s provided only in the
<span class="class">PassRefPtr</span> class, hence the need to call <span class="function">release</span>,
-then <span class="function">releaseRef</span>. If we find this is used often we could
-provide <span class="function">releaseRef</span> for <span class="class">RefPtr</span> too.
-Also, we are considering changing the name of <span class="function">releaseRef</span>
-to <span class="function">leakRef</span> to make it harder to confuse with
-<span class="function">release</span>, and to allude to the a risk of a storage leak
-if the function is used incorrectly.</p>
+then <span class="function">leakRef</span>.</p>
<h2>RefPtr and new objects</h2>
@@ -319,6 +308,10 @@ to <span class="function">adoptRef</span> inside <span class="function">Node::cr
then passes into <span class="variable">a</span> and is released and passes into
<span class="variable">b</span>, all without touching the reference count.</p>
+<p>The <span class="class">RefCounted</span> class implements a runtime check
+so we get an assertion failure if we create an object and call <span class="function">ref</span>
+or <span class="function">deref</span> without first calling <span class="function">adoptRef</span>.</p>
+
<h2>Guidelines</h2>
<p>We’ve developed these guidelines for use of <span class="class">RefPtr</span>
@@ -365,6 +358,8 @@ Since local variables are typically <span class="class">RefPtr</span>, it’s co
<ul>
<li>New objects should be put into a <span class="class">RefPtr</span> as soon as possible
after creation to allow the smart pointers to do all reference counting automatically.</li>
+<li>For <span class="class">RefCounted</span> objects, the above should be done with the
+<span class="function">adoptRef</span> function.</li>
<li>Best idiom is to use a private constructor and a public
<span class="function">create</span> function that
returns a <span class="class">PassRefPtr</span>.</li>
@@ -372,18 +367,13 @@ returns a <span class="class">PassRefPtr</span>.</li>
<h2>Improving this document</h2>
-<p>There may be frequently asked questions are not covered by this document.
-If so, we would like to add discussion of those.</p>
-
-<p>One or more of the following topics could also be covered by this document.</p>
+<p>We should add answers to any frequently asked questions are not covered by this document.
+One or more of the following topics could also be covered by this document.</p>
<ul>
<li>The “protector” idiom, where a local RefPtr variable is used to keep an object alive.</li>
-<li>Perils of programming with “floating objects”. A thing of the
-past for <span class="class">RefCounted</span> but still used in some other cases.</li>
-
<li>Perils of programming with <span class="class">TreeShared</span>.</li>
<li>Our desire to eliminate <span class="class">TreeShared</span> and instead have
@@ -397,10 +387,10 @@ and the JavaScript and Objective-C DOM bindings.</li>
external reference counting in Boost <span class="class">shared_ptr</class>.</li>
<li>The <span class="class">OwnPtr</span> class template, and how it can be used
-with <span class="class">PassOwnPtr</span> and <span class="class">auto_ptr</span>.</li>
+with <span class="class">PassOwnPtr</span> and <span class="function">adoptPtr</span>.</li>
<li>The <span class="class">OwnArrayPtr</span> class template,
-and the lack of a <span class="class">PassOwnArrayPtr</span>.</li>
+and <span class="class">PassOwnArrayPtr</span>.</li>
<li>The <span class="class">RetainPtr</span> class template,
and the lack of a <span class="class">PassRetainPtr</span>.</li>
--
WebKit Debian packaging
More information about the Pkg-webkit-commits
mailing list