docs/develop/support/usecases/BAutolockUseCases.html

   1 <HTML>
   2 <!-- $Id: BAutolockUseCases.html 10 2002-07-09 12:24:59Z ejakowatz $ -->
   3 <HEAD>
   4 <TITLE>BAutolock 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>BAutolock Use Cases and Implementation Details:</H1>
  12
  13 <P>This document describes the BAutolock 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">BAutolock Interface</A></LI>
  18 <LI><A HREF="#usecases">BAutolock Use Cases</A></LI>
  19 <LI><A HREF="#implement">BAutolock Implementation</A></LI>
  20 </OL>
  21
  22 <A NAME="interface"></A><H2>BAutolock Interface:</H2>
  23
  24 <P>The BAutolock class is a simple class for handling synchronization between threads.  The best
  25 source of information for the BAutolock interface can be found
  26 <A HREF="file:///boot/beos/documentation/Be%20Book/The%20Support%20Kit/Autolock.html">here in the Be Book</A>.
  27 </P>
  28
  29 <A NAME="usecases"></A><H2>BAutolock Use Cases:</H2>
  30
  31 <P>The following use cases cover the BAutolock functionality:</P>
  32
  33 <OL>
  34 <LI><P><B>Construction 1:</B> A BAutolock can be created by passing a pointer to a BLocker object.
  35 An attempt will be made to Lock() this BLocker during the construction of the BAutolock object.
  36 </P></LI>
  37
  38 <LI><P><B>Construction 2:</B> A BAutolock can be created by passing a reference to a BLocker object.
  39 An attempt will be made to Lock() this BLocker during the construction of the BAutolock object.
  40 </P></LI>
  41
  42 <LI><P><B>Construction 3:</B> A BAutolock can be created by passing a pointer to a BLooper object.
  43 An attempt will be made to Lock() this BLooper during the construction of the BAutolock object.
  44 </P></LI>
  45
  46 <LI><P><B>Is Locked:</B> When the BAutolock is constructed, a lock is attempted on the BLocker or
  47 BLooper passed in.  The result of that lock attempt is returned by calling IsLocked() on the
  48 BAutolock.  The result is a boolean.  True is returned if the lock was successfully acquired.
  49 False is returned if the lock could not be acquired.  See the docs for BLocker and BLooper to
  50 find out why the lock acquisition may fail.</P></LI>
  51
  52 <LI><P><B>Destruction 1:</B> If the lock acquisition on the BLocker or BLooper was successful at
  53 construction time, when the BAutolock is destructed, the lock will be released by calling Unlock()
  54 on the BLocker or BLooper.</P></LI>
  55
  56 <LI><P><B>Destruction 2:</B> If the lock acquisition on the BLocker or BLooper failed at
  57 construction time, when the BAutolock is destructed, nothing is done to the BLocker or the BLooper.
  58 An Unlock() is not attempted because the lock at construction time failed.</P></LI>
  59
  60 </OL>
  61
  62 <A NAME="implement"></A><H2>BAutolock Implementation:</H2>
  63
  64 <P>The entire BAutolock implementation is inline.  Because BAutolock is implemented inline, there
  65 is no code for BAutolock in libbe.so.  The code is all in Be's Autolock.h header file and compiled
  66 at build time directly into any object being built.</P>
  67
  68 <P>This has some interesting implications from a backwards compatibility perspective.  Because
  69 there are no references from existing non-Be executables and libraries to libbe.so expecting
  70 to find the BAutolock class, the entire definition of BAutolock can be changed almost without risk
  71 of breaking compatibility.  This gives anyone wishing to expand and build on the current BAutolock
  72 class a great deal of flexibility.</P>
  73
  74 <P>However, it may be worthwhile when changing BAutolock in the future to try and stay source
  75 compatible.  That way, existing source code will continue to compile without having to update
  76 it.</P>
  77
  78 </BODY>
  79 </HTML>