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
38namespace 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
75template<typename T>
76class Supplementable;
77
78template<typename T>
79class Supplement {
80public:
81    virtual ~Supplement() { }
82#if !ASSERT_DISABLED || defined(ADDRESS_SANITIZER)
83    virtual bool isRefCountedWrapper() const { return false; }
84#endif
85
86    static void provideTo(Supplementable<T>* host, const char* key, PassOwnPtr<Supplement<T> > supplement)
87    {
88        host->provideSupplement(key, supplement);
89    }
90
91    static Supplement<T>* from(Supplementable<T>* host, const char* key)
92    {
93        return host ? host->requireSupplement(key) : 0;
94    }
95};
96
97template<typename T>
98class Supplementable {
99public:
100    void provideSupplement(const char* key, PassOwnPtr<Supplement<T> > supplement)
101    {
102        ASSERT(m_threadId == currentThread());
103        ASSERT(!m_supplements.get(key));
104        m_supplements.set(key, supplement);
105    }
106
107    void removeSupplement(const char* key)
108    {
109        ASSERT(m_threadId == currentThread());
110        m_supplements.remove(key);
111    }
112
113    Supplement<T>* requireSupplement(const char* key)
114    {
115        ASSERT(m_threadId == currentThread());
116        return m_supplements.get(key);
117    }
118
119#if !ASSERT_DISABLED
120protected:
121    Supplementable() : m_threadId(currentThread()) { }
122#endif
123
124private:
125    typedef HashMap<const char*, OwnPtr<Supplement<T> >, PtrHash<const char*> > SupplementMap;
126    SupplementMap m_supplements;
127#if !ASSERT_DISABLED
128    ThreadIdentifier m_threadId;
129#endif
130};
131
132} // namespace WebCore
133
134#endif // Supplementable_h
135
136