1 /* 2 * Copyright (c) 2001-2005, Haiku, Inc. 3 * Distributed under the terms of the MIT license. 4 * 5 * Author: Erik Jaesler <erik@cgsoftware.com> 6 */ 7 8 /** Semaphore-type class for thread safety */ 9 10 11 #include <OS.h> 12 #include <Locker.h> 13 #include <SupportDefs.h> 14 15 #include "support_kit_config.h" 16 17 // 18 // Data Member Documentation: 19 // 20 // The "fBenaphoreCount" member is set to 1 if the BLocker style is 21 // semaphore. If the style is benaphore, it is initialized to 0 and 22 // is incremented atomically when it is acquired, decremented when it 23 // is released. By setting the benaphore count to 1 when the style is 24 // semaphore, the benaphore effectively becomes a semaphore. I was able 25 // to determine this is what Be's implementation does by testing the 26 // result of the CountLockRequests() member. 27 // 28 // The "fSemaphoreID" member holds the sem_id returned from create_sem() 29 // when the BLocker is constructed. It is used to acquire and release 30 // the lock regardless of the lock style (semaphore or benaphore). 31 // 32 // The "fLockOwner" member holds the thread_id of the thread which 33 // currently holds the lock. If no thread holds the lock, it is set to 34 // B_ERROR. 35 // 36 // The "fRecursiveCount" member holds a count of the number of times the 37 // thread holding the lock has acquired the lock without a matching unlock. 38 // It is basically the number of times the thread must call Unlock() before 39 // the lock can be acquired by a different thread. 40 // 41 42 43 // 44 // Constructors: 45 // 46 // All constructors just pass their arguments to InitLocker(). Note that 47 // the default for "name" is "some BLocker" and "benaphore_style" is true. 48 // 49 50 BLocker::BLocker() 51 { 52 InitLocker(NULL, true); 53 } 54 55 56 BLocker::BLocker(const char *name) 57 { 58 InitLocker(name, true); 59 } 60 61 62 BLocker::BLocker(bool benaphoreStyle) 63 { 64 InitLocker(NULL, benaphoreStyle); 65 } 66 67 68 BLocker::BLocker(const char *name, bool benaphoreStyle) 69 { 70 InitLocker(name, benaphoreStyle); 71 } 72 73 74 // 75 // This constructor is not documented. The final argument is ignored for 76 // now. In Be's headers, its called "for_IPC". DO NOT USE THIS 77 // CONSTRUCTOR! 78 // 79 BLocker::BLocker(const char *name, bool benaphoreStyle, 80 bool) 81 { 82 InitLocker(name, benaphoreStyle); 83 } 84 85 86 // 87 // The destructor just deletes the semaphore. By deleting the semaphore, 88 // any threads waiting to acquire the BLocker will be unblocked. 89 // 90 BLocker::~BLocker() 91 { 92 delete_sem(fSemaphoreID); 93 } 94 95 96 status_t 97 BLocker::InitCheck() const 98 { 99 return fSemaphoreID >= 0 ? B_OK : fSemaphoreID; 100 } 101 102 103 bool 104 BLocker::Lock(void) 105 { 106 status_t result; 107 return AcquireLock(B_INFINITE_TIMEOUT, &result); 108 } 109 110 111 status_t 112 BLocker::LockWithTimeout(bigtime_t timeout) 113 { 114 status_t result; 115 116 AcquireLock(timeout, &result); 117 return result; 118 } 119 120 121 122 void 123 BLocker::Unlock(void) 124 { 125 // If the thread currently holds the lockdecrement 126 if (IsLocked()) { 127 // Decrement the number of outstanding locks this thread holds 128 // on this BLocker. 129 fRecursiveCount--; 130 131 // If the recursive count is now at 0, that means the BLocker has 132 // been released by the thread. 133 if (fRecursiveCount == 0) { 134 // The BLocker is no longer owned by any thread. 135 fLockOwner = B_ERROR; 136 137 // Decrement the benaphore count and store the undecremented 138 // value in oldBenaphoreCount. 139 int32 oldBenaphoreCount = atomic_add(&fBenaphoreCount, -1); 140 141 // If the oldBenaphoreCount is greater than 1, then there is 142 // at lease one thread waiting for the lock in the case of a 143 // benaphore. 144 if (oldBenaphoreCount > 1) { 145 // Since there are threads waiting for the lock, it must 146 // be released. Note, the old benaphore count will always be 147 // greater than 1 for a semaphore so the release is always done. 148 release_sem(fSemaphoreID); 149 } 150 } 151 } 152 } 153 154 155 thread_id 156 BLocker::LockingThread(void) const 157 { 158 return fLockOwner; 159 } 160 161 162 bool 163 BLocker::IsLocked(void) const 164 { 165 // This member returns true if the calling thread holds the lock. 166 // The easiest way to determine this is to compare the result of 167 // find_thread() to the fLockOwner. 168 return find_thread(NULL) == fLockOwner; 169 } 170 171 172 int32 173 BLocker::CountLocks(void) const 174 { 175 return fRecursiveCount; 176 } 177 178 179 int32 180 BLocker::CountLockRequests(void) const 181 { 182 return fBenaphoreCount; 183 } 184 185 186 sem_id 187 BLocker::Sem(void) const 188 { 189 return fSemaphoreID; 190 } 191 192 193 void 194 BLocker::InitLocker(const char *name, bool benaphore) 195 { 196 if (name == NULL) 197 name = "some BLocker"; 198 199 if (benaphore && !BLOCKER_ALWAYS_SEMAPHORE_STYLE) { 200 // Because this is a benaphore, initialize the benaphore count and 201 // create the semaphore. Because this is a benaphore, the semaphore 202 // count starts at 0 (ie acquired). 203 fBenaphoreCount = 0; 204 fSemaphoreID = create_sem(0, name); 205 } else { 206 // Because this is a semaphore, initialize the benaphore count to -1 207 // and create the semaphore. Because this is semaphore style, the 208 // semaphore count starts at 1 so that one thread can acquire it and 209 // the next thread to acquire it will block. 210 fBenaphoreCount = 1; 211 fSemaphoreID = create_sem(1, name); 212 } 213 214 // The lock is currently not acquired so there is no owner. 215 fLockOwner = B_ERROR; 216 217 // The lock is currently not acquired so the recursive count is zero. 218 fRecursiveCount = 0; 219 } 220 221 222 bool 223 BLocker::AcquireLock(bigtime_t timeout, status_t *error) 224 { 225 // By default, return no error. 226 status_t status = B_OK; 227 228 // Only try to acquire the lock if the thread doesn't already own it. 229 if (!IsLocked()) { 230 // Increment the benaphore count and test to see if it was already greater 231 // than 0. If it is greater than 0, then some thread already has the 232 // benaphore or the style is a semaphore. Either way, we need to acquire 233 // the semaphore in this case. 234 int32 oldBenaphoreCount = atomic_add(&fBenaphoreCount, 1); 235 if (oldBenaphoreCount > 0) { 236 do { 237 status = acquire_sem_etc(fSemaphoreID, 1, B_RELATIVE_TIMEOUT, 238 timeout); 239 } while (status == B_INTERRUPTED); 240 241 // Note, if the lock here does time out, the benaphore count 242 // is not decremented. By doing this, the benaphore count will 243 // never go back to zero. This means that the locking essentially 244 // changes to semaphore style if this was a benaphore. 245 // 246 // Doing the decrement of the benaphore count when the acquisition 247 // fails is a risky thing to do. If you decrement the counter at 248 // the same time the thread which holds the benaphore does an 249 // Unlock(), there is serious risk of a race condition. 250 // 251 // If the Unlock() sees a positive count and releases the semaphore 252 // and then the timed out thread decrements the count to 0, there 253 // is no one to take the semaphore. The next two threads will be 254 // able to acquire the benaphore at the same time! The first will 255 // increment the counter and acquire the lock. The second will 256 // acquire the semaphore and therefore the lock. Not good. 257 // 258 // This has been discussed on the becodetalk mailing list and 259 // Trey from Be had this to say: 260 // 261 // I looked at the LockWithTimeout() code, and it does not have 262 // _this_ (ie the race condition) problem. It circumvents it by 263 // NOT doing the atomic_add(&count, -1) if the semaphore 264 // acquisition fails. This means that if a 265 // BLocker::LockWithTimeout() times out, all other Lock*() attempts 266 // turn into guaranteed semaphore grabs, _with_ the overhead of a 267 // (now) useless atomic_add(). 268 // 269 // Given Trey's comments, it looks like Be took the same approach 270 // I did. The output of CountLockRequests() of Be's implementation 271 // confirms Trey's comments also. 272 // 273 // Finally some thoughts for the future with this code: 274 // - If 2^31 timeouts occur on a 32-bit machine (ie today), 275 // the benaphore count will wrap to a negative number. This 276 // would have unknown consequences on the ability of the BLocker 277 // to continue to function. 278 // 279 } 280 } 281 282 // If the lock has successfully been acquired. 283 if (status == B_OK) { 284 // Set the lock owner to this thread and increment the recursive count 285 // by one. The recursive count is incremented because one more Unlock() 286 // is now required to release the lock (ie, 0 => 1, 1 => 2 etc). 287 fLockOwner = find_thread(NULL); 288 fRecursiveCount++; 289 } 290 291 if (error != NULL) 292 *error = status; 293 294 // Return true if the lock has been acquired. 295 return (status == B_OK); 296 } 297