include/am-refcounting.h
changeset 18 9b30f80f6e49
parent 17 563aea5eba06
     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;