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. 14The 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 25source of information for the BAutolock interface can be found in 26<A HREF="https://www.haiku-os.org/legacy-docs/bebook/BAutolock.html">the Be Book documentation</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. 35An 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. 39An 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. 43An 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 47BLooper passed in. The result of that lock attempt is returned by calling IsLocked() on the 48BAutolock. The result is a boolean. True is returned if the lock was successfully acquired. 49False is returned if the lock could not be acquired. See the docs for BLocker and BLooper to 50find 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 53construction time, when the BAutolock is destructed, the lock will be released by calling Unlock() 54on 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 57construction time, when the BAutolock is destructed, nothing is done to the BLocker or the BLooper. 58An 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 65is no code for BAutolock in libbe.so. The code is all in Be's Autolock.h header file and compiled 66at build time directly into any object being built.</P> 67 68<P>This has some interesting implications from a backwards compatibility perspective. Because 69there are no references from existing non-Be executables and libraries to libbe.so expecting 70to find the BAutolock class, the entire definition of BAutolock can be changed almost without risk 71of breaking compatibility. This gives anyone wishing to expand and build on the current BAutolock 72class 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 75compatible. That way, existing source code will continue to compile without having to update 76it.</P> 77 78</BODY> 79</HTML> 80