1 : // Copyright (c) 2008 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 : // The LazyInstance<Type, Traits> class manages a single instance of Type,
6 : // which will be lazily created on the first time it's accessed. This class is
7 : // useful for places you would normally use a function-level static, but you
8 : // need to have guaranteed thread-safety. The Type constructor will only ever
9 : // be called once, even if two threads are racing to create the object. Get()
10 : // and Pointer() will always return the same, completely initialized instance.
11 : // When the instance is constructed it is registered with AtExitManager. The
12 : // destructor will be called on program exit.
13 : //
14 : // LazyInstance is completely thread safe, assuming that you create it safely.
15 : // The class was designed to be POD initialized, so it shouldn't require a
16 : // static constructor. It really only makes sense to declare a LazyInstance as
17 : // a global variable using the base::LinkerInitialized constructor.
18 : //
19 : // LazyInstance is similar to Singleton, except it does not have the singleton
20 : // property. You can have multiple LazyInstance's of the same type, and each
21 : // will manage a unique instance. It also preallocates the space for Type, as
22 : // to avoid allocating the Type instance on the heap. This may help with the
23 : // performance of creating the instance, and reducing heap fragmentation. This
24 : // requires that Type be a complete type so we can determine the size.
25 : //
26 : // Example usage:
27 : // static LazyInstance<MyClass> my_instance(base::LINKER_INITIALIZED);
28 : // void SomeMethod() {
29 : // my_instance.Get().SomeMethod(); // MyClass::SomeMethod()
30 : //
31 : // MyClass* ptr = my_instance.Pointer();
32 : // ptr->DoDoDo(); // MyClass::DoDoDo
33 : // }
34 :
35 : #ifndef BASE_LAZY_INSTANCE_H_
36 : #define BASE_LAZY_INSTANCE_H_
37 :
38 : #include "base/atomicops.h"
39 : #include "base/basictypes.h"
40 :
41 : namespace base {
42 :
43 : template <typename Type>
44 : struct DefaultLazyInstanceTraits {
45 4260 : static void New(void* instance) {
46 : // Use placement new to initialize our instance in our preallocated space.
47 : // The parenthesis is very important here to force POD type initialization.
48 4260 : new (instance) Type();
49 4260 : }
50 4257 : static void Delete(void* instance) {
51 : // Explicitly call the destructor.
52 4257 : reinterpret_cast<Type*>(instance)->~Type();
53 4257 : }
54 : };
55 :
56 : // We pull out some of the functionality into a non-templated base, so that we
57 : // can implement the more complicated pieces out of line in the .cc file.
58 : class LazyInstanceHelper {
59 : protected:
60 : enum {
61 : STATE_EMPTY = 0,
62 : STATE_CREATING = 1,
63 : STATE_CREATED = 2
64 : };
65 :
66 5856 : explicit LazyInstanceHelper(LinkerInitialized x) { /* state_ is 0 */ }
67 : // Declaring a destructor (even if it's empty) will cause MSVC to register a
68 : // static initializer to register the empty destructor with atexit().
69 :
70 : // Make sure that instance is created, creating or waiting for it to be
71 : // created if neccessary. Constructs with |ctor| in the space provided by
72 : // |instance| and registers dtor for destruction at program exit.
73 : void EnsureInstance(void* instance, void (*ctor)(void*), void (*dtor)(void*));
74 :
75 : base::subtle::Atomic32 state_;
76 :
77 : private:
78 : DISALLOW_COPY_AND_ASSIGN(LazyInstanceHelper);
79 : };
80 :
81 : template <typename Type, typename Traits = DefaultLazyInstanceTraits<Type> >
82 : class LazyInstance : public LazyInstanceHelper {
83 : public:
84 5856 : explicit LazyInstance(LinkerInitialized x) : LazyInstanceHelper(x) { }
85 : // Declaring a destructor (even if it's empty) will cause MSVC to register a
86 : // static initializer to register the empty destructor with atexit().
87 :
88 : Type& Get() {
89 : return *Pointer();
90 : }
91 :
92 25555 : Type* Pointer() {
93 25555 : Type* instance = reinterpret_cast<Type*>(&buf_);
94 :
95 : // We will hopefully have fast access when the instance is already created.
96 25555 : if (base::subtle::NoBarrier_Load(&state_) != STATE_CREATED)
97 4260 : EnsureInstance(instance, Traits::New, Traits::Delete);
98 :
99 25555 : return instance;
100 : }
101 :
102 : private:
103 : int8 buf_[sizeof(Type)]; // Preallocate the space for the Type instance.
104 :
105 : DISALLOW_COPY_AND_ASSIGN(LazyInstance);
106 : };
107 :
108 : } // namespace base
109 :
110 : #endif // BASE_LAZY_INSTANCE_H_
|