vthread.h

Go to the documentation of this file.

/*
Copyright c1997-2014 Trygve Isaacson. All rights reserved.
This file is part of the Code Vault version 4.1
http://www.bombaydigital.com/
License: MIT. See LICENSE.md in the Vault top level directory.
*/

#ifndef vthread_h
#define vthread_h

#include "vthread_platform.h"

#include "vstring.h"
#include "vmutex.h"
#include "vlogger.h"

class VDuration;
class VManagementInterface;
class VBentoNode;

class VThread {
    public:

        /*
        The following three static functions are to be implemented in your client application
        code. The APIs are defined here and are called when needed, and you just have to
        implement them to do what's needed depending on what you have available.
        */
        static int userMain(int argc, char** argv);
        static void* userThreadMain(void* arg);
        static void logStackCrawl(const VString& headerMessage, VNamedLoggerPtr logger, bool verbose);

        // Constants to pass for VThread constructor deleteSelfAtEnd parameter:
        static const bool kDeleteSelfAtEnd = true;      
        static const bool kDontDeleteSelfAtEnd = false; 

        // Constants to pass for VThread constructor createDetached parameter:
        static const bool kCreateThreadDetached = true;     
        static const bool kCreateThreadJoinable = false;    

        VThread(const VString& name, const VString& loggerName, bool deleteSelfAtEnd, bool createDetached, VManagementInterface* manager);
        virtual ~VThread();

        virtual void start();
        virtual void stop();
        virtual void run() = 0;

        VThreadID_Type threadID() const;
        bool isRunning() const;
        bool join();
        bool getDeleteAtEnd() const;
        VManagementInterface* getManagementInterface() const;

        const VString& getName() const { return mName; }
        void setName(const VString& threadName) { mName = threadName; }
        const VString& getLoggerName() const { return mLoggerName; }

        static void* threadMain(void* arg);

        static void getThreadsInfo(VBentoNode& bento);

        static VString getThreadName(VThreadID_Type threadID);

        static void stopThread(VThreadID_Type threadID);

        /* PLATFORM-SPECIFIC STATIC FUNCTIONS --------------------------------
        The remaining functions defined here are the low-level interfaces to
        the platform-specific threading APIs. These are implemented in each
        platform-specific version of vthread_platform.cpp.
        */

        typedef void*(*threadMainFunction)(void* param);

        static void threadCreate(VThreadID_Type* threadID, bool createDetached, threadMainFunction threadMainProcPtr, void* threadArgument);

        static void threadExit();

        static bool threadJoin(VThreadID_Type threadID, void** value);

        static void threadDetach(VThreadID_Type threadID);

        static VThreadID_Type threadSelf();

        static VThread* getCurrentThread();

        static VString getCurrentThreadName();

        static bool setPriority(int nice);

        static void sleep(const VDuration& interval);

        static void yield();

    protected:

        bool                    mIsDeleted;         
        VString                 mName;              
        VString                 mLoggerName;        
        bool                    mDeleteAtEnd;       
        bool                    mCreateDetached;    
        VManagementInterface*   mManager;           
        VThreadID_Type          mThreadID;          
        volatile bool           mIsRunning;         

    private:

        // Prevent copy construction and assignment since there is no provision for sharing the underlying thread.
        VThread(const VThread& other);
        VThread& operator=(const VThread& other);

        // These two function are implemented in the platform-specific code to perform any
        // necessary per-thread bookkeeping. They are called from VThread::threadMain() just
        // before and after the corresponding VManagementInterface threadStarting() and
        // threadEnded() calls.
        static void _threadStarting(const VThread* thread);
        static void _threadEnded(const VThread* thread);
};

class VMainThread : public VThread {
    public:
        VMainThread();
        virtual ~VMainThread();

        virtual void start();
        virtual void run() {} // Will never be called because start() throws.

        int execute(int argc, char** argv);
};

class VForeignThread : public VThread {
    public:
        VForeignThread(const VString& name);
        virtual ~VForeignThread();

        virtual void start();
        virtual void run() {} // Will never be called because start() throws.
};

#endif /* vthread_h */