Home | History | Annotate | Download | only in ppapi
      1 // Copyright 2013 The Chromium Authors. All rights reserved.
      2 // Use of this source code is governed by a BSD-style license that can be
      3 // found in the LICENSE file.
      4 //
      5 // This is a copy of base/linked_ptr.h with CHECKS/DCHECKS replaced with
      6 // PP_DCHECKs.
      7 //
      8 // A "smart" pointer type with reference tracking.  Every pointer to a
      9 // particular object is kept on a circular linked list.  When the last pointer
     10 // to an object is destroyed or reassigned, the object is deleted.
     11 //
     12 // Used properly, this deletes the object when the last reference goes away.
     13 // There are several caveats:
     14 // - Like all reference counting schemes, cycles lead to leaks.
     15 // - Each smart pointer is actually two pointers (8 bytes instead of 4).
     16 // - Every time a pointer is released, the entire list of pointers to that
     17 //   object is traversed.  This class is therefore NOT SUITABLE when there
     18 //   will often be more than two or three pointers to a particular object.
     19 // - References are only tracked as long as linked_ptr<> objects are copied.
     20 //   If a linked_ptr<> is converted to a raw pointer and back, BAD THINGS
     21 //   will happen (double deletion).
     22 //
     23 // A good use of this class is storing object references in STL containers.
     24 // You can safely put linked_ptr<> in a vector<>.
     25 // Other uses may not be as good.
     26 //
     27 // Note: If you use an incomplete type with linked_ptr<>, the class
     28 // *containing* linked_ptr<> must have a constructor and destructor (even
     29 // if they do nothing!).
     30 //
     31 // Thread Safety:
     32 //   A linked_ptr is NOT thread safe. Copying a linked_ptr object is
     33 //   effectively a read-write operation.
     34 //
     35 // Alternative: to linked_ptr is shared_ptr, which
     36 //  - is also two pointers in size (8 bytes for 32 bit addresses)
     37 //  - is thread safe for copying and deletion
     38 //  - supports weak_ptrs
     39 
     40 #ifndef MEDIA_CDM_PPAPI_LINKED_PTR_H_
     41 #define MEDIA_CDM_PPAPI_LINKED_PTR_H_
     42 
     43 #include "ppapi/cpp/logging.h"
     44 
     45 // This is used internally by all instances of linked_ptr<>.  It needs to be
     46 // a non-template class because different types of linked_ptr<> can refer to
     47 // the same object (linked_ptr<Superclass>(obj) vs linked_ptr<Subclass>(obj)).
     48 // So, it needs to be possible for different types of linked_ptr to participate
     49 // in the same circular linked list, so we need a single class type here.
     50 //
     51 // DO NOT USE THIS CLASS DIRECTLY YOURSELF.  Use linked_ptr<T>.
     52 class linked_ptr_internal {
     53  public:
     54   // Create a new circle that includes only this instance.
     55   void join_new() {
     56     next_ = this;
     57   }
     58 
     59   // Join an existing circle.
     60   void join(linked_ptr_internal const* ptr) {
     61     next_ = ptr->next_;
     62     ptr->next_ = this;
     63   }
     64 
     65   // Leave whatever circle we're part of.  Returns true iff we were the
     66   // last member of the circle.  Once this is done, you can join() another.
     67   bool depart() {
     68     if (next_ == this) return true;
     69     linked_ptr_internal const* p = next_;
     70     while (p->next_ != this) p = p->next_;
     71     p->next_ = next_;
     72     return false;
     73   }
     74 
     75  private:
     76   mutable linked_ptr_internal const* next_;
     77 };
     78 
     79 template <typename T>
     80 class linked_ptr {
     81  public:
     82   typedef T element_type;
     83 
     84   // Take over ownership of a raw pointer.  This should happen as soon as
     85   // possible after the object is created.
     86   explicit linked_ptr(T* ptr = NULL) { capture(ptr); }
     87   ~linked_ptr() { depart(); }
     88 
     89   // Copy an existing linked_ptr<>, adding ourselves to the list of references.
     90   template <typename U> linked_ptr(linked_ptr<U> const& ptr) { copy(&ptr); }
     91 
     92   linked_ptr(linked_ptr const& ptr) {
     93     PP_DCHECK(&ptr != this);
     94     copy(&ptr);
     95   }
     96 
     97   // Assignment releases the old value and acquires the new.
     98   template <typename U> linked_ptr& operator=(linked_ptr<U> const& ptr) {
     99     depart();
    100     copy(&ptr);
    101     return *this;
    102   }
    103 
    104   linked_ptr& operator=(linked_ptr const& ptr) {
    105     if (&ptr != this) {
    106       depart();
    107       copy(&ptr);
    108     }
    109     return *this;
    110   }
    111 
    112   // Smart pointer members.
    113   void reset(T* ptr = NULL) {
    114     depart();
    115     capture(ptr);
    116   }
    117   T* get() const { return value_; }
    118   operator T*() const { return value_; }
    119   T* operator->() const { return value_; }
    120   T& operator*() const { return *value_; }
    121   // Release ownership of the pointed object and returns it.
    122   // Sole ownership by this linked_ptr object is required.
    123   T* release() {
    124     bool last = link_.depart();
    125     PP_DCHECK(last);
    126     (void)last;
    127     T* v = value_;
    128     value_ = NULL;
    129     return v;
    130   }
    131 
    132   bool operator==(const T* p) const { return value_ == p; }
    133   bool operator!=(const T* p) const { return value_ != p; }
    134   template <typename U>
    135   bool operator==(linked_ptr<U> const& ptr) const {
    136     return value_ == ptr.get();
    137   }
    138   template <typename U>
    139   bool operator!=(linked_ptr<U> const& ptr) const {
    140     return value_ != ptr.get();
    141   }
    142 
    143  private:
    144   template <typename U>
    145   friend class linked_ptr;
    146 
    147   T* value_;
    148   linked_ptr_internal link_;
    149 
    150   void depart() {
    151     if (link_.depart()) delete value_;
    152   }
    153 
    154   void capture(T* ptr) {
    155     value_ = ptr;
    156     link_.join_new();
    157   }
    158 
    159   template <typename U> void copy(linked_ptr<U> const* ptr) {
    160     value_ = ptr->get();
    161     if (value_)
    162       link_.join(&ptr->link_);
    163     else
    164       link_.join_new();
    165   }
    166 };
    167 
    168 template<typename T> inline
    169 bool operator==(T* ptr, const linked_ptr<T>& x) {
    170   return ptr == x.get();
    171 }
    172 
    173 template<typename T> inline
    174 bool operator!=(T* ptr, const linked_ptr<T>& x) {
    175   return ptr != x.get();
    176 }
    177 
    178 // A function to convert T* into linked_ptr<T>
    179 // Doing e.g. make_linked_ptr(new FooBarBaz<type>(arg)) is a shorter notation
    180 // for linked_ptr<FooBarBaz<type> >(new FooBarBaz<type>(arg))
    181 template <typename T>
    182 linked_ptr<T> make_linked_ptr(T* ptr) {
    183   return linked_ptr<T>(ptr);
    184 }
    185 
    186 #endif  // MEDIA_CDM_PPAPI_LINKED_PTR_H_
    187