Home | History | Annotate | Download | only in platform 
      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 "wtf/Assertions.h"
     30 #include "wtf/HashMap.h"
     31 #include "wtf/OwnPtr.h"
     32 #include "wtf/PassOwnPtr.h"
     33 
     34 #if !ASSERT_DISABLED
     35 #include "wtf/Threading.h"
     36 #endif
     37 
     38 namespace WebCore {
     39 
     40 // What you should know about Supplementable and Supplement
     41 // ========================================================
     42 // Supplementable and Supplement instances are meant to be thread local. They
     43 // should only be accessed from within the thread that created them. The
     44 // 2 classes are not designed for safe access from another thread. Violating
     45 // this design assumption can result in memory corruption and unpredictable
     46 // behavior.
     47 //
     48 // What you should know about the Supplement keys
     49 // ==============================================
     50 // The Supplement is expected to use the same const char* string instance
     51 // as its key. The Supplementable's SupplementMap will use the address of the
     52 // string as the key and not the characters themselves. Hence, 2 strings with
     53 // the same characters will be treated as 2 different keys.
     54 //
     55 // In practice, it is recommended that Supplements implements a static method
     56 // for returning its key to use. For example:
     57 //
     58 //     class MyClass : public Supplement<MySupplementable> {
     59 //         ...
     60 //         static const char* supplementName();
     61 //     }
     62 //
     63 //     const char* MyClass::supplementName()
     64 //     {
     65 //         return "MyClass";
     66 //     }
     67 //
     68 // An example of the using the key:
     69 //
     70 //     MyClass* MyClass::from(MySupplementable* host)
     71 //     {
     72 //         return reinterpret_cast<MyClass*>(Supplement<MySupplementable>::from(host, supplementName()));
     73 //     }
     74 //
     75 // What you should know about thread checks
     76 // ========================================
     77 // When assertion is enabled this class performs thread-safety check so that
     78 // provideTo and from happen on the same thread. If you want to provide
     79 // some value for Workers this thread check may not work very well though,
     80 // since in most case you'd provide the value while worker preparation is
     81 // being done on the main thread, even before the worker thread is started.
     82 // If that's the case you can explicitly call reattachThread() when the
     83 // Supplementable object is passed to the final destination thread (i.e.
     84 // worker thread). Please be extremely careful to use the method though,
     85 // as randomly calling the method could easily cause racy condition.
     86 //
     87 // Note that reattachThread() does nothing if assertion is not enabled.
     88 //
     89 
     90 template<typename T>
     91 class Supplementable;
     92 
     93 template<typename T>
     94 class Supplement {
     95 public:
     96     virtual ~Supplement() { }
     97 #if !ASSERT_DISABLED || defined(ADDRESS_SANITIZER)
     98     virtual bool isRefCountedWrapper() const { return false; }
     99 #endif
    100 
    101     static void provideTo(Supplementable<T>* host, const char* key, PassOwnPtr<Supplement<T> > supplement)
    102     {
    103         host->provideSupplement(key, supplement);
    104     }
    105 
    106     static Supplement<T>* from(Supplementable<T>* host, const char* key)
    107     {
    108         return host ? host->requireSupplement(key) : 0;
    109     }
    110 };
    111 
    112 template<typename T>
    113 class Supplementable {
    114 public:
    115     void provideSupplement(const char* key, PassOwnPtr<Supplement<T> > supplement)
    116     {
    117         ASSERT(m_threadId == currentThread());
    118         ASSERT(!m_supplements.get(key));
    119         m_supplements.set(key, supplement);
    120     }
    121 
    122     void removeSupplement(const char* key)
    123     {
    124         ASSERT(m_threadId == currentThread());
    125         m_supplements.remove(key);
    126     }
    127 
    128     Supplement<T>* requireSupplement(const char* key)
    129     {
    130         ASSERT(m_threadId == currentThread());
    131         return m_supplements.get(key);
    132     }
    133 
    134     void reattachThread()
    135     {
    136 #if !ASSERT_DISABLED
    137         m_threadId = currentThread();
    138 #endif
    139     }
    140 
    141 #if !ASSERT_DISABLED
    142 protected:
    143     Supplementable() : m_threadId(currentThread()) { }
    144 #endif
    145 
    146 private:
    147     typedef HashMap<const char*, OwnPtr<Supplement<T> >, PtrHash<const char*> > SupplementMap;
    148     SupplementMap m_supplements;
    149 #if !ASSERT_DISABLED
    150     ThreadIdentifier m_threadId;
    151 #endif
    152 };
    153 
    154 } // namespace WebCore
    155 
    156 #endif // Supplementable_h
    157