1/* 2 * Copyright 2007-2014 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 * John Scipione, jscipione@gmail.com 8 * 9 * Corresponds to: 10 * headers/os/support/Autolock.h rev 33370 11 */ 12 13 14/*! 15 \file Autolock.h 16 \ingroup support 17 \ingroup libbe 18 \brief Implements a handy locking utility. 19*/ 20 21 22/*! 23 \class BAutolock 24 \ingroup support 25 \ingroup libbe 26 \brief Convenient utility to make parts of your code thread-safe easily. 27 28 The autolocker uses a BLooper or a BLocker in order to protect a part 29 of your code. This class is usually used in combination with a BLocker 30 that protects a certain part of your code and data that are being 31 accessed by multiple threads. While BAutolock does not add any features 32 to locking, it provides a mechanism to easily lock and protect a part of 33 your code. 34 35 Normally, when you need to protect data, you would have to make sure that 36 all your locks are paired with unlocks. Below is a simple example, but you 37 can imagine that there are more complex situations where you might spend a 38 lot of time debugging a hang because you didn't pair all the Lock()s with 39 an Unlock(). See the example: 40 41\code 42status_t 43Receiver::HandleCall(Call *call) 44{ 45 ... work on call data ... 46 47 fDataLocker->Lock() 48 49 ... perform changes ... 50 51 if (!success) { 52 fDataLocker->Unlock(); 53 return B_ERROR; 54 } 55 56 fDataLocker->Unlock() 57 58 return B_OK; 59} 60\endcode 61 With the BAutolock this example can be rewritten as follows: 62 63\code 64status_t 65Receiver::HandleCall(Call *call) 66{ 67 ... work on call data ... 68 69 BAutolock autolock(fDataLocker); 70 71 ... perform changes ... 72 73 if (!success) 74 return B_ERROR; 75 76 return B_OK; 77} 78\endcode 79 80 Since the object is created on stack, it is destroyed as soon as we leave 81 the function. Because the destruction of the object causes it to unlock 82 the BLocker or BLooper, you don't have to manually make sure that every 83 exit from the function is properly unlocked. 84 85 \since BeOS R3 86*/ 87 88 89/*! 90 \fn BAutolock::BAutolock(BLooper* looper) 91 \brief Create an object and lock the BLooper 92 93 \since BeOS R3 94*/ 95 96 97/*! 98 \fn BAutolock::BAutolock(BLocker* locker) 99 \brief Create an object and lock the BLocker 100 101 \since BeOS R3 102*/ 103 104 105/*! 106 \fn BAutolock::BAutolock(BLocker& locker) 107 \brief Create an object and lock the BLocker 108 109 \since BeOS R3 110*/ 111 112 113/*! 114 \fn BAutolock::~BAutolock() 115 \brief Destroy the object and unlock the associated BLocker or BLooper 116 117 \since BeOS R3 118*/ 119 120 121/*! 122 \fn bool BAutolock::IsLocked() 123 \brief Verify whether the associated BLocker or BLooper are actually 124 locked. 125 126 Basically you may assume that when the object is created, you are 127 almost always sure the actual locking succeeds. It might fail if the 128 BLocker or BLooper are destroyed though. The semaphore will be 129 released and the Lock() call will fail. 130 131 If you expect this to happen, you can use this method to help you 132 protect yourself from any harm. 133 134 \return Whether or not the BLocker or BLooper is locked. 135 \retval true The lock was acquired. 136 \retval false Failed to acquire the lock. 137 138 \since BeOS R3 139*/ 140 141 142/*! 143 \fn bool BAutolock::Lock() 144 \brief Lock the BAutolock if it has not already happened 145 146 Note that unlike BLocker, the object is not locked with lock count. That 147 means that if the lock is already taken, this method returns \c true 148 without any action. 149 150 \return Whether or not the BLocker or BLooper was locked. 151 \retval true The lock was acquired (or had already been acquired). 152 \retval false Failed to acquire the lock. 153 154 \since Haiku R1 155*/ 156 157 158/*! 159 \fn void BAutolock::Unlock() 160 \brief Unlock the BAutolock if the lock is being held. 161 162 If the lock is not held, the method does nothing. 163 164 \since Haiku R1 165*/