src/third_party/WebKit/Source/platform/Supplementable.h

   1 /*
   2  * Copyright (C) 2012 Google, Inc. All Rights Reserved.
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions
   6  * are met:
   7  * 1. Redistributions of source code must retain the above copyright
   8  *    notice, this list of conditions and the following disclaimer.
   9  * 2. Redistributions in binary form must reproduce the above copyright
  10  *    notice, this list of conditions and the following disclaimer in the
  11  *    documentation and/or other materials provided with the distribution.
  12  *
  13  * THIS SOFTWARE IS PROVIDED BY APPLE INC. ``AS IS'' AND ANY
  14  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  16  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL APPLE INC. OR
  17  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  18  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  19  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  20  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
  21  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  22  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  23  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  24  */
  25
  26 #ifndef Supplementable_h
  27 #define Supplementable_h
  28
  29 #include "platform/heap/Handle.h"
  30 #include "wtf/Assertions.h"
  31 #include "wtf/HashMap.h"
  32 #include "wtf/OwnPtr.h"
  33 #include "wtf/PassOwnPtr.h"
  34
  35 #if ENABLE(ASSERT)
  36 #include "wtf/Threading.h"
  37 #endif
  38
  39 namespace blink {
  40
  41 // What you should know about Supplementable and Supplement
  42 // ========================================================
  43 // Supplementable and Supplement instances are meant to be thread local. They
  44 // should only be accessed from within the thread that created them. The
  45 // 2 classes are not designed for safe access from another thread. Violating
  46 // this design assumption can result in memory corruption and unpredictable
  47 // behavior.
  48 //
  49 // What you should know about the Supplement keys
  50 // ==============================================
  51 // The Supplement is expected to use the same const char* string instance
  52 // as its key. The Supplementable's SupplementMap will use the address of the
  53 // string as the key and not the characters themselves. Hence, 2 strings with
  54 // the same characters will be treated as 2 different keys.
  55 //
  56 // In practice, it is recommended that Supplements implements a static method
  57 // for returning its key to use. For example:
  58 //
  59 //     class MyClass : public Supplement<MySupplementable> {
  60 //         ...
  61 //         static const char* supplementName();
  62 //     }
  63 //
  64 //     const char* MyClass::supplementName()
  65 //     {
  66 //         return "MyClass";
  67 //     }
  68 //
  69 // An example of the using the key:
  70 //
  71 //     MyClass* MyClass::from(MySupplementable* host)
  72 //     {
  73 //         return reinterpret_cast<MyClass*>(Supplement<MySupplementable>::from(host, supplementName()));
  74 //     }
  75 //
  76 // What you should know about thread checks
  77 // ========================================
  78 // When assertion is enabled this class performs thread-safety check so that
  79 // provideTo and from happen on the same thread. If you want to provide
  80 // some value for Workers this thread check may not work very well though,
  81 // since in most case you'd provide the value while worker preparation is
  82 // being done on the main thread, even before the worker thread is started.
  83 // If that's the case you can explicitly call reattachThread() when the
  84 // Supplementable object is passed to the final destination thread (i.e.
  85 // worker thread). Please be extremely careful to use the method though,
  86 // as randomly calling the method could easily cause racy condition.
  87 //
  88 // Note that reattachThread() does nothing if assertion is not enabled.
  89 //
  90
  91 template<typename T, bool isGarbageCollected>
  92 class SupplementBase;
  93
  94 template<typename T, bool isGarbageCollected>
  95 class SupplementableBase;
  96
  97 template<typename T, bool isGarbageCollected>
  98 struct SupplementableTraits;
  99
 100 template<typename T>
 101 struct SupplementableTraits<T, true> {
 102     typedef RawPtr<SupplementBase<T, true> > SupplementArgumentType;
 103     typedef HeapHashMap<const char*, Member<SupplementBase<T, true> >, PtrHash<const char*> > SupplementMap;
 104 };
 105
 106 template<typename T>
 107 struct SupplementableTraits<T, false> {
 108     typedef PassOwnPtr<SupplementBase<T, false> > SupplementArgumentType;
 109     typedef HashMap<const char*, OwnPtr<SupplementBase<T, false> >, PtrHash<const char*> > SupplementMap;
 110 };
 111
 112 template<bool>
 113 class SupplementTracing;
 114
 115 template<>
 116 class SupplementTracing<true> : public GarbageCollectedMixin { };
 117
 118 template<>
 119 class SupplementTracing<false> {
 120 public:
 121     virtual ~SupplementTracing() { }
 122     virtual void trace(Visitor*) { }
 123 };
 124
 125 template<typename T, bool isGarbageCollected = false>
 126 class SupplementBase : public SupplementTracing<isGarbageCollected> {
 127 public:
 128 #if ENABLE(SECURITY_ASSERT)
 129     virtual bool isRefCountedWrapper() const { return false; }
 130 #endif
 131
 132     static void provideTo(SupplementableBase<T, isGarbageCollected>& host, const char* key, typename SupplementableTraits<T, isGarbageCollected>::SupplementArgumentType supplement)
 133     {
 134         host.provideSupplement(key, supplement);
 135     }
 136
 137     static SupplementBase<T, isGarbageCollected>* from(SupplementableBase<T, isGarbageCollected>& host, const char* key)
 138     {
 139         return host.requireSupplement(key);
 140     }
 141
 142     static SupplementBase<T, isGarbageCollected>* from(SupplementableBase<T, isGarbageCollected>* host, const char* key)
 143     {
 144         return host ? host->requireSupplement(key) : 0;
 145     }
 146
 147     virtual void willBeDestroyed() { }
 148
 149     // FIXME: Oilpan: Remove this callback once PersistentHeapSupplementable is removed again.
 150     virtual void persistentHostHasBeenDestroyed() { }
 151 };
 152
 153 // Helper class for implementing Supplementable, HeapSupplementable, and
 154 // PersistentHeapSupplementable.
 155 template<typename T, bool isGarbageCollected = false>
 156 class SupplementableBase {
 157 public:
 158     void provideSupplement(const char* key, typename SupplementableTraits<T, isGarbageCollected>::SupplementArgumentType supplement)
 159     {
 160         ASSERT(m_threadId == currentThread());
 161         ASSERT(!this->m_supplements.get(key));
 162         this->m_supplements.set(key, supplement);
 163     }
 164
 165     void removeSupplement(const char* key)
 166     {
 167         ASSERT(m_threadId == currentThread());
 168         this->m_supplements.remove(key);
 169     }
 170
 171     SupplementBase<T, isGarbageCollected>* requireSupplement(const char* key)
 172     {
 173         ASSERT(m_threadId == currentThread());
 174         return this->m_supplements.get(key);
 175     }
 176
 177     void reattachThread()
 178     {
 179 #if ENABLE(ASSERT)
 180         m_threadId = currentThread();
 181 #endif
 182     }
 183
 184     // We have a trace method in the SupplementableBase class to ensure we have
 185     // the vtable at the first word of the object. However we don't trace the
 186     // m_supplements here, but in the partially specialized template subclasses
 187     // since we only want to trace it for garbage collected classes.
 188     virtual void trace(Visitor*) { }
 189
 190     void willBeDestroyed()
 191     {
 192         typedef typename SupplementableTraits<T, isGarbageCollected>::SupplementMap::iterator SupplementIterator;
 193         for (SupplementIterator it = m_supplements.begin(); it != m_supplements.end(); ++it)
 194             it->value->willBeDestroyed();
 195     }
 196
 197     // FIXME: Oilpan: Make private and remove this ignore once PersistentHeapSupplementable is removed again.
 198 protected:
 199     GC_PLUGIN_IGNORE("")
 200     typename SupplementableTraits<T, isGarbageCollected>::SupplementMap m_supplements;
 201
 202 #if ENABLE(ASSERT)
 203 protected:
 204     SupplementableBase() : m_threadId(currentThread()) { }
 205
 206 private:
 207     ThreadIdentifier m_threadId;
 208 #endif
 209 };
 210
 211 // This class is used to make an on-heap class supplementable. Its supplements
 212 // must be HeapSupplement.
 213 template<typename T>
 214 class HeapSupplement : public SupplementBase<T, true> { };
 215
 216 // FIXME: Oilpan: Move GarbageCollectedMixin to SupplementableBase<T, true> once PersistentHeapSupplementable is removed again.
 217 template<typename T>
 218 class GC_PLUGIN_IGNORE("http://crbug.com/395036") HeapSupplementable : public SupplementableBase<T, true>, public GarbageCollectedMixin {
 219 public:
 220     virtual void trace(Visitor* visitor) OVERRIDE
 221     {
 222         visitor->trace(this->m_supplements);
 223         SupplementableBase<T, true>::trace(visitor);
 224     }
 225 };
 226
 227 // This class is used to make an off-heap class supplementable with supplements
 228 // that are on-heap, aka. HeapSupplements.
 229 template<typename T>
 230 class GC_PLUGIN_IGNORE("http://crbug.com/395036") PersistentHeapSupplementable : public SupplementableBase<T, true> {
 231 public:
 232     PersistentHeapSupplementable() : m_root(this) { }
 233     virtual ~PersistentHeapSupplementable()
 234     {
 235         typedef typename SupplementableTraits<T, true>::SupplementMap::iterator SupplementIterator;
 236         for (SupplementIterator it = this->m_supplements.begin(); it != this->m_supplements.end(); ++it)
 237             it->value->persistentHostHasBeenDestroyed();
 238     }
 239
 240     virtual void trace(Visitor* visitor)
 241     {
 242         visitor->trace(this->m_supplements);
 243         SupplementableBase<T, true>::trace(visitor);
 244     }
 245
 246 private:
 247     class TraceDelegate : PersistentBase<ThreadLocalPersistents<AnyThread>, TraceDelegate> {
 248     public:
 249         TraceDelegate(PersistentHeapSupplementable* owner) : m_owner(owner) { }
 250         void trace(Visitor* visitor) { m_owner->trace(visitor); }
 251     private:
 252         PersistentHeapSupplementable* m_owner;
 253     };
 254
 255     TraceDelegate m_root;
 256 };
 257
 258 template<typename T>
 259 class Supplement : public SupplementBase<T, false> { };
 260
 261 // This class is used to make an off-heap class supplementable with off-heap
 262 // supplements (Supplement).
 263 template<typename T>
 264 class GC_PLUGIN_IGNORE("http://crbug.com/395036") Supplementable : public SupplementableBase<T, false> {
 265 public:
 266     virtual void trace(Visitor* visitor)
 267     {
 268         // No tracing of off-heap supplements. We should not have any Supplementable
 269         // object on the heap. Either the object is HeapSupplementable or if it is
 270         // off heap it should use PersistentHeapSupplementable to trace any on-heap
 271         // supplements.
 272         COMPILE_ASSERT(!IsGarbageCollectedType<T>::value, GarbageCollectedObjectMustBeHeapSupplementable);
 273         SupplementableBase<T, false>::trace(visitor);
 274     }
 275 };
 276
 277 template<typename T>
 278 struct ThreadingTrait<SupplementBase<T, true> > {
 279     static const ThreadAffinity Affinity = ThreadingTrait<T>::Affinity;
 280 };
 281
 282 template<typename T>
 283 struct ThreadingTrait<SupplementableBase<T, true> > {
 284     static const ThreadAffinity Affinity = ThreadingTrait<T>::Affinity;
 285 };
 286
 287 } // namespace blink
 288
 289 #endif // Supplementable_h