docs/user/support/Autolock.dox

   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
  42 status_t
  43 Receiver::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
  64 status_t
  65 Receiver::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 */