src/third_party/skia/src/core/SkLazyPtr.h

   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.
  68 class SkFontConfigInterfaceDirect;
  69
  70 namespace 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.
  74 template <typename P, void (*Destroy)(P)>
  75 static 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
  88 template <typename T> T* sk_new() { return SkNEW(T); }
  89 template <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).
 104 template <typename T, T* (*Create)() = sk_new<T>, void (*Destroy)(T*) = sk_delete<T> >
 105 class SkLazyPtr {
 106 public:
 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
 125 private:
 126     void* fPtr;
 127 };
 128
 129 template <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).
 132 template <typename T, int N, T* (*Create)(int) = sk_new_arg<T>, void (*Destroy)(T*) = sk_delete<T> >
 133 class SkLazyPtrArray {
 134 public:
 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
 152 private:
 153     void* fArray[N];
 154 };
 155
 156 }  // namespace Private
 157
 158 #endif//SkLazyPtr_DEFINED