Initial commit
This commit is contained in:
368
Include/ZUtil/ZThread.hpp
Normal file
368
Include/ZUtil/ZThread.hpp
Normal file
@@ -0,0 +1,368 @@
|
||||
/*
|
||||
ZThread.hpp
|
||||
Author : James Russell <jcrussell@762studios.com>
|
||||
Created: 07/04/09
|
||||
|
||||
Purpose :
|
||||
|
||||
Wrapper class to allow easy thread creation. By making a class that is
|
||||
a subclass of ZThread and defining the run() method, a thread 'object' can
|
||||
be created that allows for greater consistency and when dealing with thread
|
||||
resources.
|
||||
|
||||
License:
|
||||
|
||||
TODO
|
||||
*/
|
||||
|
||||
#ifndef _ZTHREAD_H
|
||||
#define _ZTHREAD_H
|
||||
|
||||
#include <ZSTL/ZList.hpp>
|
||||
#include <ZSTL/ZString.hpp>
|
||||
|
||||
#include <ZUtil/ZConcurrency.hpp>
|
||||
#include <ZUtil/ZSmartPointer.hpp>
|
||||
|
||||
class ZThread;
|
||||
typedef void (*ZThreadCallbackFunc)(ZThread* executor, void* arg);
|
||||
|
||||
/*
|
||||
Macro that creates an anonymous request object for marshalling code into a thread request.
|
||||
|
||||
Example:
|
||||
|
||||
TODO
|
||||
|
||||
@param zthread - the zthread object that should execute the request
|
||||
@param argument - the void* argument to pass in (accessible as Arg)
|
||||
@param wait - a boolean indicating if we should wait or not
|
||||
@param code - the actual code that should be executed as part of the request (wrap in parenthesis)
|
||||
*/
|
||||
#define ZTHREAD_EXECUTE(zthread, argument, wait, code) \
|
||||
{ \
|
||||
class Z##__FUNCTION__##__LINE__##ThreadRequest : public ZThreadRequest \
|
||||
{ \
|
||||
protected: \
|
||||
void *Arg; \
|
||||
public: \
|
||||
Z##__FUNCTION__##__LINE__##ThreadRequest() : ZThreadRequest(), Arg(argument) { } \
|
||||
\
|
||||
virtual void Execute(ZThread *_threadObj) \
|
||||
{ \
|
||||
code \
|
||||
} \
|
||||
}; \
|
||||
\
|
||||
zthread->AddThreadRequest(ZPtr<ZThreadRequest>(znew Z##__FUNCTION__##__LINE__##ThreadRequest), wait); \
|
||||
}
|
||||
|
||||
//Forward declaration of ZThread
|
||||
class ZThread;
|
||||
|
||||
//Possible return values from ZThread run
|
||||
typedef enum ZThreadReturn
|
||||
{
|
||||
ZTR_TERMINATE, //Indicates the thread should terminate after returning from run
|
||||
ZTR_LOOP, //Indicates the thread should loop after returning from run
|
||||
ZTR_PAUSE, //Indicates the thread should pause after returning from run
|
||||
ZTR_SIZE
|
||||
} ZThreadReturn;
|
||||
|
||||
/*
|
||||
A ZThread 'Request' object. Used for thread marshaling.
|
||||
*/
|
||||
class ZThreadRequest
|
||||
{
|
||||
friend class ZThread;
|
||||
private:
|
||||
//Completion Event
|
||||
ZEvent CompletedEvent;
|
||||
|
||||
//Indicates this 'ThreadRequest' should persist until removed
|
||||
bool Persist;
|
||||
|
||||
//Indicates to the ZThread that this request should stop running immediately
|
||||
//This value is checked before execution
|
||||
bool Stop;
|
||||
|
||||
public:
|
||||
/*
|
||||
Default Constructor.
|
||||
|
||||
@param _persist - boolean indicating this thread request should execute continuously until
|
||||
the ZThread object is deleted
|
||||
*/
|
||||
ZThreadRequest(bool _persist = false)
|
||||
: CompletedEvent(), Persist(_persist), Stop(false) { }
|
||||
|
||||
/*
|
||||
Destructor.
|
||||
|
||||
Destroys the concurrency event.
|
||||
*/
|
||||
virtual ~ZThreadRequest() { }
|
||||
|
||||
/*
|
||||
virtual public ZThreadRequest::Execute
|
||||
|
||||
Virtual method, which defines the thread request to be executed. The function will be executed
|
||||
from within the ZThread object's thread context. If this method is not overridden and Func is not
|
||||
NULL, Func is called with the provided argument.
|
||||
|
||||
@param _threadObj - the ZThread object executing this request
|
||||
|
||||
@return (void)
|
||||
*/
|
||||
virtual void Execute(ZThread *_threadObj) = 0;
|
||||
|
||||
/*
|
||||
public ZThreadRequest::StopExecution
|
||||
|
||||
Stops execution of the thread request, provided it has not executed yet.
|
||||
|
||||
@return (void)
|
||||
*/
|
||||
void StopExecution() { this->Stop = true; }
|
||||
|
||||
/*
|
||||
public ZThreadRequest::Wait
|
||||
|
||||
Blocks until after the thread request has been executed.
|
||||
|
||||
@return (void)
|
||||
*/
|
||||
void Wait() { CompletedEvent.Wait(); }
|
||||
};
|
||||
|
||||
/*
|
||||
ZThread object class. Should be subclassed to make a threadable 'object'.
|
||||
*/
|
||||
class ZThread
|
||||
{
|
||||
private:
|
||||
DISABLE_COPY_AND_ASSIGN(ZThread);
|
||||
|
||||
public:
|
||||
/*
|
||||
Default Constructor.
|
||||
|
||||
@param _threadName - the name of this thread
|
||||
*/
|
||||
ZThread(ZString _threadName = "");
|
||||
|
||||
/*
|
||||
Destructor for the ZThread Object. When the ZThread object is deleted, the destructor will wait on
|
||||
the thread to terminate and return resources to the system.
|
||||
*/
|
||||
virtual ~ZThread();
|
||||
|
||||
/*
|
||||
public ZThread::AddThreadRequest()
|
||||
|
||||
Adds a callback that will be executed when the thread loops.
|
||||
|
||||
@param _request - the thread request to add to the thread's context
|
||||
|
||||
@return (void)
|
||||
*/
|
||||
void AddThreadRequest(ZPtr<ZThreadRequest> _request, bool _wait = false);
|
||||
|
||||
/*
|
||||
public ZThread::AddCallbackRequest()
|
||||
|
||||
Adds a callback to be executed by the thread. It can be executed synchronously or asynchronously.
|
||||
|
||||
@param function - The function to execute
|
||||
@param arg - The argument
|
||||
@param async - If true, this returns immediately, otherwise it waits for the function to execute.
|
||||
|
||||
@return (void)
|
||||
*/
|
||||
void AddCallbackRequest(ZThreadCallbackFunc function, void* arg, bool async);
|
||||
|
||||
/*
|
||||
public ZThread::GetThreadID
|
||||
|
||||
Gets the thread ID of the thread object.
|
||||
|
||||
@return (uint32_t) - int that is the thread id of the thread object
|
||||
*/
|
||||
uint32_t GetThreadId();
|
||||
|
||||
/*
|
||||
public ZThread::GetThreadName
|
||||
|
||||
Gets the thread name of the ZThread object. The name of a thread is either a
|
||||
string value of the thread id or a name that was set by the ZThread object.
|
||||
|
||||
@return (ZString) - string representing the 'name' of this thread
|
||||
*/
|
||||
ZString GetThreadName();
|
||||
|
||||
/*
|
||||
public ZThread::PauseThread
|
||||
|
||||
Tells the user thread to pause.
|
||||
|
||||
@return (void)
|
||||
*/
|
||||
void PauseThread();
|
||||
|
||||
/*
|
||||
public ZThread::RestartThread
|
||||
|
||||
Restarts a paused thread.
|
||||
|
||||
@return (void)
|
||||
*/
|
||||
void RestartThread();
|
||||
|
||||
/*
|
||||
public ZThread::ThreadRunning
|
||||
|
||||
Indicates if a ZThread object is executing it's run method or is paused.
|
||||
|
||||
@return (bool) - boolean indicating thread is running or is paused
|
||||
*/
|
||||
bool ThreadRunning();
|
||||
|
||||
/*
|
||||
public ZThread::ThreadInitialized
|
||||
|
||||
Returns true if the ZThread object has called it's initThread() method and returned.
|
||||
|
||||
@return (bool) - boolean indicating the thread is initialized
|
||||
*/
|
||||
bool ThreadInitialized();
|
||||
|
||||
/*
|
||||
public ZThread::ShutdownThread
|
||||
|
||||
Tells the user thread to shutdown. Blocks until it happens.
|
||||
|
||||
@return (void)
|
||||
*/
|
||||
void ShutdownThread();
|
||||
|
||||
/*
|
||||
public ZThread::StartThread
|
||||
|
||||
When StartThread is called on a class that extends ZThread, a thread will be created
|
||||
that will call the run() function implemented by the subclass.
|
||||
|
||||
@return (bool) - boolean indicating the thread has started successfully
|
||||
*/
|
||||
bool StartThread();
|
||||
|
||||
/*
|
||||
public ZThread::WaitInitialized
|
||||
|
||||
Caller waits until the ZThread has initialized.
|
||||
|
||||
@return (void)
|
||||
@context (all)
|
||||
*/
|
||||
void WaitInitialized();
|
||||
|
||||
/*
|
||||
public ZThread::WaitShutdown
|
||||
|
||||
Caller waits until the ZThread has shutdown.
|
||||
|
||||
@return (void)
|
||||
@context (all)
|
||||
*/
|
||||
void WaitShutdown();
|
||||
|
||||
protected:
|
||||
//Thread 'name' of this thread
|
||||
ZString ThreadName;
|
||||
|
||||
//Boolean field which, when set to true, indicates the thread should terminate.
|
||||
bool bShouldShutdown;
|
||||
|
||||
//Boolean field which, when set to true, indicates the thread should pause.
|
||||
bool bShouldPause;
|
||||
|
||||
/*
|
||||
This is a wrapper around the user run() method, which calls that method in a loop, executing
|
||||
thread requests and setting the condition variables appropriately.
|
||||
*/
|
||||
void Run();
|
||||
|
||||
/*
|
||||
Executes the thread requests that may be pending at the time it is called by the subclass.
|
||||
*/
|
||||
void ExecuteThreadRequests();
|
||||
|
||||
/*
|
||||
Initialization method which is called when the thread starts. Does not have to be overridden, but any
|
||||
thread specific initialization that must be done in the thread context of the ZThread object needs
|
||||
to be defined here.
|
||||
*/
|
||||
virtual void initThread() { }
|
||||
|
||||
/*
|
||||
Shutdown method which is called when the thread terminates. Does not have to be overridden, but any
|
||||
thread specific shutdown requirements that must be done in the thread context of the ZThread object
|
||||
needs to be defined here.
|
||||
*/
|
||||
virtual void shutdownThread() { }
|
||||
|
||||
/*
|
||||
This method must be implemented by the ZThread subclass. This is the 'main' function of execution for
|
||||
the newly created thread.
|
||||
|
||||
@param _dt - the time (in ms) since last time run was called
|
||||
@return - a ZTHREAD_RETURN value indicating whether the thread should run once (ZTR_TERMINATE),
|
||||
loop (ZTR_RETURN), or pause (ZTR_PAUSE).
|
||||
*/
|
||||
virtual ZThreadReturn run(uint64_t _dt) = 0;
|
||||
|
||||
bool IsCallerTheThread();
|
||||
private:
|
||||
struct ZThreadCallbackRequest {
|
||||
ZThreadCallbackFunc callback;
|
||||
void* arg;
|
||||
SST_Event doneEvent;
|
||||
};
|
||||
|
||||
|
||||
|
||||
//Thread context of this thread
|
||||
ZThreadContext ThreadContext;
|
||||
|
||||
//The mutex for use by this thread object for handling thread marshaling.
|
||||
ZMutex ThreadLock;
|
||||
|
||||
//The event signaled when the thread has finished initializing
|
||||
ZEvent InitEvent;
|
||||
|
||||
//Previous tick count for this thread object
|
||||
uint64_t PreviousTickCount;
|
||||
|
||||
//Current tick count for this thread object
|
||||
uint64_t CurrentTickCount;
|
||||
|
||||
//Boolean field which, when set to true, indicates the thread is initialized and running.
|
||||
bool bIsRunning;
|
||||
|
||||
//Boolean field which, when set to true, indicates the thread has called and returned from initThread()
|
||||
bool bIsInitialized;
|
||||
|
||||
//List of callbacks that will occur when the ZThread object runs.
|
||||
ZList< ZPtr<ZThreadRequest> > ZTRCallbacks; // ZTR callbacks
|
||||
ZList< ZThreadCallbackRequest > Callbacks; // Simple (non-object) callbacks
|
||||
|
||||
/*
|
||||
Proxy method called by StartThread() which will call initThread and Run on the ZThread Object.
|
||||
|
||||
@param _runnable - a pointer to the ZThread object to run
|
||||
@return - integer condition (not used)
|
||||
*/
|
||||
static int InitThread(void *_runnable);
|
||||
};
|
||||
|
||||
#endif
|
||||
|
||||
Reference in New Issue
Block a user