1<HTML> 2<!-- $Id: BLockerUseCases.html 10 2002-07-09 12:24:59Z ejakowatz $ --> 3<HEAD> 4<TITLE>BLocker Use Cases and Implementation Details</TITLE> 5</HEAD> 6 7<BODY BGCOLOR="white" LINK="#000067" VLINK="#000067" ALINK="#0000FF"> 8 9<FONT FACE="Verdana,Arial,Helvetica,sans-serif" SIZE="-1"> 10 11<H1>BLocker Use Cases and Implementation Details:</H1> 12 13<P>This document describes the BLocker interface and some basics of how it is implemented. 14The document has the following sections:</P> 15 16<OL> 17<LI><A HREF="#interface">BLocker Interface</A></LI> 18<LI><A HREF="#usecases">BLocker Use Cases</A></LI> 19<LI><A HREF="#implement">BLocker Implementation</A></LI> 20</OL> 21 22<A NAME="interface"></A><H2>BLocker Interface:</H2> 23 24<P>The BLocker class is a simple class for handling synchronization between threads. The best 25source of information for the BLocker interface can be found 26<A HREF="https://www.haiku-os.org/legacy-docs/bebook/BLocker.html">here in the Be Book</A>. 27</P> 28 29<A NAME="usecases"></A><H2>BLocker Use Cases:</H2> 30 31<P>The following use cases cover the BLocker functionality:</P> 32 33<OL> 34<LI><P><B>Construction 1:</B> A BLocker can be created by specifying a name for the semaphore used 35internally. If a name is specified during construction, then that name is given to the internal 36semaphore. If no name is given at construction, the semaphore is given the name "some BLocker". 37</P></LI> 38 39<LI><P><B>Construction 2:</B> A BLocker can use a semaphore or a "benaphore" internally depending 40on a flag passed when the BLocker is created. If the flag is false, the BLocker uses a semaphore 41to do synchronization. If the flag is true, the BLocker uses a benaphore internally to do 42synchronization. If no flag is specified, the BLocker uses a benaphore internally.</P></LI> 43 44<LI><P><B>Destruction:</B> When a BLocker is destructed, any threads waiting for the lock are 45immediately unblocked. The threads are notified by the return code of the locking member function 46that the lock was not successfully acquired. Any threads blocked on Lock() will return with 47a false value. Any threads blocked on LockWithTimeout() will return with B_BAD_SEM_ID.</P></LI> 48 49<LI><P><B>Locking 1:</B> When a thread acquires the BLocker using the Lock() or LockWithTimeout() 50member functions, no other thread can acquire the lock until this thread releases it.</P></LI> 51 52<LI><P><B>Locking 2:</B> When a thread holds the BLocker and it calls Lock() or LockWithTimeout(), 53the member function returns immediately. The thread must call Unlock() the same number of times 54it calls Lock...() before the BLocker is released. At any time, the thread can call CountLocks() 55to get the number of times it must call Unlock() to release the BLocker.</P></LI> 56 57<LI><P><B>Locking 3:</B> When a thread calls Lock(), the thread blocks until it can acquire the 58lock. Once the lock has been acquired or an unrecoverable error has occurred, the Lock() member 59function completes. If the lock has been acquired, Lock() returns true. If the lock has not 60been acquired, Lock() returns false.</P></LI> 61 62<LI><P><B>Locking 4:</B> When a thread calls LockWithTimeout(), the thread blocks until it can 63acquire the lock, the time specified in microseconds expires, or an unrecoverable error occurs. 64If the timeout specified is B_INFINTE_TIMEOUT, there is no timeout and the member function will 65either acquire the lock or fail due to an unrecoverable error. If the lock is acquired, the 66member function returns B_OK. If the timeout is reached, B_TIMED_OUT is returned and the lock is 67not acquired. If a serious error occurs, a non B_OK code is returned.</P></LI> 68 69<LI><P><B>Unlocking:</B> The Unlock() member function takes no arguments and returns no value. 70If the thread currently holds the lock, the lock count is reduced by the call to Unlock(). If 71the lock count reaches zero, then another thread may acquire the lock. If the thread does not 72hold the lock and it calls Unlock(), the call will have no affect at all on the BLocker.</P></LI> 73 74<LI><P><B>Locking Thread:</B> The LockingThread() member function returns the thread_id of the 75thread that is holding the lock. If no thread holds the lock, then B_ERROR is returned.</P></LI> 76 77<LI><P><B>Is Locked:</B> The IsLocked() member function returns true if the BLocker is currently 78held by the calling thread. If the BLocker is not acquired by any thread or it is acquired by a 79different thread, IsLocked() returns false.</P></LI> 80 81<LI><P><B>Count Locks:</B> The CountLocks() member function returns the number of times the lock 82has been acquired by the thread which holds the lock. If no thread holds the lock, then 0 is 83returned. If the BLocker is held by any thread, including a thread which is not the thread 84making the CountLocks() request, the number of times the lock has been acquired by the thread which 85holds the lock is returned.</P></LI> 86 87<LI><P><B>Count Lock Requests:</B> The CountLockRequests() member function returns the number of 88threads currently attempting to lock the BLocker. If no thread holds the lock and no thread is 89waiting for the lock, then 0 is returned. If one thread holds the lock and no other threads 90are waiting for the lock, then 1 is returned. If one thread holds the lock and x threads are 91waiting for the lock, then x+1 is returned. The call to CountLockRequests() can be made by any 92thread including threads which do not have the lock.</P> 93 94<P><B>NOTE:</B> Reading the Be Book, that would seem like what is returned by this member 95function. In actuality, the value returned is just the "benaphore count" for the BLocker. 96If the BLocker is semaphore style, then the benaphore count is set to 1 at construction time 97to ensure that the semaphore is always tested when a lock is acquired. The return value is 98just this count. So, the return value for benaphore style is:</P> 99 100<PRE> 101numThreadsWaitingForTheLock + numThreadsHoldingTheLock + numOfTimeoutsOccuredOnTheLock 102</PRE> 103 104<P>The return value for a semaphore style is:</P> 105 106<PRE> 107numThreadsWaitingForTheLock + numThreadsHoldingTheLock + numOfTimeoutsOccuredOnTheLock + 1 108</PRE> 109 110<P>Again, this is what we are implementing but the above description is what appears in the 111BeBook as far as I understand it.</P> 112</LI> 113 114<LI><P><B>Sem:</B> The Sem() member function returns the sem_id of the semaphore used by the 115BLocker. If the BLocker is a benaphore, then the sem_id returned is the semaphore used to 116implement the benaphore. If the BLocker is a not a benaphore, then the sem_id returned is the 117semaphore which the BLocker represents.</P></LI> 118</OL> 119 120<A NAME="implement"></A><H2>BLocker Implementation:</H2> 121 122<P>For more information about how to implement a benaphore, you can reference an implementation 123found on Be's website at 124 125<A HREF="https://www.haiku-os.org/legacy-docs/benewsletter/Issue1-26.html">https://www.haiku-os.org/legacy-docs/benewsletter/Issue1-26.html</A>.</P> 126 127 128 129</BODY> 130</HTML> 131