Update RefPtr documentation and deprecation
authordarin@apple.com <darin@apple.com@268f45cc-cd09-0410-ab3c-d52691b4dbfc>
Mon, 20 Apr 2015 04:42:39 +0000 (04:42 +0000)
committerdarin@apple.com <darin@apple.com@268f45cc-cd09-0410-ab3c-d52691b4dbfc>
Mon, 20 Apr 2015 04:42:39 +0000 (04:42 +0000)
https://bugs.webkit.org/show_bug.cgi?id=143936

Reviewed by Andreas Kling.

Source/WTF:

* WTF.vcxproj/WTF.vcxproj: Removed PassRef.h
* WTF.vcxproj/WTF.vcxproj.filters: Ditto.
* WTF.xcodeproj/project.pbxproj: Ditto.
* wtf/CMakeLists.txt: Ditto.

Tools:

* Scripts/do-webcore-rename: Put in some DeprecatedPassRefPtr renames.

Websites/webkit.org:

* coding/RefPtr.html: Updated.

git-svn-id: https://svn.webkit.org/repository/webkit/trunk@183001 268f45cc-cd09-0410-ab3c-d52691b4dbfc

Source/WTF/ChangeLog
Source/WTF/WTF.vcxproj/WTF.vcxproj
Source/WTF/WTF.vcxproj/WTF.vcxproj.filters
Source/WTF/WTF.xcodeproj/project.pbxproj
Source/WTF/wtf/CMakeLists.txt
Tools/ChangeLog
Tools/Scripts/do-webcore-rename
Websites/webkit.org/ChangeLog
Websites/webkit.org/coding/RefPtr.html

index 90c1fdf..1851661 100644 (file)
@@ -1,3 +1,15 @@
+2015-04-19  Darin Adler  <darin@apple.com>
+
+        Update RefPtr documentation and deprecation
+        https://bugs.webkit.org/show_bug.cgi?id=143936
+
+        Reviewed by Andreas Kling.
+
+        * WTF.vcxproj/WTF.vcxproj: Removed PassRef.h
+        * WTF.vcxproj/WTF.vcxproj.filters: Ditto.
+        * WTF.xcodeproj/project.pbxproj: Ditto.
+        * wtf/CMakeLists.txt: Ditto.
+
 2015-04-17  Alexey Proskuryakov  <ap@apple.com>
 
         Use ASan poisoning to taint moved-out-of Refs
index bbed7c1..23a81e8 100644 (file)
     <ClInclude Include="..\wtf\ParallelJobsLibdispatch.h" />
     <ClInclude Include="..\wtf\ParallelJobsOpenMP.h" />
     <ClInclude Include="..\wtf\PassOwnPtr.h" />
-    <ClInclude Include="..\wtf\PassRef.h" />
     <ClInclude Include="..\wtf\PassRefPtr.h" />
     <ClInclude Include="..\wtf\Platform.h" />
     <ClInclude Include="..\wtf\PrintStream.h" />
index e97e9ec..d4fec2f 100644 (file)
     <ClInclude Include="..\wtf\PassOwnPtr.h">
       <Filter>wtf</Filter>
     </ClInclude>
-    <ClInclude Include="..\wtf\PassRef.h">
-      <Filter>wtf</Filter>
-    </ClInclude>
     <ClInclude Include="..\wtf\PassRefPtr.h">
       <Filter>wtf</Filter>
     </ClInclude>
index 8942d8a..e405d6d 100644 (file)
@@ -88,7 +88,6 @@
                93934BD318A1E8C300D0D6A1 /* StringViewObjC.mm in Sources */ = {isa = PBXBuildFile; fileRef = 93934BD218A1E8C300D0D6A1 /* StringViewObjC.mm */; };
                93934BD518A1F16900D0D6A1 /* StringViewCF.cpp in Sources */ = {isa = PBXBuildFile; fileRef = 93934BD418A1F16900D0D6A1 /* StringViewCF.cpp */; };
                93AC91A818942FC400244939 /* LChar.h in Headers */ = {isa = PBXBuildFile; fileRef = 93AC91A718942FC400244939 /* LChar.h */; };
-               93B1AA80180E5AF3004A2F05 /* PassRef.h in Headers */ = {isa = PBXBuildFile; fileRef = 93B1AA7F180E5AF3004A2F05 /* PassRef.h */; };
                93F1993E19D7958D00C2390B /* StringView.cpp in Sources */ = {isa = PBXBuildFile; fileRef = 93F1993D19D7958D00C2390B /* StringView.cpp */; };
                974CFC8E16A4F327006D5404 /* WeakPtr.h in Headers */ = {isa = PBXBuildFile; fileRef = 974CFC8D16A4F327006D5404 /* WeakPtr.h */; };
                9BC70F05176C379D00101DEC /* AtomicStringTable.cpp in Sources */ = {isa = PBXBuildFile; fileRef = 9BC70F04176C379D00101DEC /* AtomicStringTable.cpp */; };
                93934BD218A1E8C300D0D6A1 /* StringViewObjC.mm */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.objcpp; name = StringViewObjC.mm; path = mac/StringViewObjC.mm; sourceTree = "<group>"; };
                93934BD418A1F16900D0D6A1 /* StringViewCF.cpp */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; name = StringViewCF.cpp; path = cf/StringViewCF.cpp; sourceTree = "<group>"; };
                93AC91A718942FC400244939 /* LChar.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = LChar.h; sourceTree = "<group>"; };
-               93B1AA7F180E5AF3004A2F05 /* PassRef.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = PassRef.h; sourceTree = "<group>"; };
                93F1993D19D7958D00C2390B /* StringView.cpp */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; path = StringView.cpp; sourceTree = "<group>"; };
                974CFC8D16A4F327006D5404 /* WeakPtr.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = WeakPtr.h; sourceTree = "<group>"; };
                9BC70F04176C379D00101DEC /* AtomicStringTable.cpp */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; path = AtomicStringTable.cpp; sourceTree = "<group>"; };
                                A8A472E6151A825B004123FF /* ParallelJobs.h */,
                                A8A472E9151A825B004123FF /* ParallelJobsLibdispatch.h */,
                                A8A472EC151A825B004123FF /* PassOwnPtr.h */,
-                               93B1AA7F180E5AF3004A2F05 /* PassRef.h */,
                                A8A472ED151A825B004123FF /* PassRefPtr.h */,
                                A876DBD7151816E500DADB95 /* Platform.h */,
                                0F9D335D165DBA73005AD387 /* PrintStream.cpp */,
                                A8A473E3151A825B004123FF /* Locker.h in Headers */,
                                A8A473E6151A825B004123FF /* MainThread.h in Headers */,
                                A8A473E8151A825B004123FF /* MathExtras.h in Headers */,
-                               93B1AA80180E5AF3004A2F05 /* PassRef.h in Headers */,
                                A8A473EA151A825B004123FF /* MD5.h in Headers */,
                                7CBBA07419BB7FDC00BBF025 /* OSObjectPtr.h in Headers */,
                                CD5497AD15857D0300B5BC30 /* MediaTime.h in Headers */,
index 8b7011c..c7b4285 100644 (file)
@@ -65,7 +65,6 @@ set(WTF_HEADERS
     ParallelJobsLibdispatch.h
     ParallelJobsOpenMP.h
     PassOwnPtr.h
-    PassRef.h
     PassRefPtr.h
     Platform.h
     PrintStream.h
index 1fd5017..88f7c23 100644 (file)
@@ -1,3 +1,12 @@
+2015-04-19  Darin Adler  <darin@apple.com>
+
+        Update RefPtr documentation and deprecation
+        https://bugs.webkit.org/show_bug.cgi?id=143936
+
+        Reviewed by Andreas Kling.
+
+        * Scripts/do-webcore-rename: Put in some DeprecatedPassRefPtr renames.
+
 2015-04-19  Yusuke Suzuki  <utatane.tea@gmail.com>
 
         Introduce bytecode intrinsics
index 1b50e68..0999432 100755 (executable)
@@ -102,6 +102,10 @@ my %renames = (
 );
 
 my %renamesContemplatedForTheFuture = (
+    "PassRefPtr" => "DeprecatedPassRefPtr",
+    "OwnPtr" => "DeprecatedOwnPtr",
+    "PassOwnPtr" => "DeprecatedPassOwnPtr",
+
     "HTMLPlugInImageElement" => "HTMLEmbeddedObjectElement",
     "isPlugInImageElement" => "isEmbeddedObjectElement",
     "isHTMLPlugInImageElement" => "isHTMLEmbeddedObjectElement",
index 033a7f7..605b285 100644 (file)
@@ -1,3 +1,12 @@
+2015-04-19  Darin Adler  <darin@apple.com>
+
+        Update RefPtr documentation and deprecation
+        https://bugs.webkit.org/show_bug.cgi?id=143936
+
+        Reviewed by Andreas Kling.
+
+        * coding/RefPtr.html: Updated.
+
 2015-03-10  Joseph Pecoraro  <pecoraro@apple.com>
 
         Fix warning about loading insecure content from secure webkit.org/blog
index b87bcd2..700e593 100644 (file)
@@ -1,5 +1,5 @@
-<?php 
-    $title="RefPtr and PassRefPtr Basics";
+<?php
+    $title="RefPtr Basics";
     include("../header.inc"); 
 ?>
 
     }
 </style>
 
-<h1><span class="class">RefPtr</span> and <span class="class">PassRefPtr</span> Basics</h1>
+<h1><span class="class">RefPtr</span> Basics</h1>
 <div>Darin Adler</div>
-<div>Version 4, 2010-08-27</div>
+<div>Version 5, 2015-04-19</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 function is called
+<p>Many objects in WebKit are reference counted. The pattern is that classes have
+member functions named <span class="function">ref</span> and <span class="function">deref</span>
+that increment and decrement a reference count. When the <span class="function">deref</span> 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 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
+<span class="function">deref</span> calls.
+We decided to use smart pointers to mitigate the problem. Early experiments showed that
 smart pointers led to additional manipulation of reference counts that hurt performance.
-For example, for a function that took a smart pointer as a parameter and returned that same smart
-pointer as a return value, just passing the parameter and returning the value would increment
+For example, for a function that took a smart pointer as an argument and returned that same smart
+pointer as a return value, passing the parameter and returning the value would increment
 and then decrement the reference count two to four times
-as the object moved from one smart pointer to another. So we looked for an
-idiom that would let us use smart pointers and avoid this reference count churn.</p>
+as the object moved from one smart pointer to another.</p>
 
-<p>The inspiration for a solution came from the C++ standard class template <span class="class">auto_ptr</span>.
-These objects implement a model where assignment is transfer of ownership. When you assign
-from one <span class="class">auto_ptr</span> to another, the donor becomes 0.</p>
+<p>We solved that problem in 2005 with a set of smart pointer class templates. C++ move semantics,
+introduced in C++11, made it possible to streamline those class templates without
+reintroducing reference count churn.</p>
 
-<p>Maciej Stachowiak devised a pair of class templates, <span class="class">RefPtr</span>
-and <span class="class">PassRefPtr</span>, that implement this scheme
-for WebCore’s intrusive reference counting.</p>
+<p>Later, in 2013, we noticed that our use of pointers in general, and smart pointers in particular,
+was causing a proliferation of null checks and uncertainty about what can be null.
+We started using references rather than pointers wherever possible in WebKit code.</p>
+
+<p>Maciej Stachowiak created the class template, <span class="class">RefPtr</span>,
+that implements WebKit’s intrusive reference counting, and we have since adapted it so that it
+works well with move semantics. Andreas Kling created a related class template,
+<span class="class">Ref</span>, which works with RefPtr and provides clarity and
+even greater efficiency when dealing with
+reference counted objects in contexts where there is no need for a null pointer.</p>
 
 <h2>Raw pointers</h2>
 
@@ -60,12 +63,7 @@ Here’s the canonical setter function, written with raw pointers:</p>
 
 class Document {
     <span class="comment">...</span>
-    Title* m_title;
-}
-
-Document::Document()
-    : m_title(0)
-{
+    Title* m_title { nullptr };
 }
 
 Document::~Document()
@@ -85,7 +83,7 @@ void Document::setTitle(Title* title)
 
 <h2><span class="class">RefPtr</span></h2>
 
-<p><span class="class">RefPtr</span> is a simple smart pointer class that calls <span class="function">ref</span>
+<p><span class="class">RefPtr</span> is a smart pointer class template that calls <span class="function">ref</span>
 on incoming values and
 <span class="function">deref</span> on outgoing values.
 <span class="class">RefPtr</span> works on any object with both a <span class="function">ref</span> and
@@ -93,7 +91,7 @@ a <span class="function">deref</span> member function.
 Here’s the setter function example, written with <span class="class">RefPtr</span>:</p>
 
 <pre class="code"><span class="comment">// example, not preferred style</span>
+
 class Document {
     <span class="comment">...</span>
     RefPtr&lt;Title&gt; m_title;
@@ -104,208 +102,166 @@ void Document::setTitle(Title* title)
     m_title = title;
 }</pre>
 
-<p>Use of <span class="class">RefPtr</span> alone can lead to reference count churn.</p>
+<p>Functions that take take ownership of reference counted arguments can lead to reference count churn.</p>
 
-<pre class="code"><span class="comment">// example, not preferred style; should use RefCounted and adoptRef (see below)</span>
+<pre class="code"><span class="comment">// example, not preferred style
  
-RefPtr&lt;Node&gt; createSpecialNode()
-{
-    RefPtr&lt;Node&gt; a = new Node;
-    a-&gt;setSpecial(true);
-    return a;
-}
-
-RefPtr&lt;Node&gt; b = createSpecialNode();</pre>
-
-<p>For purposes of this discussion, lets assume that the node object starts with a
-reference count of 0 (more on this later). When it’s assigned to <span class="variable">a</span>,
-the reference count is incremented to 1. The reference count is incremented to 2 to
-create the return value, then decremented back to 1 when <span class="variable">a</span> is destroyed.
-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>
+RefPtr&lt;Title&gt; untitledTitle = titleFactory().createUniqueUntitledTitle();
 
-<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>
+document.setTitle(untitledTitle);</pre>
 
-<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>
+<p>The title starts with a reference count of 1. The <span class="function">setTitle</span> function stores it in the data member,
+and the reference count is incremented to 2. Then the local variable <span class="variable">untitledTitle</span> goes out of
+scope and the reference count is decremented back to 1.</p>
 
-<h2><span class="class">PassRefPtr</span></h2>
+<p>The way to define a function that takes ownership of an object is to use an rvalue reference.</p>
 
-<p><span class="class">PassRefPtr</span> is like <span class="class">RefPtr</span> with a difference.
-When you copy a <span class="class">PassRefPtr</span> or
-assign the value of a <span class="class">PassRefPtr</span> to a <span class="class">RefPtr</span> or
-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; should use RefCounted and adoptRef (see below)</span>
+<pre class="code"><span class="comment">// preferred style</span>
+class Document {
+    <span class="comment">...</span>
+    RefPtr&lt;Title&gt; m_title;
+}
 
-PassRefPtr&lt;Node&gt; createSpecialNode()
+void Document::setTitle(RefPtr&lt;Title&gt;&amp;&amp; title)
 {
-    PassRefPtr&lt;Node&gt; a = new Node;
-    a-&gt;setSpecial(true);
-    return a;
+    m_title = WTF::move(title);
 }
 
-RefPtr&lt;Node&gt; b = createSpecialNode();</pre>
-
-<p>The node object starts with a reference count of 0. When it’s assigned to <span class="variable">a</span>,
-the reference count is incremented to 1. Then <span class="variable">a</span> gets set to 0 when the return
-value <span class="class">PassRefPtr</span> is created. Then the return value is set to 0 when
-<span class="variable">b</span> is created.</p>
-
-<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>
+<span class="comment">...</span>
 
-<pre class="code"><span class="comment">// warning, will dereference a null pointer and will not work</span>
-static RefPtr&lt;Ring&gt; g_oneRingToRuleThemAll;
+RefPtr&lt;Title&gt; untitledTitle = titleFactory().createUniqueUntitledTitle();
 
-void finish(PassRefPtr&lt;Ring&gt; ring)
-{
-    g_oneRingToRuleThemAll = ring;
-    <span class="comment">...</span>
-    ring-&gt;wear();
-}</pre>
+document.setTitle(WTF::move(untitledTitle));</pre>
 
-<p>By the time <span class="function">wear</span> is called, <span class="variable">ring</span>
-is already 0. To avoid this, we recommend <span class="class">PassRefPtr</span> only for
-function argument and result types, copying arguments into <span class="class">RefPtr</span>
-local variables.</p>
+<p>The title makes it all the way into the data member with a reference count of 1;
+it’s never incremented or decremented.</p>
 
-<pre class="code">static RefPtr&lt;Ring&gt; g_oneRingToRuleThemAll;
+<p>Note the use of <span class="function">WTF::move</span>
+instead of <span class="function">std::move</span>.
+The WTF version adds a couple of compile time checks to catch common errors, and should be
+used throughout the WebKit project in place of <span class="function">std::move</span>.</p>
 
-void finish(PassRefPtr&lt;Ring&gt; prpRing)
-{
-    RefPtr&lt;Ring&gt; ring = prpRing;
-    g_oneRingToRuleThemAll = ring;
-    <span class="comment">...</span>
-    ring-&gt;wear();
-}</pre>
+<h2><span class="class">Ref</span></h2>
 
-<h2>Mixing <span class="class">RefPtr</span> and <span class="class">PassRefPtr</span></h2>
+<p><span class="class">Ref</span> is like <span class="class">RefPtr</span>, except that it
+acts like a reference rather than a pointer; it doesn’t have a null value.</p>
 
-<p>Since we recommend use of <span class="class">RefPtr</span> in all cases except when passing arguments to or
-returning values from a function, there will be times when you have a <span class="class">RefPtr</span>
-and wish to transfer ownership as <span class="class">PassRefPtr</span> does.
-<span class="class">RefPtr</span> has a member function named
-<span class="function">release</span> that does the trick. It sets the value of the original
-<span class="class">RefPtr</span> to 0 and constructs a <span class="class">PassRefPtr</span>, without
-changing reference counts.</p>
+<p><span class="class">Ref</span> works particularly well with return values; it’s often
+straightforward to be sure that a newly created object will never be null.</p>
 
-<pre class="code"><span class="comment">// example, not preferred style; should use RefCounted and adoptRef (see below)</span>
+<pre class="code"><span class="comment">// preferred style</span>
  
-PassRefPtr&lt;Node&gt; createSpecialNode()
+Ref&lt;Title&gt; TitleFactory::createUniqueUntitledTitle()
 {
-    RefPtr&lt;Node&gt; a = new Node;
-    a-&gt;setCreated(true);
-    return a.release();
-}
-
-RefPtr&lt;Node&gt; b = createSpecialNode();</pre>
+    return createTitle("untitled " + m_nextAvailableUntitledNumber++);
+}</pre>
 
-<p>This keeps the efficiency of <span class="class">PassRefPtr</span> while reducing the chance
-that its relatively tricky semantics will cause problems.</p>
+<p>Using <span class="class">Ref</span> helps makes it clear to the caller that this function will never return null.</p>
 
 <h2>Mixing with raw pointers</h2>
 
+<p>The <span class="class">RefPtr</span> class mixes with raw pointers much as the smart
+pointers in the C++ standard library, such as <span class="class">std::unique_ptr</span>, do.</p>
+
 <p>When using a <span class="class">RefPtr</span> to call a function that takes a raw pointer,
 use the <span class="function">get</span> function.</p>
 
 <pre class="code">printNode(stderr, a.get());</pre>
 
-<p>However, many operations can be done on a <span class="class">RefPtr</span>
-or <span class="class">PassRefPtr</span> directly, without resorting to an explicit <span class="function">get</span> call.</p>
+<p>With a <span class="class">Ref</span>, the <span class="function">get</span> function
+produces a raw reference, and the <span class="function">ptr</span> function produces a raw pointer.</p>
 
-<pre class="code">RefPtr&lt;Node&gt; a = createSpecialNode();
-Node* b = getOrdinaryNode();
+<pre class="code">printString(stderr, a.get().caption());
+printNode(stderr, a.ptr());</pre>
+
+<p>Many operations can be done on a <span class="class">RefPtr</span>
+directly, without resorting to an explicit <span class="function">get</span> call.</p>
+
+<pre class="code">Ref&lt;Node&gt; a = createSpecialNode();
+RefPtr&lt;Node&gt; b = findNode();
+Node* c = getOrdinaryNode();
 
 <span class="comment">// the * operator</span>
-*a = value;
+*b = value;
 
 <span class="comment">// the -&gt; operator</span>
 a-&gt;clear();
+b-&gt;clear();
 
 <span class="comment">// null check in an if statement</span>
-if (a)
+if (b)
     log("not empty");
 
 <span class="comment">// the ! operator</span>
-if (!a)
+if (!b)
     log("empty");
 
 <span class="comment">// the == and != operators, mixing with raw pointers</span>
-if (a == b)
+if (b == c)
     log("equal");
-if (a != b)
+if (b != c)
     log("not equal");
 
 <span class="comment">// some type casts</span>
-RefPtr&lt;DerivedNode&gt; d = static_pointer_cast&lt;DerivedNode&gt;(a);</pre>
+RefPtr&lt;DerivedNode&gt; d = static_pointer_cast&lt;DerivedNode&gt;(d);</pre>
 
-<p>Normally, <span class="class">RefPtr</span> and <span class="class">PassRefPtr</span>
-enforce a simple rule; they always balance <span class="function">ref</span> and
+<p>Normally, <span class="class">RefPtr</span> enforces a simple rule; it always
+balances <span class="function">ref</span> and
 <span class="function">deref</span> calls, guaranteeing a programmer can’t miss a
-<span class="function">deref</span>. But in the case where we have a raw pointer,
+<span class="function">deref</span>. But in the case where we start with a raw pointer,
 already have a reference count, and want to transfer ownership the
 <span class="function">adoptRef</span> function should be used.</p>
 
 <pre class="code"><span class="comment">// warning, requires a pointer that already has a ref</span>
 RefPtr&lt;Node&gt; 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
+<p>In the rare case where we have a need to transfer from a <span class="class">RefPtr</span>
+to a raw pointer without changing the reference count, use the
 <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&lt;Node&gt; node = createSpecialNode();
-Node* rawNodePointer = node.release().leakRef();</pre>
-
-<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">leakRef</span>.</p>
+Node* rawNodePointer = node.leakRef();</pre>
 
 <h2>RefPtr and new objects</h2>
 
-<p>In the examples in this discussion, we talked about objects with a reference
-count of 0. However, for efficiency and simplicity, the <span class="class">RefCounted</span> class doesn't
-use a reference count of 0 at all. Objects are created with a reference count
+<p>New objects of classes that make use of the <span class="class">RefCounted</span> class template
+are created with a reference count
 of 1. The best programming idiom to use is to put such objects right into a
-<span class="class">RefPtr</span> to make it impossible to forget to deref the object when done with
+<span class="class">Ref</span> to make it impossible to forget to deref the object when done with
 it. This means that anyone calling new on such an object should immediately
-call adoptRef. In WebCore we use functions named create instead of direct calls
-to new.</p>
+call adoptRef. In WebKit we use functions named create instead of direct calls
+to new for these classes.</p>
 
 <pre class="code"><span class="comment">// preferred style</span>
  
-PassRefPtr&lt;Node&gt; Node::create()
+Ref&lt;Node&gt; Node::create()
 {
-    return adoptRef(new Node);
+    return adoptRef(*new Node);
 }
 
-RefPtr&lt;Node&gt; e = Node::create();</pre>
+Ref&lt;Node&gt; e = Node::create();</pre>
 
-<p>Because of the way <span class="function">adoptRef</span> and
-<span class="class">PassRefPtr</span> are implemented, this is an efficient idiom.
-The object starts with a reference count of 1 and no manipulation of the reference
-count happens at all.</p>
+<p>Because of the way <span class="function">adoptRef</span> is implemented,
+this is an efficient idiom.
+The object starts with a reference count of 1 and no code is generated to
+examine or modify the reference count.</p>
 
 <pre class="code"><span class="comment">// preferred style</span>
  
-PassRefPtr&lt;Node&gt; createSpecialNode()
+Ref&lt;Node&gt; createSpecialNode()
 {
-    RefPtr&lt;Node&gt; a = Node::create();
+    Ref&lt;Node&gt; a = Node::create();
     a-&gt;setCreated(true);
-    return a.release();
+    return a;
 }
 
-RefPtr&lt;Node&gt; b = createSpecialNode();</pre>
+Ref&lt;Node&gt; b = createSpecialNode();</pre>
 
-<p>The node object is put into a <span class="class">PassRefPtr</span> by a call
+<p>The node object is put into a <span class="class">Ref</span> by a call
 to <span class="function">adoptRef</span> inside <span class="function">Node::create</span>,
-then passes into <span class="variable">a</span> and is released and passes into
+then passes into <span class="variable">a</span> and is passed 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
@@ -315,54 +271,67 @@ or <span class="function">deref</span> without first calling <span class="functi
 <h2>Guidelines</h2>
 
 <p>We’ve developed these guidelines for use of <span class="class">RefPtr</span>
-and <span class="class">PassRefPtr</span> in WebKit code.</p>
+and <span class="class">Ref</span> in WebKit code.</p>
 
 <h3>Local variables</h3>
 <ul>
-<li>If ownership and lifetime are guaranteed, a local variable can be a raw pointer.</li>
+<li>If ownership and lifetime are guaranteed, a local variable can be a raw reference or pointer.</li>
 <li>If the code needs to hold ownership or guarantee lifetime, a local variable should
-be a <span class="class">RefPtr</span>.</li>
-<li>Local variables should never be <span class="class">PassRefPtr</span>.</li>
+be a <span class="class">Ref</span>, or if it can be null, a <span class="class">RefPtr</span>.</li>
 </ul>
 
 <h3>Data members</h3>
 <ul>
-<li>If ownership and lifetime are guaranteed, a data member can be a raw pointer.</li>
+<li>If ownership and lifetime are guaranteed, a data member can be a raw reference or pointer.</li>
 <li>If the class needs to hold ownership or guarantee lifetime, the data member should
-be a <span class="class">RefPtr</span>.</li>
-<li>Data members should never be <span class="class">PassRefPtr</span>.</li>
+be a <span class="class">Ref</span> or <span class="class">RefPtr</span>.</li>
 </ul>
 
 <h3>Function arguments</h3>
 <ul>
-<li>If a function does not take ownership of an object, the argument should be a raw pointer.</li>
-<li>If a function does take ownership of an object, the argument should be a <span class="class">PassRefPtr</span>.
-This includes most setter functions.
-Unless the use of the argument is very simple, the argument should be transferred to a
-<span class="class">RefPtr</span> at the start of the function; the argument can be named with
-a “prp” prefix in such cases.</li>
+<li>If a function does not take ownership of an object, the argument should be a raw reference or raw pointer.</li>
+<li>If a function does take ownership of an object, the argument should be a <span class="class">Ref&amp;&amp;</span>
+or a <span class="class">RefPtr&amp;&amp;</span>. This includes many setter functions.
 </ul>
 
 <h3>Function results</h3>
 <ul>
 <li>If a function’s result is an object, but ownership is not being transferred, the result
-should be a raw pointer. This includes most getter functions.</li>
+should be a raw reference or raw pointer. This includes most getter functions.</li>
 <li>If a function’s result is a new object or ownership is being transferred for any other
-reason, the result should be a <span class="class">PassRefPtr</span>.
-Since local variables are typically <span class="class">RefPtr</span>, it’s common to call
-<span class="function">release</span> in the return statement to transfer the
-<span class="class">RefPtr</span> to the <span class="class">PassRefPtr</span>.</li>
+reason, the result should be a <span class="class">Ref</span> or <span class="class">RefPtr</span>.</li>
 </ul>
 
 <h3>New objects</h3>
 <ul>
-<li>New objects should be put into a <span class="class">RefPtr</span> as soon as possible
+<li>New objects should be put into a <span class="class">Ref</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>
+returns a <span class="class">Ref</span>.</li>
+</ul>
+
+<h2>Pitfalls</h2>
+
+<h3>PassRefPtr</h3>
+<p>Programmers who worked on WebKit before C++11 are familiar with a class template called PassRefPtr
+(soon to be renamed to DeprecatedPassRefPtr) and you will see it in older WebKit code.</p>
+<ul>
+<li>Any function result or local variable of type PassRefPtr should be replaced with one of type RefPtr or Ref.</li>
+<li>Any argument of type PassRefPtr should be replaced with one of type RefPtr&amp;&amp; or Ref&amp;&amp;.</li>
+<li>Code calling RefPtr::release to turn a RefPtr into a PassRefPtr should instead call WTF::move.</li>
+</ul>
+
+<h3>Common mistakes</h3>
+<ul>
+<li>Giving a function argument a type of Ref, RefPtr, Ref&amp;&amp;, or RefPtr&amp;&amp;
+when it should instead be a raw reference or raw pointer. A function that sometimes takes ownership
+can work just fine with a raw reference or raw pointer. The rvalue reference form is appropriate
+when passing ownership is the primary way the function is used and the is case that needs to be optimized.
+Not all setters need to take an rvalue reference.</li>
+<li>Forgetting to call WTF::move can result in unnecessary reference count churn.</li>
 </ul>
 
 <h2>Improving this document</h2>
@@ -372,30 +341,31 @@ 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>copyRef</li>
+<li>releaseNonNull</li>
+
+<li>How this works when these are stored in collections such as vectors and hash maps.</li>
+
+<li>Better explanation of when WTF::move is needed and not needed.</li>
 
-<li>Perils of programming with <span class="class">TreeShared</span>.</li>
+<li>The “protector” idiom, where a local <span class="class">Ref</span> variable is used to keep an object alive.</li>
+
+<li>Perils of programming with <span class="class">TreeShared</span>.
+(Or after we merge <span class="class">TreeShared</span> into <span class="class">Node</span>,
+the perils of programming with <span class="class">Node</span>).</li>
 
 <li>Our desire to eliminate <span class="class">TreeShared</span> and instead have
-<span class="variable">m_firstChild</span> and <span class="variable">m_next</span> be
-<span class="class">ListRefPtr</span> or the equivalent.</li>
+nodes hold a reference to their first child and next sibling.</li>
 
 <li>How we we mix reference counting with garbage collection to implement the DOM
 and the JavaScript and Objective-C DOM bindings.</li>
 
-<li>Comparison of our intrusive reference counting with other schemes such as the
-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="function">adoptPtr</span>.</li>
-
-<li>The <span class="class">OwnArrayPtr</span> class template,
-and <span class="class">PassOwnArrayPtr</span>.</li>
+<li>Comparison of WebKit intrusive reference counting with other schemes such as the
+external reference counting in <span class="class">std::shared_ptr</class>.</li>
 
-<li>The <span class="class">RetainPtr</span> class template,
-and the lack of a <span class="class">PassRetainPtr</span>.</li>
+<li>Guidelines for use of <span class="class">std::unique_ptr</span> and <span class="class">std::make_unique</span>.</li>
 
-<li>The <span class="class">ListRefPtr</span> class template.</li>
+<li>The <span class="class">RetainPtr</span> class template.</li>
 
 </ul>