1/*
2 * Copyright 2014 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 SkLazyPtr_DEFINED
9#define SkLazyPtr_DEFINED
10
11/** Declare a lazily-chosen static pointer (or array of pointers) of type F.
12 *
13 *  Example usage:
14 *
15 *  Foo* GetSingletonFoo() {
16 *      SK_DECLARE_STATIC_LAZY_PTR(Foo, singleton);  // Created with SkNEW, destroyed with SkDELETE.
17 *      return singleton.get();
18 *  }
19 *
20 *  These macros take an optional T* (*Create)() and void (*Destroy)(T*) at the end.
21 *  If not given, we'll use SkNEW and SkDELETE.
22 *  These options are most useful when T doesn't have a public constructor or destructor.
23 *  Create comes first, so you may use a custom Create with a default Destroy, but not vice versa.
24 *
25 *  Foo* CustomCreate() { return ...; }
26 *  void CustomDestroy(Foo* ptr) { ... }
27 *  Foo* GetSingletonFooWithCustomCleanup() {
28 *      SK_DECLARE_STATIC_LAZY_PTR(Foo, singleton, CustomCreate, CustomDestroy);
29 *      return singleton.get();
30 *  }
31 *
32 *  If you have a bunch of related static pointers of the same type, you can
33 *  declare an array of lazy pointers together, and we'll pass the index to Create().
34 *
35 *  Foo* CreateFoo(int i) { return ...; }
36 *  Foo* GetCachedFoo(Foo::Enum enumVal) {
37 *      SK_DECLARE_STATIC_LAZY_PTR_ARRAY(Foo, Foo::kEnumCount, cachedFoos, CreateFoo);
38 *      return cachedFoos[enumVal];
39 *  }
40 *
41 *
42 *  You can think of SK_DECLARE_STATIC_LAZY_PTR as a cheaper specialization of
43 *  SkOnce.  There is no mutex or extra storage used past the pointer itself.
44 *  In debug mode, each lazy pointer will be cleaned up at process exit so we
45 *  can check that we've not leaked or freed them early.
46 *
47 *  We may call Create more than once, but all threads will see the same pointer
48 *  returned from get().  Any extra calls to Create will be cleaned up.
49 *
50 *  These macros must be used in a global or function scope, not as a class member.
51 */
52
53#define SK_DECLARE_STATIC_LAZY_PTR(T, name, ...) \
54    static Private::SkLazyPtr<T, ##__VA_ARGS__> name
55
56#define SK_DECLARE_STATIC_LAZY_PTR_ARRAY(T, name, N, ...) \
57    static Private::SkLazyPtrArray<T, N, ##__VA_ARGS__> name
58
59
60
61// Everything below here is private implementation details.  Don't touch, don't even look.
62
63#include "SkDynamicAnnotations.h"
64#include "SkThread.h"
65#include "SkThreadPriv.h"
66
67// See FIXME below.
68class SkFontConfigInterfaceDirect;
69
70namespace Private {
71
72// Set *dst to ptr if *dst is NULL.  Returns value of *dst, destroying ptr if not swapped in.
73// Issues the same memory barriers as sk_atomic_cas: acquire on failure, release on success.
74template <typename P, void (*Destroy)(P)>
75static P try_cas(void** dst, P ptr) {
76    P prev = (P)sk_atomic_cas(dst, NULL, ptr);
77
78    if (prev) {
79        // We need an acquire barrier before returning prev, which sk_atomic_cas provided.
80        Destroy(ptr);
81        return prev;
82    } else {
83        // We need a release barrier before returning ptr, which sk_atomic_cas provided.
84        return ptr;
85    }
86}
87
88template <typename T> T* sk_new() { return SkNEW(T); }
89template <typename T> void sk_delete(T* ptr) { SkDELETE(ptr); }
90
91// We're basing these implementations here on this article:
92//   http://preshing.com/20140709/the-purpose-of-memory_order_consume-in-cpp11/
93//
94// Because the users of SkLazyPtr and SkLazyPtrArray will read the pointers
95// _through_ our atomically set pointer, there is a data dependency between our
96// atomic and the guarded data, and so we only need writer-releases /
97// reader-consumes memory pairing rather than the more general write-releases /
98// reader-acquires convention.
99//
100// This is nice, because a sk_consume_load is free on all our platforms: x86,
101// ARM, MIPS.  In contrast, sk_acquire_load issues a memory barrier on non-x86.
102
103// This has no constructor and must be zero-initalized (the macro above does this).
104template <typename T, T* (*Create)() = sk_new<T>, void (*Destroy)(T*) = sk_delete<T> >
105class SkLazyPtr {
106public:
107    T* get() {
108        // If fPtr has already been filled, we need a consume barrier when loading it.
109        // If not, we need a release barrier when setting it.  try_cas will do that.
110        T* ptr = (T*)sk_consume_load(&fPtr);
111        return ptr ? ptr : try_cas<T*, Destroy>(&fPtr, Create());
112    }
113
114#ifdef SK_DEVELOPER
115    // FIXME: We know we leak refs on some classes.  For now, let them leak.
116    void cleanup(SkFontConfigInterfaceDirect*) {}
117    template <typename U> void cleanup(U* ptr) { Destroy(ptr); }
118
119    ~SkLazyPtr() {
120        this->cleanup((T*)fPtr);
121        fPtr = NULL;
122    }
123#endif
124
125private:
126    void* fPtr;
127};
128
129template <typename T> T* sk_new_arg(int i) { return SkNEW_ARGS(T, (i)); }
130
131// This has no constructor and must be zero-initalized (the macro above does this).
132template <typename T, int N, T* (*Create)(int) = sk_new_arg<T>, void (*Destroy)(T*) = sk_delete<T> >
133class SkLazyPtrArray {
134public:
135    T* operator[](int i) {
136        SkASSERT(i >= 0 && i < N);
137        // If fPtr has already been filled, we need an consume barrier when loading it.
138        // If not, we need a release barrier when setting it.  try_cas will do that.
139        T* ptr = (T*)sk_consume_load(&fArray[i]);
140        return ptr ? ptr : try_cas<T*, Destroy>(&fArray[i], Create(i));
141    }
142
143#ifdef SK_DEVELOPER
144    ~SkLazyPtrArray() {
145        for (int i = 0; i < N; i++) {
146            Destroy((T*)fArray[i]);
147            fArray[i] = NULL;
148        }
149    }
150#endif
151
152private:
153    void* fArray[N];
154};
155
156}  // namespace Private
157
158#endif//SkLazyPtr_DEFINED
159