/** Copyright 2007-2014 Haiku, Inc. All rights reserved.* Distributed under the terms of the MIT License.** Authors:* Niels Sascha Reedijk, niels.reedijk@gmail.com* John Scipione, jscipione@gmail.com** Corresponds to:* headers/os/support/Locker.h rev 36218* src/kits/support/Locker.cpp rev 32758*//*!\file Locker.h\ingroup support\ingroup libbe\brief Provides locking class BLocker.*//*!\class BLocker\ingroup support\ingroup libbe\brief Semaphore-type class for thread safety.The BLocker interface is not merely a wrapper around a semaphore, but italso has two advantages. First of all, it implements a benaphore.A benaphore is in some ways more speed efficient,because before it uses the internal semaphore, it first checks against avariable that is only operated on with atomic operations. Setting a variableis a lot more efficient than acquiring a semaphore, thus this type of lockingis much preferred.It basically works as follows. Whenever you newly created BLocker objectreceives a locking request, it atomically sets the benaphore variable to\c 1. Then only additional calls from different threads will utilize thesemaphore. You can imagine that in many cases where you protectof data that \em might be accessed by two or more concurrent threads, butthe chances of it happening being very small, the benaphore benefits themost from its speed.The other feature of BLocker that improves basic semaphore handling is thatit allows for recursive locks. The following piece of code works with aBLocker, but block inevitably with a semaphore. Let's pretend I call\c Water():\codestatus_tFlower::Grow(int length){if (fLock->Lock()) {fLength += length;fLock->Unlock();return B_OK;} elsereturn B_ERROR;}status_tFlower::Water(int amount){if (fLock->Lock()) {status_t status = Grow(amount * 2);fLock->Unlock();return status;} elsereturn B_ERROR;}\endcodeThis code would work because BLocker keeps track of the amount of lockrequests from the same thread. A normal semaphore would block in \c Grow()because the semaphore would be acquired already. Please do make sure youpair every Lock() with an Unlock() though, or you'll create a deadlock.\sa BAutolock\since BeOS R3*//*!\fn BLocker::BLocker()\brief Create a new BLocker with the default name "some BLocker" andbenaphore-style locking.This BLocker will use the benaphore-style locking.\note For debugging purposes, it's extremely convenient to actually give aname to the object. In case of a deadlock, it's easier to track downwhich BLocker object might have caused the problems.\see BLocker(const char*, bool) for all the options.\since BeOS R3*//*!\fn BLocker::BLocker(const char* name)\brief Creates a new BLocker with the given \a name and benaphore-stylelocking.\param name A NULL-terminated string that contains the name of thesemaphore. Note that the length of the names are limited to\c B_OS_NAME_LENGTH constant, which includes the \c \\0character.\see BLocker(const char* name, bool benaphoreStyle) for all the options.\since BeOS R3*//*!\fn BLocker::BLocker(bool benaphoreStyle)\brief Creates a BLocker with the default name "some BLocker" and the givenlocking style.\note For debugging purposes, it's extremely convenient to actually give aname to the object. In case of a deadlock, it's easier to track downwhich BLocker object might have caused the problems.\param benaphoreStyle If you pass \c true, the locker will be in benaphorestyle (which is the default option for other constructors). If youpass \c false, the object will completely rely on semaphores forits functioning.\see BLocker(const char* name, bool benaphoreStyle) if you also wantto set a name.\since BeOS R4*//*!\fn BLocker::BLocker(const char* name, bool benaphoreStyle)\brief Creates a new BLocker with the given \a name and locking style.\param name A NULL-terminated string that contains the name of thesemaphore. Note that the length of the names are limited to\c B_OS_NAME_LENGTH constant, which includes the \c \\0character.\param benaphoreStyle If you pass \c true, the locker will be in benaphorestyle (which is the default option for other constructors). Ifyou pass \c false, the object will completely rely on semaphoresfor its functioning.\since BeOS R4*//*!\fn virtual BLocker::~BLocker()\brief Destructor.Release the internal semaphore. Because of this, any pending Lock() callsfrom other threads be cancelled. The return code will be \c false forthose calls.\since BeOS R3*//*!\fn status_t BLocker::InitCheck() const\brief Check whether the locker has properly initialized\return A status code, \c B_OK if the semaphore has been properlyinitialized or any other error (negative) value relatedto semaphore initialization.\since Haiku R1*//*!\fn bool BLocker::Lock()\brief Add a lock request and block on it until we get it.\retval true Lock acquired successfully.\retval false Failed to acquire the lock. Most probable cause is that theobject is deleted. This frees the semaphore and releases thepending Lock() requests.\see LockWithTimeout(bigtime_t timeout), Unlock()\since BeOS R3*//*!\fn status_t BLocker::LockWithTimeout(bigtime_t timeout)\brief Add a lock request and block until we get it or until it times out.\param timeout This is a timeout in microseconds (one millionth of asecond) relative to now.\see Lock(), Unlock()\since BeOS R3*//*!\fn void BLocker::Unlock(void)\brief Release the lock that's currently held.\since BeOS R3*//*!\fn thread_id BLocker::LockingThread(void) const\brief Return the \c thread_id of the thread that's currently holding thelock.\since BeOS R3*//*!\fn bool BLocker::IsLocked(void) const\brief Check if the calling thread is actually holding the lock.\return Whether or not the calling thread is holding the lock.\retval true The thread from which this method is called from is currentlyholding the lock.\retval false The object is unlocked or the lock is held by another thread.\since BeOS R3*//*!\fn int32 BLocker::CountLocks(void) const\brief Return the number of recursive locks that are currently held.\return the number of currently held recursive locks as an int32.\since BeOS R3*//*!\fn int32 BLocker::CountLockRequests(void) const\brief Return the number of threads with a pending lock request.\return The number of threads with a pending lock request as an int32.\since BeOS R3*//*!\fn sem_id BLocker::Sem(void) const\brief Return the sem_id of the semaphore this object holds.\warning Like any other internal objects that the Haiku API might expose,this semaphore id should in general be left alone. You should notuse any of the public low-level semaphore functions on thissemaphore, because it will harm the internal consistency of theobject.\return The sem_id of the semaphore this object holds.\since BeOS R3*/