smtpthread/Thread.h

// DOCUMENT:  Thread-Class
// VERSION:   $Revision: 1.5 $
// DATE:      $Date: 2007-10-26 23:09:19 $
// AUTHOR:    M.Beranek
// COPYRIGHT: M.Beranek

#ifndef _THREAD_H
#define _THREAD_H

#include <pthread.h>

namespace SmtpThread
{
    /**
     * Thread-Class.
     *
     * This abstract class wraps a class around a threading function.
     *
     * Threading is startet through calling 'Start', which sets
     * the protected member-variable '_isRunning'. The state of
     * the thread can be checked with the member-function
     * 'isRunning'.
     *
     * You must overwrite the method 'Execute' to do
     * something usefull within the thread.
     *
     * 'Execute' should be constructed as an endless loop like:
     *
     * <code>
     * void InheritedClassname::Execute( void * arg )<br>
     * {<br>
     *   while( _isRunning )<br>
     *   {<br>
     *     // do something...<br>
     *   }<br>
     * }<br>
     * </code>
     *
     * When 'Start' is called, it starts the thread and executes
     * 'Setup' and 'Execute'.
     *
     * To stop threading, simply call 'Stop'.
     */
    class Thread
    {
    public:
        
        /**
         * Constructor.
         */
        Thread();
        
        /**
         * Destructor.
         *
         * NOTE: Under normal conditions I would use a purely virtual
         * destructor. But unfortunately most people (me too) often forget
         * to call the 'Stop' member-function in the destructor of the
         * derived classes.
         *
         * So calling delete on an object, which still has a running
         * thread, may not behave well, especially when the destructor
         * removes members of the object, while the thread is trying to
         * access them.
         *
         * So, I implemented a non-virtual destructor, which stops
         * threading, when the thread is still running. This will cause
         * most compilers to issue a warning, but it seems to be the
         * easiest way, to get your code working... ;)
         *
         */
        ~Thread();
        
        /**
         * Start threading.
         * @param void* arg typeless argument.
         * @return int exit-code of 'pthread_create'
         */
        int Start(void* arg);
        
        /**
         * Returns the thread-id.
         * @return pthread_t thread-id
         */
        pthread_t getThreadId();
        
        /**
         * Checks, whether or not the thread is running.
         * @return bool true / false = running / not running
         */
        bool isRunning();
        
        /**
         * Stop threading.
         */
        void Stop();
        
        
    protected:
        
        /**
         * Gets called immediatly after "EntryPoint".
         * Calls "Setup" and "Execute".
         * @param void* arg typeless argument.
         */
        int Run(void * arg);
        
        /**
         * This is the entrypoint for threading.
         * This function must be declared as "static", because the pthread-library
         * expects a normal C-type-function as an entrypoint.
         *
         * Parameters are passed as pointer to void and are the same as passed
         * to "Start".
         *
         * @param void* arg typeless argument.
         */
        static void * EntryPoint( void * );
        
        /**
         * Initializes some thread-variables and sets up a mutex.
         * The mutex can be accessed through the member-varaible
         * "_mutex".
         */
        virtual void Setup();
        
        /**
         * The main threading-functionality goes here.
         * You should create an endless loop like:
         *
         * <code>
         * while( _isRunning)
         * {
         *   // do something usefull...
         * }
         * </code>
         *
         * Parameters are passed as pointer to void and are the same as passed
         * to "Start".
         *
         * @param void* arg typeless argument.
         */
        virtual void Execute( void * );
        
        /**
         * Helper to initialize the parameters provided to "Start".
         */
        void * Arg() const
        {
            return _arg;
        }
        
        /**
         * Initiallizes the parameters passed to "Start".
         *
         * @param void* a typeless argument.
         */
        void Arg( void * a )
        {
            _arg = a;
        }
        
        /** Wether or not the thread is running. */
        bool _isRunning;
        
        /** Mutex. */
        pthread_mutex_t _mutex;
        
        /**
         * Locks the mutex "_mutex".
         *
         * NOTE: Use with care, cause it might get you a deadlock!
         *
         * @see Thread::releaseLock
         */
        void getLock();
        
        /**
         * Unlocks the mutex "_mutex".
         *
         * @see Thread::getLock
         */
        void releaseLock();
        
        
    private:
        
        /** Thread-ID. */
        pthread_t _ThreadId;
        
        /** Parameters passed to "Start", */
        void * _arg;
        
        
    };
    
}

#endif  /* _THREAD_H */

---