1 /*
2  * Copyright 2015 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 SkSemaphore_DEFINED
9 #define SkSemaphore_DEFINED
10 
11 #include "SkTypes.h"
12 #include "../private/SkAtomics.h"
13 #include "../private/SkOncePtr.h"
14 
15 struct SkBaseSemaphore {
16 
17     // Increment the counter by 1.
18     // This is a specialization for supporting SkMutex.
signalSkBaseSemaphore19     void signal() {
20         // Since this fetches the value before the add, 0 indicates that this thread is running and
21         // no threads are waiting, -1 and below means that threads are waiting, but only signal 1
22         // thread to run.
23         if (sk_atomic_fetch_add(&fCount, 1, sk_memory_order_release) < 0) {
24            this->osSignal(1);
25         }
26     }
27 
28     // Increment the counter N times.
29     // Generally it's better to call signal(N) instead of signal() N times.
30     void signal(int N);
31 
32     // Decrement the counter by 1,
33     // then if the counter is <= 0, sleep this thread until the counter is > 0.
waitSkBaseSemaphore34     void wait() {
35         // Since this fetches the value before the subtract, zero and below means that there are no
36         // resources left, so the thread needs to wait.
37         if (sk_atomic_fetch_sub(&fCount, 1, sk_memory_order_acquire) <= 0) {
38             this->osWait();
39         }
40     }
41 
42     struct OSSemaphore;
43 
44     void osSignal(int n);
45     void osWait();
46     void deleteSemaphore();
47 
48     // This implementation follows the general strategy of
49     //     'A Lightweight Semaphore with Partial Spinning'
50     // found here
51     //     http://preshing.com/20150316/semaphores-are-surprisingly-versatile/
52     // That article (and entire blog) are very much worth reading.
53     //
54     // We wrap an OS-provided semaphore with a user-space atomic counter that
55     // lets us avoid interacting with the OS semaphore unless strictly required:
56     // moving the count from >0 to <=0 or vice-versa, i.e. sleeping or waking threads.
57     int                        fCount;
58     SkBaseOncePtr<OSSemaphore> fOSSemaphore;
59 };
60 
61 /**
62  * SkSemaphore is a fast mostly-user-space semaphore.
63  *
64  * A semaphore is logically an atomic integer with a few special properties:
65  *   - The integer always starts at 0.
66  *   - You can only increment or decrement it, never read or write it.
67  *   - Increment is spelled 'signal()'; decrement is spelled 'wait()'.
68  *   - If a call to wait() decrements the counter to <= 0,
69  *     the calling thread sleeps until another thread signal()s it back above 0.
70  */
71 class SkSemaphore : SkNoncopyable {
72 public:
73     // Initializes the counter to 0.
74     // (Though all current implementations could start from an arbitrary value.)
75     SkSemaphore();
76     ~SkSemaphore();
77 
78     void wait();
79 
80     void signal(int n = 1);
81 
82 private:
83     SkBaseSemaphore fBaseSemaphore;
84 };
85 
86 #endif//SkSemaphore_DEFINED
87