1 /*
2 * Copyright 2013 Google Inc.
3 *
4 * Use of this source code is governed by a BSD-style license that can be
5 * found in the LICENSE file.
6 */
7
8 #ifndef SkOnce_DEFINED
9 #define SkOnce_DEFINED
10
11 // Before trying SkOnce, see if SkLazyPtr or SkLazyFnPtr will work for you.
12 // They're smaller and faster, if slightly less versatile.
13
14
15 // SkOnce.h defines SK_DECLARE_STATIC_ONCE and SkOnce(), which you can use
16 // together to create a threadsafe way to call a function just once. E.g.
17 //
18 // static void register_my_stuff(GlobalRegistry* registry) {
19 // registry->register(...);
20 // }
21 // ...
22 // void EnsureRegistered() {
23 // SK_DECLARE_STATIC_ONCE(once);
24 // SkOnce(&once, register_my_stuff, GetGlobalRegistry());
25 // }
26 //
27 // No matter how many times you call EnsureRegistered(), register_my_stuff will be called just once.
28 // OnceTest.cpp also should serve as a few other simple examples.
29
30 #include "../private/SkAtomics.h"
31 #include "../private/SkSpinlock.h"
32
33 // This must be used in a global scope, not in function scope or as a class member.
34 #define SK_DECLARE_STATIC_ONCE(name) namespace {} static SkOnceFlag name
35
36 class SkOnceFlag;
37
38 inline void SkOnce(SkOnceFlag* once, void (*f)());
39
40 template <typename Arg>
41 inline void SkOnce(SkOnceFlag* once, void (*f)(Arg), Arg arg);
42
43 // If you've already got a lock and a flag to use, this variant lets you avoid an extra SkOnceFlag.
44 template <typename Lock>
45 inline void SkOnce(bool* done, Lock* lock, void (*f)());
46
47 template <typename Lock, typename Arg>
48 inline void SkOnce(bool* done, Lock* lock, void (*f)(Arg), Arg arg);
49
50 // ---------------------- Implementation details below here. -----------------------------
51
52 // This class has no constructor and must be zero-initialized (the macro above does this).
53 class SkOnceFlag {
54 public:
mutableDone()55 bool* mutableDone() { return &fDone; }
56
acquire()57 void acquire() { fSpinlock.acquire(); }
release()58 void release() { fSpinlock.release(); }
59
60 private:
61 bool fDone;
62 SkPODSpinlock fSpinlock;
63 };
64
65 // We've pulled a pretty standard double-checked locking implementation apart
66 // into its main fast path and a slow path that's called when we suspect the
67 // one-time code hasn't run yet.
68
69 // This is the guts of the code, called when we suspect the one-time code hasn't been run yet.
70 // This should be rarely called, so we separate it from SkOnce and don't mark it as inline.
71 // (We don't mind if this is an actual function call, but odds are it'll be inlined anyway.)
72 template <typename Lock, typename Arg>
sk_once_slow(bool * done,Lock * lock,void (* f)(Arg),Arg arg)73 static void sk_once_slow(bool* done, Lock* lock, void (*f)(Arg), Arg arg) {
74 lock->acquire();
75 if (!sk_atomic_load(done, sk_memory_order_relaxed)) {
76 f(arg);
77 // Also known as a store-store/load-store barrier, this makes sure that the writes
78 // done before here---in particular, those done by calling f(arg)---are observable
79 // before the writes after the line, *done = true.
80 //
81 // In version control terms this is like saying, "check in the work up
82 // to and including f(arg), then check in *done=true as a subsequent change".
83 //
84 // We'll use this in the fast path to make sure f(arg)'s effects are
85 // observable whenever we observe *done == true.
86 sk_release_store(done, true);
87 }
88 lock->release();
89 }
90
91 // This is our fast path, called all the time. We do really want it to be inlined.
92 template <typename Lock, typename Arg>
SkOnce(bool * done,Lock * lock,void (* f)(Arg),Arg arg)93 inline void SkOnce(bool* done, Lock* lock, void (*f)(Arg), Arg arg) {
94 // When *done == true:
95 // Also known as a load-load/load-store barrier, this acquire barrier makes
96 // sure that anything we read from memory---in particular, memory written by
97 // calling f(arg)---is at least as current as the value we read from done.
98 //
99 // In version control terms, this is a lot like saying "sync up to the
100 // commit where we wrote done = true".
101 //
102 // The release barrier in sk_once_slow guaranteed that done = true
103 // happens after f(arg), so by syncing to done = true here we're
104 // forcing ourselves to also wait until the effects of f(arg) are readble.
105 //
106 // When *done == false:
107 // We'll try to call f(arg) in sk_once_slow.
108 // If we get the lock, great, we call f(arg), release true into done, and drop the lock.
109 // If we race and don't get the lock first, we'll wait for the first guy to finish.
110 // Then lock acquire() will give us at least an acquire memory barrier to get the same
111 // effect as the acquire load in the *done == true fast case. We'll see *done is true,
112 // then just drop the lock and return.
113 if (!sk_atomic_load(done, sk_memory_order_acquire)) {
114 sk_once_slow(done, lock, f, arg);
115 }
116 }
117
118 template <typename Arg>
SkOnce(SkOnceFlag * once,void (* f)(Arg),Arg arg)119 inline void SkOnce(SkOnceFlag* once, void (*f)(Arg), Arg arg) {
120 return SkOnce(once->mutableDone(), once, f, arg);
121 }
122
123 // Calls its argument.
124 // This lets us use functions that take no arguments with SkOnce methods above.
125 // (We pass _this_ as the function and the no-arg function as its argument. Cute eh?)
sk_once_no_arg_adaptor(void (* f)())126 static void sk_once_no_arg_adaptor(void (*f)()) {
127 f();
128 }
129
SkOnce(SkOnceFlag * once,void (* func)())130 inline void SkOnce(SkOnceFlag* once, void (*func)()) {
131 return SkOnce(once, sk_once_no_arg_adaptor, func);
132 }
133
134 template <typename Lock>
SkOnce(bool * done,Lock * lock,void (* func)())135 inline void SkOnce(bool* done, Lock* lock, void (*func)()) {
136 return SkOnce(done, lock, sk_once_no_arg_adaptor, func);
137 }
138
139 #endif // SkOnce_DEFINED
140