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