Threaded API Documentation

Version-0.6

Revision History

Version	Notes
0.1	Initial version, contains support for Windows mutex object
0.2	Added initial version of Posix mutex. Made MutexFactory's ctor/dtor protected to avoid compiler warning on GCC.
0.3	Separated this from LoggingControl project/solution and made Threaded a DLL on its own. Added LIB_API symbols which can help build this as a DLL.
0.4	Added ThreadBase, SimpleThread, factory method for SimpleThread and internal ThreadImpl classes for implementing threads in an application.
0.41	Added Doxygen tags to the source
0.5	Added MutexLock, 2004-02-10
0.6	Added IMutex::TryLock(), 2004-02-18

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Introduction

This is a homegrown attempt to develop a library that will support various multithreading artifacts on multiple platforms by wrapping up platform-specific API calls. I will be adding features to this library as I need them, thus it will probably remain sparse for quite some time. Note also that this library will probably always be limited to functionality that can be commonized across platforms.

DISCLAIMERS: 1) Yes, I am aware of Boost.Threads. This library is a completely separate effort undertaken for my education and edification only. I do not pretend that this library is anywhere as efficient, robust or powerful as Boost.Threads. 2) This library is provided AS IS and without any warranty implied or otherwise. I am publishing this library for review purposes only.

At this time, I am only supporting Win32 and Posix.

The library is completely contained within the Threaded namespace.

At this time, the library supports two basic features: Synchronization Objects and Threads.

Synchronization Objects

Synchronization objects enable threads to manage safe access to resources.

The simplest synchronization object is the simple Mutex, which stands for MUTual EXclusion. The library supports the creation of mutexes through a singleton factory object (Threaded::ThreadedFactory) by calling the factory method CreateMutex() . This method returns a pointer to an object of base type Threaded::IMutex. Once the IMutex object is no longer needed, make sure you delete the object to avoid a memory leak.

Threaded::IMutex supports two simple operations: Lock and Release. A thread calls Lock() when it requires access to a particular resource and can wait indefinitely. A thread calls TryLock() when it requires access to a particular resource and will only wait a specified time. A thread calls Release() when it no longer requires access to a particular resource. If another thread currently has the mutex object locked, the call to Lock() will block until the mutex has been released and a call to TryLock(timeout) will only wait timeout milliseconds.

Sometimes the user may want to make an operation atomic. To do something like this, see the following code:

    class MyClass {
                IMutex* m_pMutex;
    public:
                MyClass() : m_pMutex(Threaded::ThreadedFactory::CreateMutex()) {}
                ~MyClass() { delete m_pMutex; }
                
                void MyAtomicFunction() {
                        m_pMutex->Lock();
                        // do something...
                        m_pMutex->Release();
                }
    };

Having to Lock and then remember to Release a mutex object for every monatomic operation can be tedious and error-prone. Thus, as a convenience, the Threaded library provides a helper class to ease such an operation called MutexLock. MutexLock can only be created with a valid instance of a mutex pointer and automatically locks the mutex upon creation. Upon destruction the MutexLock automatically releases the mutex. This concept is also sometimes called a "Guard".

Thus, the code for MyAtomicFunction() would be reduced to:

                void MyAtomicFunction() {
                        Threaded::MutexLock lock(m_pMutex);
                        // do something...
                } // at end of function, lock is automatically destroyed

A MutexLock internally uses the Lock() method (not the TryLock() method) on the IMutex object.

Threads

A thread can be thought of as a single line of execution. An application can have only one thread (i.e. the thread that invokes the main() function) or multiple threads, depending on its requirements.

The library supports the thread concept in two ways.

First, an application can derive its own C++ objects from the class Threaded::ThreadBase. The ThreadBase class provides a Start() method, which is called to start the thread. The only requirement is that the derived class must implement a virtual Run() method that accepts no arguments and returns a value of type void*.

The ThreadBase object supports calls to determine if the thread has started (hasStarted() ) and has finished (hasFinished() ). The hasFinished() method accepts an output argument to retrieve the return value of the Run() method.

Second, an application can create simple threads to run global or static functions. The library supports the creation of SimpleThread objects (derived from ThreadBase) through a singleton factory object (ThreadedFactory ) by calling the factory method CreateSimpleThread() . This method returns a pointer to an object of type SimpleThread. Once the SimpleThread object is no longer needed, make sure you delete the object to avoid a memory leak.

Generated on Wed Feb 18 19:56:34 2004 for Threaded by

1.3.5