BambooLib

2.0.1

Author:

Brett Bode - brett@scl.ameslab.gov

Sam Miller - samm@scl.ameslab.gov

Jason Olson

Michael Ekstrand - mekstran@scl.ameslab.gov

others?

Introduction

The Bamboo library provides wire protocol communication, XML message handling, and other application support features to client applications in the SciDAC Scalable Systems Software environment.

Dependencies

The Bamboo library has several dependencies. You will need to the development headers for all these libraries.

• Expat XML parser
• PCRE regular expression library http://sourceforge.net/project/showfiles.php?group_id=10194/
• zlib http://www.zlib.net/
• OpenSSL http://www.openssl.org/

Installation

Note: assumes you obtained a Bamboo tarball, to compile from CVS you will need autoconf & friends to generate a configure script

1. ./configure
2. make
3. make install

Thread safety

When pthreads is available, BambooLib takes advantage of it to implement some basic thread safety for its classes. A couple of facilities are presently used: global mutexes and "synchronized" classes.

The threading.h header exposes a global mutex declaration macro, an exception-safe mutex locker, and the synchronized class mechanism.

Protection of various classes

The qLog and ServiceDirectory classes are synchronized and therefore thread-safe, except for their constructors and destructors.

The ConfigReader class is not protected, but that shouldn't be much of an issue except when it is to be re-read. That problem should be addressed sometime, or clients will just need to protect it themselves.

The messages, wire protocol implementations, and XML classes are unprotected. No more than 1 thread can access the same XML document at a time (reading is probably safe, but writing needs to be protected by the clien tcode). Same goes for messages and wire protocol classes.

Threading implementation

This section documents how to use BambooLib's threading support within BambooLib (and externally, if desired) to implement thread safety.

Global mutexes

To declare a global static mutex in a file (for creating critical sections), use the LIBBAMBOO_STATIC_MUTEX macro, as follows:

// some global declarations
LIBBAMBOO_STATIC_MUTEX(muxName);
// some more global declarations

This allows us to add support for more threading mechanisms in the future. To lock a mutex, instantiate the BambooLib::threading::mutex_locker class locally. It locks the mutex on creation, and unlocks it when it goes out of scope, thus creating a critical section from the declaration of the mutex_locker through the end of the scope. The critical section can be locked and unlocked, but it starts out locked.

Note that mutex_locker and global mutexes are not recursive.

Example:

{
    // some code
    mutex_locker crit(mutex);
    // some criticala code
}   // critical section ends here

Synchronized classes

Java provides a useful mechanism for thread synchronization - methods can be declared "synchronized." No more than 1 thread can be in synchronized methods of the same instance at a time. We implement a similar mechanism for C++.

To have synchronization semantics, a class must inherit from BambooLib::threading::synchronized. This inheritance can be private or protected (in fact, this is the recommended procedure). synchronized declares a proteced inner class, synchronize, that locks the instance. Its usage is much like mutex_locker, except that it takes the instance as its constructor parameter rather than a mutex. It is also a recursive lock - the same thread can lock it more than once, provided that it unlocks it as many times as it locks it.

When writing synchronized methods, it is imperative to be careful to avoid deadlocks. Synchronized code in methods on class instance A cannot call synchronized code on class instance B (of the same or different classes, it doesn't matter) unless it is guaranteed that all synchronized code pertaining to B will call no further synchronized code for other instances (including A). This restriction is probably specified a tad too strictly, but you have to be really careful. If this guideline is followed, the code should be safe.

Since a synchronize object can be locked and unlocked, it is possible to have only parts of methods synchronized.

---