Main Page Modules Namespace List Class Hierarchy Alphabetical List Compound List File List Namespace Members Compound Members File Members Related Pages

# deThread.hpp

Go to the documentation of this file.

    00001 ///////////////////////////////////////////////////////////////////////////////
    00002 /// @file deThread.hpp
    00003 ///
    00004 /// @brief base header for threads
    00005 ///
    00006 /// @author Washu
    00007 ///
    00008 /// This file is the intellectual property of Novus Delta, LLC.. Usage of the
    00009 /// contents of this file is subject to the Destiny3D Member License which
    00010 /// can be found at http://www.destiny3d.com.  Any other usage is prohibited.
    00011 ///
    00012 /// This file is distributed "AS IS" without warranty of any kind.  Novus
    00013 /// Delta, LLC. does not guarantee the fitness of the contents of this file
    00014 /// for any particular purpose.
    00015 ///
    00016 /// Copyright (C) 2001-2003 Novus Delta, LLC. All Rights Reserved.
    00017 ///
    00018 /// <hr>
    00019 ///                                 Change History
    00020 /// <hr>
    00021 ///
    00022 /// @date Jul 2004
    00023 /// @author Washu
    00024 /// @remarks Initial Creation
    00025 ///////////////////////////////////////////////////////////////////////////////
    00026
    00027 #ifndef DETHREAD_HPP
    00028 #define DETHREAD_HPP
    00029
    00030 #include "deGlobalTypes.hpp"
    00031
    00032 #if defined(DEUTIL_DLL_EXPORTS) || defined(DESTINY3D_EXPORT_ALL)
    00033 #   define DETHREAD_API extern "C" DEDLL_EXPORT
    00034 #elif defined(DESTINY3D_STATIC_LINK)
    00035 #   define DETHREAD_API extern "C"
    00036 #else
    00037 #   define DETHREAD_API extern "C" DEDLL_IMPORT
    00038 #endif
    00039
    00040 #ifdef USING_DESTINY3D
    00041 #ifdef _DEBUG
    00042 #   ifdef DESTINY3D_STATIC_LINK
    00043 #       pragma comment(lib, "deUtil_sd")
    00044 #   else
    00045 #       pragma comment(lib, "deUtild")
    00046 #   endif //DESTINY3D_STATIC_LINK
    00047 #else
    00048 #   ifdef DESTINY3D_STATIC_LINK
    00049 #       pragma comment(lib, "deUtil_s")
    00050 #   else
    00051 #       pragma comment(lib, "deUtil")
    00052 #   endif //DESTINY3D_STATIC_LINK
    00053 #endif //_DEBUG
    00054 #endif //USING_DESTINY3D
    00055
    00056 class IdeThread;
    00057 class IdeThreadLock;
    00058
    00059 /// Thread encapsulation structure.
    00060 DE3D_INTERFACE_(IdeThread)
    00061 {
    00062 public:
    00063     /// ThreadProc is the function signature for thread execution routines.
    00064     typedef u32 (*ThreadProc)(void*);
    00065     typedef void (*MessageHandler)(void);
    00066
    00067     /// Begin execution of the associated routine, passing in the specified parameter.
    00068     /// This method can fail if a thread is already running or if the operating system cannot start the routine.
    00069     /// @param parameter Value to pass into the thread execution routine.
    00070     /// @return deTRUE if thread was started successfully, deFALSE on failure.
    00071     virtual deBoolean Start(void* parameter) = 0;
    00072     /// Test whether the thread is executing.
    00073     virtual deBoolean IsRunning() = 0;
    00074     /// Retrieves the value returned by the thread execution routine.
    00075     /// Note: if the thread has not been started or has not completed, the return value
    00076     ///   is undefined.
    00077     /// @param waitForExit Causes the querying thread to block until the queried thread terminates.
    00078     /// @return The value returned by the associated ThreadProc.
    00079     virtual u32 GetReturnValue(deBoolean waitForExit = deTRUE) = 0;
    00080     /// Releases & destroys a thread. This will block until the thread completes execution.
    00081     /// Note that the block would cause a deadlock if called from the thread being contained,
    00082     ///   so such a call will fail - the thread must be released from within another thread.
    00083     virtual s32 Release() = 0;
    00084     /// Wait for the target thread to finish executing, with an optional message-handler callback.
    00085     /// If the system receives any signals for this thread while waiting for the target thread
    00086     ///   to terminate, the message handler will be executed.
    00087     /// @param handler a callback to be called when any system events arrive for the calling thread.
    00088     virtual void Join(MessageHandler handler) = 0;
    00089 protected:
    00090     virtual ~IdeThread() {}
    00091 };
    00092
    00093 /// Thread synchronization handler.
    00094 DE3D_INTERFACE_(IdeThreadLock)
    00095 {
    00096 public:
    00097     /// Acquires an exclusive lock in the currently executing thread.
    00098     /// This method will block until other threads relinquish the lock.
    00099     /// Each Lock or successful TryLock call must be paired with an Unlock call.
    00100     virtual void Lock() = 0;
    00101     /// Relinquishes an exclusive lock, signaling any threads that are waiting for
    00102     ///   this lock object to be relinquished.
    00103     virtual void Unlock() = 0;
    00104     /// Attempts to acquire an exclusive lock in the currently executing thread.
    00105     /// Each Lock or successful TryLock call must be paired with an Unlock call.
    00106     /// @return deTRUE if the lock was acquired, deFALSE if another thread holds the lock.
    00107     virtual deBoolean TryLock(u32 waitTimeInMs) = 0;
    00108     /// Releases & destroys a lock object.
    00109     /// This will block until the current thread can acquire this lock, and will then proceed.
    00110     virtual s32 Release() = 0;
    00111 protected:
    00112     virtual ~IdeThreadLock() {}
    00113 };
    00114
    00115 /// Manager class for avoiding threading overhead when many short-lived threads are needed.
    00116 DE3D_INTERFACE_(IdeThreadPool)
    00117 {
    00118 public:
    00119     /// Adds a work item to the queue. It will be executed immediately if a thread is
    00120     ///   available to process it, otherwise it will wait for a thread to become available.
    00121     /// This function will return immediately, whether the work item was executed or not.
    00122     virtual void QueueUserWorkItem(IdeThread::ThreadProc function, void* parameter) = 0;
    00123     ///
    00124     virtual u32 GetAvailableThreadCount() = 0;
    00125     virtual u32 GetCurrentThreadCount() = 0;
    00126     virtual void RemoveUnusedThreads() = 0;
    00127 protected:
    00128     virtual ~IdeThreadPool() {}
    00129 };
    00130
    00131 class deThreadScopeLock
    00132 {
    00133 private:
    00134     IdeThreadLock* mLockObj;
    00135 public:
    00136     inline deThreadScopeLock(IdeThreadLock* lockObj) : mLockObj(lockObj) { mLockObj->Lock(); }
    00137     inline ~deThreadScopeLock() { mLockObj->Unlock(); }
    00138 };
    00139
    00140 /// Create an IdeThread object
    00141 DETHREAD_API IdeThread* IdeThread_CreateThread(IdeThread::ThreadProc threadProc);
    00142 /// Create an IdeThreadLock synchronization object
    00143 DETHREAD_API IdeThreadLock* IdeThreadLock_CreateThreadLock(u32 spinCount = 1024);
    00144 DETHREAD_API IdeThreadPool* IdeThreadPool_GetPtr(u32 minThreadCount);
    00145 DETHREAD_API void IdeThreadPool_Destroy();
    00146
    00147 #endif //DETHREAD_HPP