thread.h

/* Copyright (c) 2005-2014, 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/threadID.h> // member
#include <lunchbox/types.h>

#include <boost/noncopyable.hpp>
#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 explicit 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();

    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 friend void abort(bool);
    static void _dumpAll();
};

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

// These thread-safety 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 from"             \
                   << lunchbox::backtrace << 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-threadsafe 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 boost::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