1/* 2 * Copyright 2007 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Niels Sascha Reedijk, niels.reedijk@gmail.com 7 * 8 * Corresponds to: 9 * headers/os/support/Autolock.h rev 19972 10 */ 11 12 13/*! 14 \file Autolock.h 15 \ingroup support 16 \ingroup libbe 17 \brief Implements a handy locking utility. 18*/ 19 20 21/*! 22 \class BAutolock 23 \ingroup support 24 \ingroup libbe 25 \brief Convenient utility to make parts of your code thread-safe easily. 26 27 The autolocker uses a BLooper or a BLocker in order to protect a part 28 of your code. This class is usually used in combination with a BLocker 29 that protects a certain part of your code and data that are being 30 accessed by multiple threads. While BAutolock does not add any features 31 to locking, it provides a mechanism to easily lock and protect a part of your 32 code. 33 34 Normally, when you need to protect data, you would have to make sure that 35 all your locks are paired with unlocks. Below is a simple example, but you 36 can imagine that there are more complex situations where you might spend a 37 lot of time debugging a hang because you didn't pair all the Lock()s with an 38 Unlock(). See the example: 39 40\code 41status_t 42Receiver::HandleCall(Call *call) 43{ 44 ... work on call data ... 45 fDataLocker->Lock() 46 ... perform changes ... 47 if (!success) 48 { 49 fDataLocker->Unlock(); 50 return B_ERROR; 51 } 52 53 fDataLocker->Unlock() 54 return B_OK; 55} 56\endcode 57 With the BAutolock this example can be rewritten as follows: 58 59\code 60status_t 61Receiver::HandleCall(Call *call) 62{ 63 ... work on call data ... 64 65 BAutolock autolock(fDataLocker); 66 67 ... perform changes ... 68 69 if (!success) 70 return B_ERROR; 71 72 return B_OK; 73} 74\endcode 75 76 Since the object is created on stack, it is destroyed as soon as we leave 77 the function. Because the destruction of the object causes it to unlock 78 the BLocker or BLooper, you don't have to manually make sure that every 79 exit from the function is properly unlocked. 80*/ 81 82 83/*! 84 \fn BAutolock::BAutolock(BLooper *looper) 85 \brief Create an object and lock the BLooper 86*/ 87 88 89/*! 90 \fn BAutolock::BAutolock(BLocker *locker) 91 \brief Create an object and lock the BLocker 92*/ 93 94 95/*! 96 \fn BAutolock::BAutolock(BLocker &locker) 97 \brief Create an object and lock the BLocker 98*/ 99 100 101/*! 102 \fn BAutolock::~BAutolock() 103 \brief Destroy the object and unlock the associated BLocker or BLooper 104*/ 105 106 107/*! 108 \fn bool BAutolock::IsLocked(void) 109 \brief Verify whether the associated BLocker or BLooper are actually 110 locked. 111 112 Basically you may assume that when the object is created, you are 113 almost always sure the actual locking succeeds. It might fail if the 114 BLocker or BLooper are destroyed though. The semaphore will be 115 released and the Lock() call will fail. 116 117 If you expect this to happen, you can use this method to help you 118 protect yourself from any harm. 119 \retval true The lock was acquired. 120 \retval false Failed to acquire the lock. 121*/ 122