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 "SkDynamicAnnotations.h"
31#include "SkThread.h"
32#include "SkTypes.h"
33
34// This must be used in a global or function scope, not as a class member.
35#define SK_DECLARE_STATIC_ONCE(name) static SkOnceFlag name
36
37class SkOnceFlag;
38
39inline void SkOnce(SkOnceFlag* once, void (*f)());
40
41template <typename Arg>
42inline void SkOnce(SkOnceFlag* once, void (*f)(Arg), Arg arg);
43
44// If you've already got a lock and a flag to use, this variant lets you avoid an extra SkOnceFlag.
45template <typename Lock>
46inline void SkOnce(bool* done, Lock* lock, void (*f)());
47
48template <typename Lock, typename Arg>
49inline void SkOnce(bool* done, Lock* lock, void (*f)(Arg), Arg arg);
50
51//  ----------------------  Implementation details below here. -----------------------------
52
53// This class has no constructor and must be zero-initialized (the macro above does this).
54class SkOnceFlag {
55public:
56    bool* mutableDone() { return &fDone; }
57
58    void acquire() {
59        // To act as a mutex, this needs an acquire barrier on success.
60        // sk_atomic_cas doesn't guarantee this ...
61        while (!sk_atomic_cas(&fSpinlock, 0, 1)) {
62            // spin
63        }
64        // ... so make sure to issue one of our own.
65        SkAssertResult(sk_acquire_load(&fSpinlock));
66    }
67
68    void release() {
69        // To act as a mutex, this needs a release barrier.  sk_atomic_cas guarantees this.
70        SkAssertResult(sk_atomic_cas(&fSpinlock, 1, 0));
71    }
72
73private:
74    bool fDone;
75    int32_t fSpinlock;
76};
77
78// We've pulled a pretty standard double-checked locking implementation apart
79// into its main fast path and a slow path that's called when we suspect the
80// one-time code hasn't run yet.
81
82// This is the guts of the code, called when we suspect the one-time code hasn't been run yet.
83// This should be rarely called, so we separate it from SkOnce and don't mark it as inline.
84// (We don't mind if this is an actual function call, but odds are it'll be inlined anyway.)
85template <typename Lock, typename Arg>
86static void sk_once_slow(bool* done, Lock* lock, void (*f)(Arg), Arg arg) {
87    lock->acquire();
88    if (!*done) {
89        f(arg);
90        // Also known as a store-store/load-store barrier, this makes sure that the writes
91        // done before here---in particular, those done by calling f(arg)---are observable
92        // before the writes after the line, *done = true.
93        //
94        // In version control terms this is like saying, "check in the work up
95        // to and including f(arg), then check in *done=true as a subsequent change".
96        //
97        // We'll use this in the fast path to make sure f(arg)'s effects are
98        // observable whenever we observe *done == true.
99        sk_release_store(done, true);
100    }
101    lock->release();
102}
103
104// This is our fast path, called all the time.  We do really want it to be inlined.
105template <typename Lock, typename Arg>
106inline void SkOnce(bool* done, Lock* lock, void (*f)(Arg), Arg arg) {
107    if (!SK_ANNOTATE_UNPROTECTED_READ(*done)) {
108        sk_once_slow(done, lock, f, arg);
109    }
110    // Also known as a load-load/load-store barrier, this acquire barrier makes
111    // sure that anything we read from memory---in particular, memory written by
112    // calling f(arg)---is at least as current as the value we read from done.
113    //
114    // In version control terms, this is a lot like saying "sync up to the
115    // commit where we wrote done = true".
116    //
117    // The release barrier in sk_once_slow guaranteed that done = true
118    // happens after f(arg), so by syncing to done = true here we're
119    // forcing ourselves to also wait until the effects of f(arg) are readble.
120    SkAssertResult(sk_acquire_load(done));
121}
122
123template <typename Arg>
124inline void SkOnce(SkOnceFlag* once, void (*f)(Arg), Arg arg) {
125    return SkOnce(once->mutableDone(), once, f, arg);
126}
127
128// Calls its argument.
129// This lets us use functions that take no arguments with SkOnce methods above.
130// (We pass _this_ as the function and the no-arg function as its argument.  Cute eh?)
131static void sk_once_no_arg_adaptor(void (*f)()) {
132    f();
133}
134
135inline void SkOnce(SkOnceFlag* once, void (*func)()) {
136    return SkOnce(once, sk_once_no_arg_adaptor, func);
137}
138
139template <typename Lock>
140inline void SkOnce(bool* done, Lock* lock, void (*func)()) {
141    return SkOnce(done, lock, sk_once_no_arg_adaptor, func);
142}
143
144#endif  // SkOnce_DEFINED
145