1 // Copyright 2012 the V8 project authors. All rights reserved.
2 // Redistribution and use in source and binary forms, with or without
3 // modification, are permitted provided that the following conditions are
4 // met:
5 //
6 // * Redistributions of source code must retain the above copyright
7 // notice, this list of conditions and the following disclaimer.
8 // * Redistributions in binary form must reproduce the above
9 // copyright notice, this list of conditions and the following
10 // disclaimer in the documentation and/or other materials provided
11 // with the distribution.
12 // * Neither the name of Google Inc. nor the names of its
13 // contributors may be used to endorse or promote products derived
14 // from this software without specific prior written permission.
15 //
16 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
17 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
18 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
19 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
20 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
21 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
22 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
26 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27
28 // emulates google3/base/once.h
29 //
30 // This header is intended to be included only by v8's internal code. Users
31 // should not use this directly.
32 //
33 // This is basically a portable version of pthread_once().
34 //
35 // This header declares:
36 // * A type called OnceType.
37 // * A macro V8_DECLARE_ONCE() which declares a (global) variable of type
38 // OnceType.
39 // * A function CallOnce(OnceType* once, void (*init_func)()).
40 // This function, when invoked multiple times given the same OnceType object,
41 // will invoke init_func on the first call only, and will make sure none of
42 // the calls return before that first call to init_func has finished.
43 //
44 // Additionally, the following features are supported:
45 // * A macro V8_ONCE_INIT which is expanded into the expression used to
46 // initialize a OnceType. This is only useful when clients embed a OnceType
47 // into a structure of their own and want to initialize it statically.
48 // * The user can provide a parameter which CallOnce() forwards to the
49 // user-provided function when it is called. Usage example:
50 // CallOnce(&my_once, &MyFunctionExpectingIntArgument, 10);
51 // * This implementation guarantees that OnceType is a POD (i.e. no static
52 // initializer generated).
53 //
54 // This implements a way to perform lazy initialization. It's more efficient
55 // than using mutexes as no lock is needed if initialization has already
56 // happened.
57 //
58 // Example usage:
59 // void Init();
60 // V8_DECLARE_ONCE(once_init);
61 //
62 // // Calls Init() exactly once.
63 // void InitOnce() {
64 // CallOnce(&once_init, &Init);
65 // }
66 //
67 // Note that if CallOnce() is called before main() has begun, it must
68 // only be called by the thread that will eventually call main() -- that is,
69 // the thread that performs dynamic initialization. In general this is a safe
70 // assumption since people don't usually construct threads before main() starts,
71 // but it is technically not guaranteed. Unfortunately, Win32 provides no way
72 // whatsoever to statically-initialize its synchronization primitives, so our
73 // only choice is to assume that dynamic initialization is single-threaded.
74
75 #ifndef V8_ONCE_H_
76 #define V8_ONCE_H_
77
78 #include "atomicops.h"
79
80 namespace v8 {
81 namespace internal {
82
83 typedef AtomicWord OnceType;
84
85 #define V8_ONCE_INIT 0
86
87 #define V8_DECLARE_ONCE(NAME) ::v8::internal::OnceType NAME
88
89 enum {
90 ONCE_STATE_UNINITIALIZED = 0,
91 ONCE_STATE_EXECUTING_FUNCTION = 1,
92 ONCE_STATE_DONE = 2
93 };
94
95 typedef void (*NoArgFunction)();
96 typedef void (*PointerArgFunction)(void* arg);
97
98 template <typename T>
99 struct OneArgFunction {
100 typedef void (*type)(T);
101 };
102
103 void CallOnceImpl(OnceType* once, PointerArgFunction init_func, void* arg);
104
CallOnce(OnceType * once,NoArgFunction init_func)105 inline void CallOnce(OnceType* once, NoArgFunction init_func) {
106 if (Acquire_Load(once) != ONCE_STATE_DONE) {
107 CallOnceImpl(once, reinterpret_cast<PointerArgFunction>(init_func), NULL);
108 }
109 }
110
111
112 template <typename Arg>
CallOnce(OnceType * once,typename OneArgFunction<Arg * >::type init_func,Arg * arg)113 inline void CallOnce(OnceType* once,
114 typename OneArgFunction<Arg*>::type init_func, Arg* arg) {
115 if (Acquire_Load(once) != ONCE_STATE_DONE) {
116 CallOnceImpl(once, reinterpret_cast<PointerArgFunction>(init_func),
117 static_cast<void*>(arg));
118 }
119 }
120
121 } } // namespace v8::internal
122
123 #endif // V8_ONCE_H_
124