This document describes the BAutolock interface and some basics of how it is implemented. The document has the following sections:
The BAutolock class is a simple class for handling synchronization between threads. The best source of information for the BAutolock interface can be found here in the Be Book.
The following use cases cover the BAutolock functionality:
Construction 1: A BAutolock can be created by passing a pointer to a BLocker object. An attempt will be made to Lock() this BLocker during the construction of the BAutolock object.
Construction 2: A BAutolock can be created by passing a reference to a BLocker object. An attempt will be made to Lock() this BLocker during the construction of the BAutolock object.
Construction 3: A BAutolock can be created by passing a pointer to a BLooper object. An attempt will be made to Lock() this BLooper during the construction of the BAutolock object.
Is Locked: When the BAutolock is constructed, a lock is attempted on the BLocker or BLooper passed in. The result of that lock attempt is returned by calling IsLocked() on the BAutolock. The result is a boolean. True is returned if the lock was successfully acquired. False is returned if the lock could not be acquired. See the docs for BLocker and BLooper to find out why the lock acquisition may fail.
Destruction 1: If the lock acquisition on the BLocker or BLooper was successful at construction time, when the BAutolock is destructed, the lock will be released by calling Unlock() on the BLocker or BLooper.
Destruction 2: If the lock acquisition on the BLocker or BLooper failed at construction time, when the BAutolock is destructed, nothing is done to the BLocker or the BLooper. An Unlock() is not attempted because the lock at construction time failed.
The entire BAutolock implementation is inline. Because BAutolock is implemented inline, there is no code for BAutolock in libbe.so. The code is all in Be's Autolock.h header file and compiled at build time directly into any object being built.
This has some interesting implications from a backwards compatibility perspective. Because there are no references from existing non-Be executables and libraries to libbe.so expecting to find the BAutolock class, the entire definition of BAutolock can be changed almost without risk of breaking compatibility. This gives anyone wishing to expand and build on the current BAutolock class a great deal of flexibility.
However, it may be worthwhile when changing BAutolock in the future to try and stay source compatible. That way, existing source code will continue to compile without having to update it.