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 "SkAtomics.h" 31#include "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 36class SkOnceFlag; 37 38inline void SkOnce(SkOnceFlag* once, void (*f)()); 39 40template <typename Arg> 41inline 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. 44template <typename Lock> 45inline void SkOnce(bool* done, Lock* lock, void (*f)()); 46 47template <typename Lock, typename Arg> 48inline 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). 53class SkOnceFlag { 54public: 55 bool* mutableDone() { return &fDone; } 56 57 void acquire() { fSpinlock.acquire(); } 58 void release() { fSpinlock.release(); } 59 60private: 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.) 72template <typename Lock, typename Arg> 73static 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. 92template <typename Lock, typename Arg> 93inline 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 118template <typename Arg> 119inline 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?) 126static void sk_once_no_arg_adaptor(void (*f)()) { 127 f(); 128} 129 130inline void SkOnce(SkOnceFlag* once, void (*func)()) { 131 return SkOnce(once, sk_once_no_arg_adaptor, func); 132} 133 134template <typename Lock> 135inline 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