Eliminate Newborn/NoAddRef (bug 5907, r=ds). default tip
authorDavid Anderson <dvander@alliedmods.net>
Fri Sep 06 13:54:31 2013 -0700 (2013-09-06)
changeset 189b30f80f6e49
parent 17 563aea5eba06
Eliminate Newborn/NoAddRef (bug 5907, r=ds).
README.md
include/am-refcounting-threadsafe.h
include/am-refcounting.h
tests/test-refcounting.cpp
     1.1 --- a/README.md	Sat Aug 31 19:52:41 2013 -0700
     1.2 +++ b/README.md	Fri Sep 06 13:54:31 2013 -0700
     1.3 @@ -96,16 +96,17 @@
     1.4  
     1.5      class MyObject : public Refcounted<MyObject>
     1.6    
     1.7 -The object is instantiated with a reference count of 1. A few RAII objects are provided for
     1.8 -automatically retaining and releasing references:
     1.9 +The object is instantiated with a reference count of 0, meaning it is illegal to call Release()
    1.10 +without first calling AddRef.
    1.11 +
    1.12 +A few RAII objects are provided for automatically retaining and releasing references:
    1.13  
    1.14  * Ref<T>. Adds one reference upon construction and releases one reference on destruction.
    1.15  * PassRef<T>. Same as Ref<T>, except, when passed into a Ref<T> or into a PassRef<T>, the contained
    1.16    reference is NULL'd, rather than performing an unnecessary extra AddRef()+Release(). PassRef<T>
    1.17    is intended only for return values.
    1.18 -* Newborn<T>. If a newly allocated Refcounted object is stored into a Ref<T>, it will have one
    1.19 -  extra reference. When allocating new refcounted objects, they should be immediately wrapped in a
    1.20 -  Newborn<T> to prevent this.
    1.21 +* AdoptRef(T). If an object is returned with an implicit AddRef, not using Ref or PassRef, then
    1.22 +  it is necessary to AdoptRef() when assigning into a Ref or PassRef.
    1.23  
    1.24  RefcountedThreadsafe provides the same accessors as Refcounted. However, the reference counting is
    1.25  performed using atomic operations, so that two threads racing do not accidentally result in a wrong
     2.1 --- a/include/am-refcounting-threadsafe.h	Sat Aug 31 19:52:41 2013 -0700
     2.2 +++ b/include/am-refcounting-threadsafe.h	Fri Sep 06 13:54:31 2013 -0700
     2.3 @@ -35,12 +35,15 @@
     2.4  
     2.5  namespace ke {
     2.6  
     2.7 +// See the comment above Refcounted<T> for more information. This class is
     2.8 +// identical, except changing the reference count is guaranteed to be atomic
     2.9 +// with respect to other threads changing the reference count.
    2.10  template <typename T>
    2.11  class RefcountedThreadsafe
    2.12  {
    2.13    public:
    2.14      RefcountedThreadsafe()
    2.15 -     : refcount_(1)
    2.16 +     : refcount_(0)
    2.17      {
    2.18      }
    2.19  
     3.1 --- a/include/am-refcounting.h	Sat Aug 31 19:52:41 2013 -0700
     3.2 +++ b/include/am-refcounting.h	Fri Sep 06 13:54:31 2013 -0700
     3.3 @@ -37,18 +37,28 @@
     3.4  
     3.5  template <typename T> class Ref;
     3.6  
     3.7 -// Holds a refcounted T without addrefing it. This is similar to PassRef<>
     3.8 -// below, but is intended only for freshly allocated objects which start
     3.9 -// with reference count 1, and we don't want to add an extra ref just by
    3.10 -// assigning to PassRef<> or Ref<>.
    3.11 +// Objects in AMTL inheriting from Refcounted will have an initial refcount
    3.12 +// of 0. However, in some systems (such as COM), the initial refcount is 1,
    3.13 +// or functions may return raw pointers that have been AddRef'd. In these
    3.14 +// cases it would be a mistake to use Ref<> or PassRef<>, since the object
    3.15 +// would leak an extra reference.
    3.16 +//
    3.17 +// This container holds a refcounted object without addrefing it. This is
    3.18 +// intended only for interacting with functions which return an object that
    3.19 +// has been manually AddRef'd. Note that this will perform a Release(), so
    3.20 +// so it is necessary to assign it to retain the object.
    3.21  template <typename T>
    3.22 -class Newborn
    3.23 +class AlreadyRefed
    3.24  {
    3.25    public:
    3.26 -    Newborn(T *t)
    3.27 +    AlreadyRefed(T *t)
    3.28        : thing_(t)
    3.29      {
    3.30      }
    3.31 +    ~AlreadyRefed() {
    3.32 +        if (thing_)
    3.33 +            thing_->Release();
    3.34 +    }
    3.35  
    3.36      T *release() const {
    3.37          return ReturnAndVoid(thing_);
    3.38 @@ -59,10 +69,10 @@
    3.39  };
    3.40  
    3.41  template <typename T>
    3.42 -static inline Newborn<T>
    3.43 -NoAddRef(T *t)
    3.44 +static inline AlreadyRefed<T>
    3.45 +AdoptRef(T *t)
    3.46  {
    3.47 -    return Newborn<T>(t);
    3.48 +    return AlreadyRefed<T>(t);
    3.49  }
    3.50  
    3.51  // When returning a value, we'd rather not be needlessly changing the refcount,
    3.52 @@ -81,7 +91,14 @@
    3.53      {
    3.54      }
    3.55  
    3.56 -    PassRef(const Newborn<T *> &other)
    3.57 +    PassRef(const AlreadyRefed<T *> &other)
    3.58 +      : thing_(other.release())
    3.59 +    {
    3.60 +        // Don't addref, newborn means already addref'd.
    3.61 +    }
    3.62 +
    3.63 +    template <typename S>
    3.64 +    PassRef(const AlreadyRefed<S *> &other)
    3.65        : thing_(other.release())
    3.66      {
    3.67          // Don't addref, newborn means already addref'd.
    3.68 @@ -134,7 +151,7 @@
    3.69    private:
    3.70      // Disallowed operators.
    3.71      PassRef &operator =(T *other);
    3.72 -    PassRef &operator =(Newborn<T> &other);
    3.73 +    PassRef &operator =(AlreadyRefed<T> &other);
    3.74  
    3.75      void AddRef() {
    3.76          if (thing_)
    3.77 @@ -149,13 +166,18 @@
    3.78      mutable T *thing_;
    3.79  };
    3.80  
    3.81 -// Classes which are refcounted should inherit from this.
    3.82 +// Classes which are refcounted should inherit from this. Note that reference
    3.83 +// counts start at 0 in AMTL, rather than 1. This avoids the complexity of
    3.84 +// having to adopt the initial ref upon allocation. However, this also means
    3.85 +// invoking Release() on a newly allocated object is illegal. Newborn objects
    3.86 +// must either be assigned to a Ref or PassRef (NOT an AdoptRef/AlreadyRefed),
    3.87 +// or must be deleted using |delete|.
    3.88  template <typename T>
    3.89  class Refcounted
    3.90  {
    3.91    public:
    3.92      Refcounted()
    3.93 -      : refcount_(1)
    3.94 +      : refcount_(0)
    3.95      {
    3.96      }
    3.97  
    3.98 @@ -217,7 +239,12 @@
    3.99        : thing_(other.release())
   3.100      {
   3.101      }
   3.102 -    Ref(const Newborn<T> &other)
   3.103 +    Ref(const AlreadyRefed<T> &other)
   3.104 +      : thing_(other.release())
   3.105 +    {
   3.106 +    }
   3.107 +    template <typename S>
   3.108 +    Ref(const AlreadyRefed<S> &other)
   3.109        : thing_(other.release())
   3.110      {
   3.111      }
   3.112 @@ -255,7 +282,7 @@
   3.113      }
   3.114  
   3.115      template <typename S>
   3.116 -    Ref &operator =(const Newborn<S> &other) {
   3.117 +    Ref &operator =(const AlreadyRefed<S> &other) {
   3.118          Release();
   3.119          thing_ = other.release();
   3.120          return *this;
     4.1 --- a/tests/test-refcounting.cpp	Sat Aug 31 19:52:41 2013 -0700
     4.2 +++ b/tests/test-refcounting.cpp	Fri Sep 06 13:54:31 2013 -0700
     4.3 @@ -43,6 +43,10 @@
     4.4    }
     4.5  };
     4.6  
     4.7 +class SubCounted : public Counted
     4.8 +{
     4.9 +};
    4.10 +
    4.11  static inline PassRef<Counted>
    4.12  PassThrough(const Ref<Counted> &obj)
    4.13  {
    4.14 @@ -60,22 +64,44 @@
    4.15    bool Run() KE_OVERRIDE
    4.16    {
    4.17      {
    4.18 -      Ref<Counted> obj(Newborn<Counted>(new Counted()));
    4.19 +      Ref<Counted> obj(new Counted());
    4.20      }
    4.21      if (!check(sDtors == 1, "Ref/Newborn counted properly"))
    4.22        return false;
    4.23 +    {
    4.24 +      PassRef<Counted> obj(new Counted());
    4.25 +    }
    4.26 +    if (!check(sDtors == 2, "Ref/Newborn counted properly"))
    4.27 +      return false;
    4.28 +    {
    4.29 +      Counted *counted = new Counted();
    4.30 +      counted->AddRef();
    4.31 +      Ref<Counted> obj(AdoptRef(counted));
    4.32 +    }
    4.33 +    if (!check(sDtors == 3, "Ref/Newborn counted properly"))
    4.34 +      return false;
    4.35 +
    4.36 +    // Check that subclass assignment works.
    4.37 +    {
    4.38 +      Ref<Counted> obj(new SubCounted());
    4.39 +      Ref<Counted> obj2(PassThrough(new SubCounted()));
    4.40 +    }
    4.41 +    if (!check(sDtors == 5, "Ref/Newborn counted properly"))
    4.42 +      return false;
    4.43 +
    4.44 +    sDtors = 0;
    4.45  
    4.46      {
    4.47 -      Ref<Counted> obj(Newborn<Counted>(new Counted()));
    4.48 +      Ref<Counted> obj(new Counted());
    4.49        Ref<Counted> obj2 = PassThrough(obj);
    4.50        Ref<Counted> obj3 = PassThrough(obj);
    4.51 -      if (!check(sDtors == 1, "destructor not called early"))
    4.52 +      if (!check(sDtors == 0, "destructor not called early"))
    4.53          return false;
    4.54        Ref<Counted> obj4 = PassThrough(PassThrough(PassThrough(obj)));
    4.55 -      if (!check(sDtors == 1, "destructor not called early"))
    4.56 +      if (!check(sDtors == 0, "destructor not called early"))
    4.57          return false;
    4.58      }
    4.59 -    if (!check(sDtors == 2, "PassRef/Ref counted properly"))
    4.60 +    if (!check(sDtors == 1, "PassRef/Ref counted properly"))
    4.61        return false;
    4.62  
    4.63      return true;