gthread.h

/*
 * File: gthread.h
 * ---------------
 *
 * This file contains code related to multithreading.
 * Qt requires at least two threads to run: a main Qt GUI thread,
 * and a separate student code thread.
 * The student's main() function runs in this latter student thread.
 * You can also run code in a new thread using the static method
 * GThread::runInNewThread or GThread::runInNewThreadAsync.
 *
 * @version 2021/04/09
 * - added sgl namespace
 * @version 2021/04/03
 * - removed dependency on custom collections
 * @version 2019/04/13
 * - reimplement GThread to wrap either QThread or std::thread
 * - add GThread abstract base class for thread abstractions
 * - add GThreadQt and GThreadStd subclasses
 * - rename GFunctionThread to QFunctionThread to reduce name confusion
 * - remove GStudentThread subclass and combine functionality into GThread
 * @version 2018/10/18
 * - improved thread names
 * @version 2018/09/08
 * - added doc comments for new documentation generation
 * @version 2018/08/23
 * - renamed to gthread.h to replace Java version
 * @version 2018/07/28
 * - initial version
 */

#ifndef _gthread_h
#define _gthread_h

#include <QThread>
#include <atomic>
#include <map>
#include <thread>

#include "gtypes.h"

namespace sgl {

class QtGui;

class QFunctionThread : public QThread {
public:
    QFunctionThread(GThunk func);

    QFunctionThread(GThunkInt func);

    int returnValue() const;

protected:
    void run();

private:
    Q_DISABLE_COPY(QFunctionThread)

    GThunk _func;
    GThunkInt _funcInt;
    bool _hasReturn;
    int _returnValue;
};

class GThread {
public:
    virtual int getResult() const = 0;

    virtual bool isRunning() const = 0;

    virtual void join() = 0;

    virtual bool join(unsigned long ms) = 0;

    virtual string name() const = 0;

    virtual int priority() const = 0;

    virtual void setName(const string& name) = 0;

    virtual void setPriority(int priority) = 0;

    virtual void sleep(double ms) = 0;

    virtual void start() = 0;

    virtual void stop() = 0;

    virtual void yield() = 0;

    // TODO: methods to set a top-level exception handler


    static void ensureThatThisIsTheQtGuiThread(const string& message = "");

    static GThread* getCurrentThread();

    static GThread* getQtGuiThread();

    static GThread* getStudentThread();

    static bool iAmRunningOnTheQtGuiThread();

    static bool iAmRunningOnTheStudentThread();

    static bool qtGuiThreadExists();

    static void runInNewThread(GThunk func, const string& threadName = "");

    static GThread* runInNewThreadAsync(GThunk func, const string& threadName = "");

    static void runOnQtGuiThread(GThunk func);

    static void runOnQtGuiThreadAsync(GThunk func);

    static void startStudentThread(GThunkInt mainFunc);

    static bool studentThreadExists();

    static bool wait(GThread* thread, long ms);

    static void setGuiThread();

protected:
    // forbid construction
    GThread();
    virtual ~GThread() = default;

    virtual void run() = 0;

    // member variables
    GThunk _func;
    GThunkInt _funcInt;
    bool _hasReturn;
    int _returnValue;

    // pointers to the two core library threads
    static GThread* _qtGuiThread;
    static GThread* _studentThread;

    // mapping between QThreads and their related GThread wrappings
    static std::map<QThread*, GThread*> _allGThreadsQt;
    static std::map<std::thread*, GThread*> _allGThreadsStd;

private:
    friend class QtGui;
};


class GThreadQt : public GThread {
public:
    GThreadQt(GThunk func, const string& threadName = "");

    GThreadQt(GThunkInt func, const string& threadName = "");

    GThreadQt(QThread* qthread);

    virtual ~GThreadQt() override;

    /* @inherit */
    int getResult() const override;

    /* @inherit */
    bool isRunning() const override;

    /* @inherit */
    void join() override;

    /* @inherit */
    bool join(unsigned long ms) override;

    /* @inherit */
    string name() const override;

    /* @inherit */
    int priority() const override;

    /* @inherit */
    void setName(const string& name) override;

    /* @inherit */
    void setPriority(int priority) override;

    /* @inherit */
    void sleep(double ms) override;

    /* @inherit */
    void start() override;

    /* @inherit */
    void stop() override;

    /* @inherit */
    void yield() override;

protected:
    /* @inherit */
    void run() override;

private:
    Q_DISABLE_COPY(GThreadQt)

    QThread* _qThread;   // underlying real Qt thread
};


class GThreadStd : public GThread {
public:
    GThreadStd(GThunk func, const string& threadName = "");

    GThreadStd(GThunkInt func, const string& threadName = "");

    GThreadStd(std::thread* stdThread);

    virtual ~GThreadStd() override;

    /* @inherit */
    int getResult() const override;

    /* @inherit */
    bool isRunning() const override;

    /* @inherit */
    void join() override;

    /* @inherit */
    bool join(unsigned long ms) override;

    /* @inherit */
    string name() const override;

    /* @inherit */
    int priority() const override;

    /* @inherit */
    void setName(const string& name) override;

    /* @inherit */
    void setPriority(int priority) override;

    /* @inherit */
    void sleep(double ms) override;

    /* @inherit */
    void start() override;

    /* @inherit */
    void stop() override;

    /* @inherit */
    void yield() override;

protected:
    /* @inherit */
    void run() override;

private:
    Q_DISABLE_COPY(GThreadStd)

    std::thread* _stdThread;   // underlying real std thread
    string _name;
    std::atomic<bool> _running;
};


// Platform-specific way to set the name of current thread for display in debugger
void native_set_thread_name(const char *name);

// Platform-specific way to exit current thread
[[noreturn]] void native_thread_exit();

} // namespace sgl

#endif // _gthread_h