thread.h

/* Copyright (c) 2005-2011, 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 COBASE_THREAD_H
#define COBASE_THREAD_H

#include <co/base/api.h>      // COBASE_API definition
#include <co/base/debug.h>    // debug macros in thread-safety checks
#include <co/base/lock.h>     // member
#include <co/base/monitor.h>  // member
#include <co/base/threadID.h> // member

#include <ostream>

namespace co
{
namespace base
{
    class ExecutionListener;

    class Thread 
    {
    public:
        COBASE_API Thread();

        COBASE_API virtual ~Thread();

        COBASE_API bool start();

        virtual bool init(){ return true; }

        virtual void run() = 0;

        COBASE_API virtual void exit();

        COBASE_API void cancel();

        COBASE_API bool join();

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

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

        COBASE_API bool isCurrent() const;

        COBASE_API static void addListener( ExecutionListener* listener );

        COBASE_API static bool removeListener( ExecutionListener* listener );

        COBASE_API static void removeAllListeners();

        COBASE_API static ThreadID getSelfThreadID();

        COBASE_API void untrack();

        COBASE_API static void yield();

        static void pinCurrentThread();

        COBASE_API static void setName( const std::string& name );

    private:
        ThreadID _id;

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

        Monitor< State > _state;

        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.

#ifndef NDEBUG
#  define EQ_CHECK_THREADSAFETY
#endif

#define EQ_TS_VAR( NAME )                                   \
public:                                                     \
    struct NAME ## Struct                                   \
    {                                                       \
        NAME ## Struct ()                                   \
            : extMutex( false ), inRegion( false )          \
            {}                                              \
        mutable co::base::ThreadID id;                      \
        mutable std::string name;                           \
        bool extMutex;                                      \
        mutable bool inRegion;                              \
    } NAME;                                                 \
private:

#ifdef EQ_CHECK_THREADSAFETY
#  define EQ_TS_RESET( NAME ) NAME.id = co::base::ThreadID::ZERO; 

#  define EQ_TS_THREAD( NAME )                                          \
    {                                                                   \
        if( NAME.id == co::base::ThreadID::ZERO )                       \
        {                                                               \
            NAME.id = co::base::Thread::getSelfThreadID();              \
            NAME.name = co::base::Log::instance().getThreadName();      \
            EQVERB << "Functions for " << #NAME                         \
                   << " locked to this thread" << std::endl;            \
        }                                                               \
        if( !NAME.extMutex && NAME.id != co::base::Thread::getSelfThreadID( )) \
        {                                                               \
            EQERROR << "Threadsafety check for " << #NAME               \
                    << " failed on object of type "                     \
                    << co::base::className( this ) << ", thread "       \
                    << co::base::Thread::getSelfThreadID() << " ("      \
                    << co::base::Log::instance().getThreadName() << ") != " \
                    << NAME.id << " (" << NAME.name << ")" << std::endl; \
            EQABORT( "Non-threadsave code called from two threads" );   \
        }                                                               \
    }

#  define EQ_TS_NOT_THREAD( NAME )                                      \
    {                                                                   \
        if( !NAME.extMutex && NAME.id != co::base::ThreadID::ZERO )     \
        {                                                               \
            if( NAME.id == co::base::Thread::getSelfThreadID( ))        \
            {                                                           \
                EQERROR << "Threadsafety check for not " << #NAME       \
                        << " failed on object of type "                 \
                        << co::base::className( this ) << std::endl;    \
                EQABORT( "Code called from wrong thread" );             \
            }                                                           \
        }                                                               \
    }

    template< typename T > class ScopedThreadCheck : public NonCopyable
    {
    public:
        explicit ScopedThreadCheck( const T& data )
                : _data( data )
            {
                EQASSERTINFO( !data.inRegion,
                              "Another thread already in critical region" );
                data.inRegion = true;
            }
        ~ScopedThreadCheck() 
            {
                EQASSERTINFO( _data.inRegion,
                              "Another thread was in critical region" );
                _data.inRegion = false;
            }
    private:
        const T& _data;
    };
# define EQ_TS_SCOPED( NAME ) \
    co::base::ScopedThreadCheck< NAME ## Struct > scoped ## NAME ## Check(NAME);

#else
#  define EQ_TS_RESET( NAME ) {}
#  define EQ_TS_THREAD( NAME ) {}
#  define EQ_TS_NOT_THREAD( NAME ) {}
#  define EQ_TS_SCOPED( NAME ) {}
#endif

}
}
#endif //COBASE_THREAD_H