1 /* 2 * Copyright (C) 2016 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef ANDROID_AUDIO_FIFO_INDEX_H 18 #define ANDROID_AUDIO_FIFO_INDEX_H 19 20 #include <atomic> 21 #include <stdint.h> 22 #include <time.h> 23 24 /** 25 * An index that may optionally be placed in shared memory. 26 * Must be Plain Old Data (POD), so no virtual methods are allowed. 27 * If in shared memory, exactly one process must explicitly call the constructor via placement new. 28 * \see #audio_utils_fifo_sync 29 */ 30 class audio_utils_fifo_index { 31 32 public: 33 audio_utils_fifo_index() : mIndex(0) { } 34 ~audio_utils_fifo_index() { } 35 36 /** 37 * Load value of index now with memory order 'acquire'. 38 * 39 * \return Index value 40 */ 41 uint32_t loadAcquire(); 42 43 /** 44 * Store new value into index now with memory order 'release'. 45 * 46 * \param value New value to store into index 47 */ 48 void storeRelease(uint32_t value); 49 50 // TODO op should be set in the constructor. 51 /** 52 * Wait for value of index to change from the specified expected value. 53 * 54 * \param op Either FUTEX_WAIT or FUTEX_WAIT_PRIVATE. 55 * \param expected Current/expected value of index. 56 * \param timeout Indicates the maximum time to block while waiting for value to change. 57 * NULL means to block forever. 58 * Time is expressed as relative CLOCK_MONOTONIC. 59 * We use the Linux kernel representation of time for the very lowest levels, 60 * and save other representations for the APIs that are built on top of this. 61 * This permits APIs to choose the int64_t representation if desired, or the 62 * Linux representation without a double conversion. 63 * 64 * \return Zero for success, or a negative error code as specified at "man 2 futex". 65 */ 66 int wait(int op, uint32_t expected, const struct timespec *timeout); 67 68 // TODO op should be set in the constructor. 69 /** 70 * Wake up any threads waiting for the value of index to change. 71 * 72 * \param op Either FUTEX_WAIT or FUTEX_WAIT_PRIVATE. 73 * \param waiters Maximum number of waiting threads to wake up. 74 * 75 * \return Actual number of threads woken up. 76 */ 77 int wake(int op, int waiters = 1); 78 79 // specialized use only, prefer loadAcquire in most cases 80 uint32_t loadConsume(); 81 82 private: 83 // Linux futex is 32 bits regardless of platform. 84 // It would make more sense to declare this as atomic_uint32_t, but there is no such type name. 85 // TODO Support 64-bit index with 32-bit futex in low-order bits. 86 std::atomic_uint_least32_t mIndex; // accessed by both sides using atomic operations 87 static_assert(sizeof(mIndex) == sizeof(uint32_t), "mIndex must be 32 bits"); 88 }; 89 90 static_assert(sizeof(audio_utils_fifo_index) == sizeof(uint32_t), 91 "audio_utils_fifo_index must be 32 bits"); 92 93 // TODO 94 // From a design POV, these next two classes should be related. 95 // Extract a base class (that shares their property of being a reference to a fifo index) 96 // This should be good in the case if there is a need for generic manipulations on these references. 97 // Or can we perhaps define a template and make two specializations of it. 98 // This is in the case when compile-time polymorphism is sufficient. 99 100 /** 101 * A reference to an audio_utils_fifo_index with deferred store-release and deferred wake. 102 * 103 * TODO Currently the index and futex share the same 32-bit cell. 104 * In the future, the index may optionally be increased to 64-bits, 105 * and the futex will either be the low-order 32 bits of the index, 106 * or an unrelated 32-bit cell used as a set of event flags. 107 * Both of these will require a change to the API. 108 */ 109 class RefIndexDeferredStoreReleaseDeferredWake 110 { 111 public: 112 RefIndexDeferredStoreReleaseDeferredWake(audio_utils_fifo_index& index); 113 ~RefIndexDeferredStoreReleaseDeferredWake(); 114 115 // Place 'value' into the cache but do not store it to memory yet. 116 void set(uint32_t value); 117 118 // If there is a new value in the cache, store it now with memory order 'release'. 119 void writeback(); 120 121 // Place 'value' into the cache and then store it with memory order 'release'. 122 void writethrough(uint32_t value); 123 124 // op is FUTEX_WAKE or FUTEX_WAKE_PRIVATE 125 // TODO op should be set in the constructor, and should be abstracted. 126 // waiters is number of waiting threads to wake up 127 void wakeDeferred(int op, int waiters = 1); 128 void wakeNowIfNeeded(); 129 // TODO op should be set in the constructor. 130 void wakeNow(int op, int waiters = 1); 131 132 private: 133 audio_utils_fifo_index& mIndex; // reference to associated index 134 uint32_t mValue; // cached value to be stored 135 bool mWriteback; // whether the cached value needs to be stored 136 int mWaiters; // number of waiters to wake 137 int mWakeOp; // which kind of wake operation to use 138 }; 139 140 /** 141 * A reference to an audio_utils_fifo_index with cached load-acquire, and deferred wait. 142 * 143 * TODO Same as RefIndexDeferredStoreReleaseDeferredWake. 144 */ 145 class RefIndexCachedLoadAcquireDeferredWait 146 { 147 public: 148 RefIndexCachedLoadAcquireDeferredWait(audio_utils_fifo_index& index); 149 ~RefIndexCachedLoadAcquireDeferredWait(); 150 151 // If value is already cached, return the cached value. 152 // Otherwise load now with memory order 'acquire', cache for later, and return the value. 153 uint32_t get(); 154 155 // If value is already cached, this is a no-op. 156 // Otherwise load now with memory order 'acquire' and cache the value for later use. 157 void prefetch(); 158 159 // Discard any value in the cache. 160 void invalidate(); 161 162 #if 0 163 /** 164 * Load a fresh value for index, ignoring any previously cached information. 165 */ 166 uint32_t readthrough(); 167 #endif 168 169 // TODO This is an immediate wait, but we needed deferred wait 170 /** 171 * Wait for value of index to change from when it was most recently read with get(). 172 * To avoid a race condition, the caller must have already read the index with get(), 173 * and then made the decision to call wait() based on that value. 174 * 175 * \param op Either FUTEX_WAIT or FUTEX_WAIT_PRIVATE. 176 * \param timeout Indicates the maximum time to block while waiting for value to change. 177 * NULL means to block forever. 178 * Time is expressed as relative CLOCK_MONOTONIC. 179 * See above for explanation of why representation is struct timespec. 180 * 181 * \return Zero for success, or a negative error code as specified at "man 2 futex". 182 * \retval -EINVAL caller did not call get() prior to wait() 183 */ 184 int wait(int op, const struct timespec *timeout); 185 186 private: 187 audio_utils_fifo_index& mIndex; // reference to associated index 188 uint32_t mValue; // most recently cached value 189 bool mLoaded; // whether mValue is valid 190 }; 191 192 #endif // !ANDROID_AUDIO_FIFO_INDEX_H 193
