thread.h

/* Copyright (c) 2005-2012, Stefan Eilemann <eile@equalizergraphics.com>
 *               2012, Marwan Abdellah <marwan.abdellah@epfl.ch>
 *
 * 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 LUNCHBOX_THREAD_H
#define LUNCHBOX_THREAD_H

#include <lunchbox/api.h>         // LUNCHBOX_API definition
#include <lunchbox/debug.h>       // debug macros in thread-safety checks
#include <lunchbox/nonCopyable.h> // base class
#include <lunchbox/threadID.h>    // member
#include <lunchbox/types.h>

#include <ostream>

namespace lunchbox
{
namespace detail { class Thread; }

    class Thread
    {
    public:
        enum Affinity
        {
            CORE = 1, 
            SOCKET = -65536, 
            SOCKET_MAX = -1024 
        };

        LUNCHBOX_API Thread();

        LUNCHBOX_API Thread( const Thread& from );

        LUNCHBOX_API virtual ~Thread();

        LUNCHBOX_API virtual bool start();

        virtual bool init(){ return true; }

        virtual void run() = 0;

        LUNCHBOX_API virtual void exit();

        LUNCHBOX_API void cancel();

        LUNCHBOX_API bool join();

        LUNCHBOX_API bool isStopped() const;

        LUNCHBOX_API bool isRunning() const;

        LUNCHBOX_API bool isCurrent() const;

        LUNCHBOX_API static ThreadID getSelfThreadID();

        LUNCHBOX_API static void yield();

        static void pinCurrentThread();

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

        LUNCHBOX_API static void setAffinity( const int32_t affinity );

    private:
        detail::Thread* const _impl;

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

        void _installCleanupHandler();

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

// 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 LB_CHECK_THREADSAFETY
#endif

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

#ifdef LB_CHECK_THREADSAFETY
#  define LB_TS_RESET( NAME ) NAME.id = lunchbox::ThreadID::ZERO;

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

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

    template< typename T > class ScopedThreadCheck : public NonCopyable
    {
    public:
        explicit ScopedThreadCheck( const T& data )
                : _data( data )
        {
            LBASSERTINFO( data.inRegion == lunchbox::ThreadID::ZERO ||
                          data.inRegion == lunchbox::Thread::getSelfThreadID(),
                          "Another thread already in critical region" );
            data.inRegion = lunchbox::Thread::getSelfThreadID();
        }

        ~ScopedThreadCheck()
        {
            LBASSERTINFO( _data.inRegion == lunchbox::ThreadID::ZERO ||
                          _data.inRegion == lunchbox::Thread::getSelfThreadID(),
                          "Another thread entered critical region" );
            _data.inRegion = lunchbox::ThreadID::ZERO;
        }
    private:
        const T& _data;
    };
# define LB_TS_SCOPED( NAME ) \
    lunchbox::ScopedThreadCheck< NAME ## Struct > scoped ## NAME ## Check(NAME);

#else
#  define LB_TS_RESET( NAME ) {}
#  define LB_TS_THREAD( NAME ) {}
#  define LB_TS_NOT_THREAD( NAME ) {}
#  define LB_TS_SCOPED( NAME ) {}
#endif

}
#endif //LUNCHBOX_THREAD_H