Only use skia::RefPtr for refcounting

skia/ext/refptr.h

 // Copyright 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef SKIA_EXT_REFPTR_H_
 #define SKIA_EXT_REFPTR_H_
 
 #include "third_party/skia/include/core/SkRefCnt.h"
 
 namespace skia {
 
 // When creating/receiving a ref-counted pointer from Skia, wrap that pointer in
 // this class to avoid dealing with the ref-counting and prevent leaks/crashes
 // due to ref-counting bugs.
 //
-// Example of Creating an SkShader* and setting it on a SkPaint:
+// Example of creating a new SkShader* and setting it on a SkPaint:
 //   skia::RefPtr<SkShader> shader = skia::AdoptRef(SkGradientShader::Create());
 //   paint.setShader(shader.get());
 //
 // When passing around a ref-counted pointer to methods outside of Skia, always
 // pass around the skia::RefPtr instead of the raw pointer. An example method
 // that takes a SkShader* parameter and saves the SkShader* in the class.
 //   void AMethodThatSavesAShader(const skia::RefPtr<SkShader>& shader) {
 //     member_refptr_ = shader;
 //   }
 //   skia::RefPtr<SkShader> member_refptr_;
 //
-// When returning a ref-counted ponter, also return the skia::RefPtr instead. An
-// example method that creates an SkShader* and returns it:
+// When returning a ref-counted pointer, also return the skia::RefPtr instead.
+// An example method that creates an SkShader* and returns it:
 //   skia::RefPtr<SkShader> MakeAShader() {
 //     return skia::AdoptRef(SkGradientShader::Create());
 //   }
 //
+// If a Skia API returns a raw pointer that already has an owner, then use

[vandebo (ex-Chrome), 2013/05/17 20:47:49]

The object under consideration is reference counted, it does not have a single
owner.  ShareRef does not enable sharing of references, it creates a new
reference.  Suggestion:

To take a scoped reference to an object which does not have a unowned reference
i.e. has all its references owned by other objects, use the "ShareRef" helper.

[enne (OOO), 2013/05/17 21:37:02]

Incorporated most of that wording.

+// the ShareRef helper to have a RefPtr share that ref with the other owner.
+//   skia::RefPtr<SkShader> shader = skia::ShareRef(paint.getShader());
+//
 // Never call ref() or unref() on the underlying ref-counted pointer. If you
 // AdoptRef() the raw pointer immediately into a skia::RefPtr and always work
 // with skia::RefPtr instances instead, the ref-counting will be taken care of
 // for you.
 template<typename T>
 class RefPtr {
  public:
   RefPtr() : ptr_(NULL) {}
 
   RefPtr(const RefPtr& other)
@@ skipping 33 matching lines @@
   T* operator->() const { return ptr_; }
 
   typedef T* RefPtr::*unspecified_bool_type;
   operator unspecified_bool_type() const {
     return ptr_ ? &RefPtr::ptr_ : NULL;
   }
 
  private:
   T* ptr_;
 
+  // This function cannot be public because Skia starts its ref-counted
+  // objects at refcnt=1.  This makes it impossible to differentiate
+  // between a newly created object (that doesn't need to be ref'd) or an
+  // already existing object with one owner (that does to be ref'd so that

[vandebo (ex-Chrome), 2013/05/17 20:47:49]

typo: ...that does *need* to be ref'd...

[enne (OOO), 2013/05/17 21:37:02]

Done.

+  // this RefPtr can also manage its lifetime).
   explicit RefPtr(T* ptr) : ptr_(ptr) {}
 
   template<typename U>
   friend RefPtr<U> AdoptRef(U* ptr);
+
+  template<typename U>
+  friend RefPtr<U> ShareRef(U* ptr);
 };
 
+// For newly created raw pointers without any owners.

[vandebo (ex-Chrome), 2013/05/17 20:47:49]

Technically the object doesn't need to be newly created.  It can be the result
of a function that returns a new reference.  Suggestion: For objects that have
an unowned reference (like newly create objects).

[enne (OOO), 2013/05/17 21:37:02]

Done.

 template<typename T>
 RefPtr<T> AdoptRef(T* ptr) { return RefPtr<T>(ptr); }
 
+// For pointers already owned. Doesn't take ownership of existing references.

[vandebo (ex-Chrome), 2013/05/17 20:47:49]

Suggestion: For objects that do not have unowned references (will ref the
object).

[enne (OOO), 2013/05/17 21:37:02]

Incorporated that wording into this comment.

+template<typename T>
+RefPtr<T> ShareRef(T* ptr) { return RefPtr<T>(SkSafeRef(ptr)); }
+
 }  // namespace skia
 
 #endif  // SKIA_EXT_REFPTR_H_