thread.h

/* Copyright (c) 2005-2013, Stefan Eilemann <eile@equalizergraphics.com>
 *               2012, Marwan Abdellah <marwan.abdellah@epfl.ch>
 *               2012, Daniel Nachbaur <danielnachbaur@gmail.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 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
    {
        NONE = 0, 
        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;

    Thread& operator=( const Thread& ) { return *this; }

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

LUNCHBOX_API std::ostream& operator << ( std::ostream&, const Thread::Affinity );

// 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 )                 \
        {}                                      \
        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();

#  define LB_TS_THREAD( NAME )                                          \
    {                                                                   \
        if( NAME.id == lunchbox::ThreadID( ))                           \
        {                                                               \
            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( ))         \
        {                                                               \
            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() ||
                          data.inRegion == lunchbox::Thread::getSelfThreadID(),
                          "Another thread already in critical region" );
            data.inRegion = lunchbox::Thread::getSelfThreadID();
        }

    ~ScopedThreadCheck()
        {
            LBASSERTINFO( _data.inRegion == lunchbox::ThreadID() ||
                          _data.inRegion == lunchbox::Thread::getSelfThreadID(),
                          "Another thread entered critical region" );
            _data.inRegion = lunchbox::ThreadID();
        }
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