1.1 --- a/include/am-refcounting.h Sat Aug 31 19:52:41 2013 -0700
1.2 +++ b/include/am-refcounting.h Fri Sep 06 13:54:31 2013 -0700
1.3 @@ -37,18 +37,28 @@
1.4
1.5 template <typename T> class Ref;
1.6
1.7 -// Holds a refcounted T without addrefing it. This is similar to PassRef<>
1.8 -// below, but is intended only for freshly allocated objects which start
1.9 -// with reference count 1, and we don't want to add an extra ref just by
1.10 -// assigning to PassRef<> or Ref<>.
1.11 +// Objects in AMTL inheriting from Refcounted will have an initial refcount
1.12 +// of 0. However, in some systems (such as COM), the initial refcount is 1,
1.13 +// or functions may return raw pointers that have been AddRef'd. In these
1.14 +// cases it would be a mistake to use Ref<> or PassRef<>, since the object
1.15 +// would leak an extra reference.
1.16 +//
1.17 +// This container holds a refcounted object without addrefing it. This is
1.18 +// intended only for interacting with functions which return an object that
1.19 +// has been manually AddRef'd. Note that this will perform a Release(), so
1.20 +// so it is necessary to assign it to retain the object.
1.21 template <typename T>
1.22 -class Newborn
1.23 +class AlreadyRefed
1.24 {
1.25 public:
1.26 - Newborn(T *t)
1.27 + AlreadyRefed(T *t)
1.28 : thing_(t)
1.29 {
1.30 }
1.31 + ~AlreadyRefed() {
1.32 + if (thing_)
1.33 + thing_->Release();
1.34 + }
1.35
1.36 T *release() const {
1.37 return ReturnAndVoid(thing_);
1.38 @@ -59,10 +69,10 @@
1.39 };
1.40
1.41 template <typename T>
1.42 -static inline Newborn<T>
1.43 -NoAddRef(T *t)
1.44 +static inline AlreadyRefed<T>
1.45 +AdoptRef(T *t)
1.46 {
1.47 - return Newborn<T>(t);
1.48 + return AlreadyRefed<T>(t);
1.49 }
1.50
1.51 // When returning a value, we'd rather not be needlessly changing the refcount,
1.52 @@ -81,7 +91,14 @@
1.53 {
1.54 }
1.55
1.56 - PassRef(const Newborn<T *> &other)
1.57 + PassRef(const AlreadyRefed<T *> &other)
1.58 + : thing_(other.release())
1.59 + {
1.60 + // Don't addref, newborn means already addref'd.
1.61 + }
1.62 +
1.63 + template <typename S>
1.64 + PassRef(const AlreadyRefed<S *> &other)
1.65 : thing_(other.release())
1.66 {
1.67 // Don't addref, newborn means already addref'd.
1.68 @@ -134,7 +151,7 @@
1.69 private:
1.70 // Disallowed operators.
1.71 PassRef &operator =(T *other);
1.72 - PassRef &operator =(Newborn<T> &other);
1.73 + PassRef &operator =(AlreadyRefed<T> &other);
1.74
1.75 void AddRef() {
1.76 if (thing_)
1.77 @@ -149,13 +166,18 @@
1.78 mutable T *thing_;
1.79 };
1.80
1.81 -// Classes which are refcounted should inherit from this.
1.82 +// Classes which are refcounted should inherit from this. Note that reference
1.83 +// counts start at 0 in AMTL, rather than 1. This avoids the complexity of
1.84 +// having to adopt the initial ref upon allocation. However, this also means
1.85 +// invoking Release() on a newly allocated object is illegal. Newborn objects
1.86 +// must either be assigned to a Ref or PassRef (NOT an AdoptRef/AlreadyRefed),
1.87 +// or must be deleted using |delete|.
1.88 template <typename T>
1.89 class Refcounted
1.90 {
1.91 public:
1.92 Refcounted()
1.93 - : refcount_(1)
1.94 + : refcount_(0)
1.95 {
1.96 }
1.97
1.98 @@ -217,7 +239,12 @@
1.99 : thing_(other.release())
1.100 {
1.101 }
1.102 - Ref(const Newborn<T> &other)
1.103 + Ref(const AlreadyRefed<T> &other)
1.104 + : thing_(other.release())
1.105 + {
1.106 + }
1.107 + template <typename S>
1.108 + Ref(const AlreadyRefed<S> &other)
1.109 : thing_(other.release())
1.110 {
1.111 }
1.112 @@ -255,7 +282,7 @@
1.113 }
1.114
1.115 template <typename S>
1.116 - Ref &operator =(const Newborn<S> &other) {
1.117 + Ref &operator =(const AlreadyRefed<S> &other) {
1.118 Release();
1.119 thing_ = other.release();
1.120 return *this;