thread.h

/* Copyright (c) 2005-2009, Stefan Eilemann <eile@equalizergraphics.com> 
 *
 * This library is free software; you can redistribute it and/or modify it under
 * the terms of the GNU Lesser General Public License version 2.1 as published
 * by the Free Software Foundation.
 *  
 * 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.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 */

#ifndef EQBASE_THREAD_H
#define EQBASE_THREAD_H

#include <eq/base/base.h>     // EQ_EXPORT definition
#include <eq/base/lock.h>     // member

#ifdef EQ_WIN32_SDP_JOIN_WAR
#  include <eq/base/monitor.h> // member
#endif

#include <vector>
#include <typeinfo>
#include <sstream>

namespace eq
{
namespace base
{
    class ExecutionListener;
    class ThreadPrivate;

    class Thread 
    {
    public:
        EQ_EXPORT Thread();

        EQ_EXPORT virtual ~Thread();

        EQ_EXPORT bool start();

        virtual bool init(){ return true; }

        virtual void* run() = 0;

        EQ_EXPORT virtual void exit( void* retVal = 0 );

        EQ_EXPORT void cancel();

        EQ_EXPORT bool join( void** retVal=0 );

        bool isStopped() const { return ( _state == STATE_STOPPED ); }

        bool isRunning() const { return ( _state == STATE_RUNNING ); }

        EQ_EXPORT bool isCurrent() const;

        EQ_EXPORT static void addListener( ExecutionListener* listener );

        EQ_EXPORT static bool removeListener( ExecutionListener* listener );

        EQ_EXPORT static void removeAllListeners();

        EQ_EXPORT static size_t getSelfThreadID();

        static void pinCurrentThread();

    private:
        ThreadPrivate* _data;
        enum State
        {
            STATE_STOPPED,
            STATE_STARTING, // start() in progress
            STATE_RUNNING,
            STATE_STOPPING  // child no longer active, join() not yet called
        };

        State _state;
        Lock  _syncChild;

#ifdef EQ_WIN32_SDP_JOIN_WAR
        Monitor<bool> _running;
        void*         _retVal;
#endif

        static void* runChild( void* arg );
        void        _runChild();

        void _installCleanupHandler();

        static void _notifyStarted();
        static void _notifyStopping();
        friend void _notifyStopping( void* ); 

        friend std::ostream& operator << ( std::ostream& os, const Thread* );
    };

    std::ostream& operator << ( std::ostream& os, const Thread* thread );

// thread-safety checks
// These checks are for development purposes, to check that certain objects are
// properly used within the framework. Leaving them enabled during application
// development may cause false positives, e.g., when threadsafety is ensured
// outside of the objects by the application.

#define CHECK_THREAD_DECLARE( NAME )                        \
    struct NAME ## Struct                                   \
    {                                                       \
        NAME ## Struct ()                                   \
            : id( 0 ), extMutex( false )                    \
            {}                                              \
        mutable size_t id;                                  \
        bool extMutex;                                      \
    } NAME;                                                 \

#ifdef EQ_CHECK_THREADSAFETY
#  define CHECK_THREAD_RESET( NAME ) NAME.id = 0;

#  define CHECK_THREAD( NAME )                                          \
    {                                                                   \
        if( NAME.id == 0 )                                              \
        {                                                               \
            NAME.id = eq::base::Thread::getSelfThreadID();                \
            EQVERB << "Functions for " << #NAME                         \
                   << " locked to this thread" << std::endl;            \
        }                                                               \
        if( !NAME.extMutex && NAME.id != eq::base::Thread::getSelfThreadID( )) \
        {                                                               \
            EQERROR << "Threadsafety check for " << #NAME               \
                    << " failed on object of type "                     \
                    << typeid(*this).name() << std::endl;               \
            EQABORT( "Non-threadsave code called from two threads" );   \
        }                                                               \
    }

#  define CHECK_NOT_THREAD( NAME )                                      \
    {                                                                   \
        if( !NAME.extMutex && NAME.id != 0 )                           \
        {                                                               \
            if( NAME.id ==  eq::base::Thread::getSelfThreadID( ))         \
            {                                                           \
                EQERROR << "Threadsafety check for not " << #NAME       \
                        << " failed on object of type "                 \
                        << typeid(*this).name() << std::endl;           \
                EQABORT( "Code called from wrong thread" );             \
            }                                                           \
        }                                                               \
    }
#else
#  define CHECK_THREAD_RESET( NAME )
#  define CHECK_THREAD( NAME )
#  define CHECK_NOT_THREAD( NAME )
#endif

}
}
#endif //EQBASE_THREAD_H