Public Member Functions | List of all members
BAutolock Class Reference

Convenient utility to make parts of your code thread-safe easily. More...

Public Member Functions

 BAutolock (BLooper *looper)
 Create an object and lock the BLooper. More...
 
 BAutolock (BLocker *locker)
 Create an object and lock the BLocker. More...
 
 BAutolock (BLocker &locker)
 Create an object and lock the BLocker. More...
 
 ~BAutolock ()
 Destroy the object and unlock the associated BLocker or BLooper. More...
 
bool IsLocked ()
 Verify whether the associated BLocker or BLooper are actually locked. More...
 
bool Lock ()
 Lock the BAutolock if it has not already happened. More...
 
void Unlock ()
 Unlock the BAutolock if the lock is being held. More...
 

Detailed Description

Convenient utility to make parts of your code thread-safe easily.

The autolocker uses a BLooper or a BLocker in order to protect a part of your code. This class is usually used in combination with a BLocker that protects a certain part of your code and data that are being accessed by multiple threads. While BAutolock does not add any features to locking, it provides a mechanism to easily lock and protect a part of your code.

Normally, when you need to protect data, you would have to make sure that all your locks are paired with unlocks. Below is a simple example, but you can imagine that there are more complex situations where you might spend a lot of time debugging a hang because you didn't pair all the Lock()s with an Unlock(). See the example:

Receiver::HandleCall(Call *call)
{
... work on call data ...
fDataLocker->Lock()
... perform changes ...
if (!success) {
fDataLocker->Unlock();
return B_ERROR;
}
fDataLocker->Unlock()
return B_OK;
}

With the BAutolock this example can be rewritten as follows:

Receiver::HandleCall(Call *call)
{
... work on call data ...
BAutolock autolock(fDataLocker);
... perform changes ...
if (!success)
return B_ERROR;
return B_OK;
}

Since the object is created on stack, it is destroyed as soon as we leave the function. Because the destruction of the object causes it to unlock the BLocker or BLooper, you don't have to manually make sure that every exit from the function is properly unlocked.

Since
BeOS R3

Constructor & Destructor Documentation

◆ BAutolock() [1/3]

BAutolock::BAutolock ( BLooper looper)
inline

Create an object and lock the BLooper.

Since
BeOS R3

◆ BAutolock() [2/3]

BAutolock::BAutolock ( BLocker locker)
inline

Create an object and lock the BLocker.

Since
BeOS R3

◆ BAutolock() [3/3]

BAutolock::BAutolock ( BLocker locker)
inline

Create an object and lock the BLocker.

Since
BeOS R3

◆ ~BAutolock()

BAutolock::~BAutolock ( )
inline

Destroy the object and unlock the associated BLocker or BLooper.

Since
BeOS R3

References Unlock().

Member Function Documentation

◆ IsLocked()

bool BAutolock::IsLocked ( )
inline

Verify whether the associated BLocker or BLooper are actually locked.

Basically you may assume that when the object is created, you are almost always sure the actual locking succeeds. It might fail if the BLocker or BLooper are destroyed though. The semaphore will be released and the Lock() call will fail.

If you expect this to happen, you can use this method to help you protect yourself from any harm.

Returns
Whether or not the BLocker or BLooper is locked.
Return values
trueThe lock was acquired.
falseFailed to acquire the lock.
Since
BeOS R3

◆ Lock()

bool BAutolock::Lock ( )
inline

Lock the BAutolock if it has not already happened.

Note that unlike BLocker, the object is not locked with lock count. That means that if the lock is already taken, this method returns true without any action.

Returns
Whether or not the BLocker or BLooper was locked.
Return values
trueThe lock was acquired (or had already been acquired).
falseFailed to acquire the lock.
Since
Haiku R1

References BLocker::Lock(), BLooper::Lock(), and NULL.

◆ Unlock()

void BAutolock::Unlock ( )
inline

Unlock the BAutolock if the lock is being held.

If the lock is not held, the method does nothing.

Since
Haiku R1

References NULL, BLocker::Unlock(), and BLooper::Unlock().

Referenced by ~BAutolock().