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
80namespace v8 {
81namespace internal {
82
83typedef AtomicWord OnceType;
84
85#define V8_ONCE_INIT 0
86
87#define V8_DECLARE_ONCE(NAME) ::v8::internal::OnceType NAME
88
89enum {
90  ONCE_STATE_UNINITIALIZED = 0,
91  ONCE_STATE_EXECUTING_FUNCTION = 1,
92  ONCE_STATE_DONE = 2
93};
94
95typedef void (*NoArgFunction)();
96typedef void (*PointerArgFunction)(void* arg);
97
98template <typename T>
99struct OneArgFunction {
100  typedef void (*type)(T);
101};
102
103void CallOnceImpl(OnceType* once, PointerArgFunction init_func, void* arg);
104
105inline 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
112template <typename Arg>
113inline 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