docs/develop/support/usecases/BLockerUseCases.html

   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.
  14 The 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
  25 source of information for the BLocker interface can be found
  26 <A HREF="file:///boot/beos/documentation/Be%20Book/The%20Support%20Kit/Locker.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
  35 internally.  If a name is specified during construction, then that name is given to the internal
  36 semaphore.  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
  40 on a flag passed when the BLocker is created.  If the flag is false, the BLocker uses a semaphore
  41 to do synchronization.  If the flag is true, the BLocker uses a benaphore internally to do
  42 synchronization.  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
  45 immediately unblocked.  The threads are notified by the return code of the locking member function
  46 that the lock was not successfully acquired.  Any threads blocked on Lock() will return with
  47 a 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()
  50 member 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(),
  53 the member function returns immediately.  The thread must call Unlock() the same number of times
  54 it calls Lock...() before the BLocker is released.  At any time, the thread can call CountLocks()
  55 to 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
  58 lock.  Once the lock has been acquired or an unrecoverable error has occurred, the Lock() member
  59 function completes.  If the lock has been acquired, Lock() returns true.  If the lock has not
  60 been 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
  63 acquire the lock, the time specified in microseconds expires, or an unrecoverable error occurs.
  64 If the timeout specified is B_INFINTE_TIMEOUT, there is no timeout and the member function will
  65 either acquire the lock or fail due to an unrecoverable error.  If the lock is acquired, the
  66 member function returns B_OK.  If the timeout is reached, B_TIMED_OUT is returned and the lock is
  67 not 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.
  70 If the thread currently holds the lock, the lock count is reduced by the call to Unlock().  If
  71 the lock count reaches zero, then another thread may acquire the lock.  If the thread does not
  72 hold 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
  75 thread 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
  78 held by the calling thread.  If the BLocker is not acquired by any thread or it is acquired by a
  79 different 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
  82 has been acquired by the thread which holds the lock.  If no thread holds the lock, then 0 is
  83 returned.  If the BLocker is held by any thread, including a thread which is not the thread
  84 making the CountLocks() request, the number of times the lock has been acquired by the thread which
  85 holds the lock is returned.</P></LI>
  86
  87 <LI><P><B>Count Lock Requests:</B> The CountLockRequests() member function returns the number of
  88 threads currently attempting to lock the BLocker.  If no thread holds the lock and no thread is
  89 waiting for the lock, then 0 is returned.  If one thread holds the lock and no other threads
  90 are waiting for the lock, then 1 is returned.  If one thread holds the lock and x threads are
  91 waiting for the lock, then x+1 is returned.  The call to CountLockRequests() can be made by any
  92 thread 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
  95 function.  In actuality, the value returned is just the "benaphore count" for the BLocker.
  96 If the BLocker is semaphore style, then the benaphore count is set to 1 at construction time
  97 to ensure that the semaphore is always tested when a lock is acquired.  The return value is
  98 just this count.  So, the return value for benaphore style is:</P>
  99
 100 <PRE>
 101 numThreadsWaitingForTheLock + numThreadsHoldingTheLock + numOfTimeoutsOccuredOnTheLock
 102 </PRE>
 103
 104 <P>The return value for a semaphore style is:</P>
 105
 106 <PRE>
 107 numThreadsWaitingForTheLock + numThreadsHoldingTheLock + numOfTimeoutsOccuredOnTheLock + 1
 108 </PRE>
 109
 110 <P>Again, this is what we are implementing but the above description is what appears in the
 111 BeBook 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
 115 BLocker.  If the BLocker is a benaphore, then the sem_id returned is the semaphore used to
 116 implement the benaphore.  If the BLocker is a not a benaphore, then the sem_id returned is the
 117 semaphore 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
 123 found on Be's website at
 124
 125 <A HREF="http://www-classic.be.com/aboutbe/benewsletter/Issue26.html">http://www-classic.be.com/aboutbe/benewsletter/Issue26.html</A>.</P>
 126
 127
 128
 129 </BODY>
 130 </HTML>