sourcemod-central: public/IThreader.h@2e8046793bc9

     1 /**

     2  * vim: set ts=4 :

     3  * ================================================================

     4  * SourceMod

     5  * Copyright (C) 2004-2007 AlliedModders LLC.  All rights reserved.

     6  * ================================================================

     7  *

     8  * This program is free software; you can redistribute it and/or

     9  * modify it under the terms of the GNU General Public License,

    10  * version 3.0, as published by the Free Software Foundation.

    11  *

    12  * This program is distributed in the hope that it will be useful,

    13  * but WITHOUT ANY WARRANTY; without even the implied warranty of

    14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

    15  * GNU General Public License for more details.

    16  *

    17  * You should have received a copy of the GNU General Public License

    18  * along with this program.  If not, see <http://www.gnu.org/licenses/>.

    19  *

    20  * As a special exception, AlliedModders LLC gives you permission to

    21  * link the code of this program (as well as its derivative works) to

    22  * "Half-Life 2," the "Source Engine," the "SourcePawn JIT," and any

    23  * Game MODs that run on software by the Valve Corporation.  You must

    24  * obey the GNU General Public License in all respects for all other

    25  * code used. Additionally, AlliedModders LLC grants this exception

    26  * to all derivative works. AlliedModders LLC defines further

    27  * exceptions, found in LICENSE.txt (as of this writing, version

    28  * JULY-31-2007), or <http://www.sourcemod.net/license.php>.

    29  *

    30  * Version: $Id$

    31  */

    33 #ifndef _INCLUDE_SOURCEMOD_THREADER_H

    34 #define _INCLUDE_SOURCEMOD_THREADER_H

    36 /**

    37  * @file IThreader.h

    38  * @brief Contains platform independent routines for threading.

    39  */

    41 #include <IShareSys.h>

    43 #define SMINTERFACE_THREADER_NAME		"IThreader"

    44 #define SMINTERFACE_THREADER_VERSION	2

    46 namespace SourceMod

    47 {

    48 	/**

    49 	 * @brief Thread creation flags

    50 	 */

    51 	enum ThreadFlags

    52 	{

    53 		Thread_Default = 0,

    54 		/**

    55 		 * @brief Auto-release handle on finish

    56 		 *

    57 		 * You are not guaranteed the handle for this is valid after

    58 		 * calling MakeThread(), so never use it until OnTerminate is called.

    59 		 */

    60 		Thread_AutoRelease = 1,

    61 		/**

    62 		 * @brief Thread is created "suspended", meaning it is inactive until unpaused.

    63 		 */

    64 		Thread_CreateSuspended = 2,

    65 	};

    67 	/**

    68 	 * @brief Specifies thread priority levels.

    69 	 */

    70 	enum ThreadPriority

    71 	{

    72 		ThreadPrio_Minimum = -8,

    73 		ThreadPrio_Low = -3,

    74 		ThreadPrio_Normal = 0,

    75 		ThreadPrio_High = 3,

    76 		ThreadPrio_Maximum = 8,

    77 	};

    79 	/**

    80 	 * @brief The current state of a thread.

    81 	 */

    82 	enum ThreadState

    83 	{

    84 		Thread_Running = 0,

    85 		Thread_Paused = 1,

    86 		Thread_Done = 2,

    87 	};

    89 	/**

    90 	 * @brief Thread-specific parameters.

    91 	 */

    92 	struct ThreadParams

    93 	{

    94 		/** Constructor */

    95 		ThreadParams() :

    96 			flags(Thread_Default),

    97 			prio(ThreadPrio_Normal)

    98 		{

    99 		};

   100 		ThreadFlags flags;		/**< Flags to set on the thread */

   101 		ThreadPriority prio;	/**< Priority to set on the thread */

   102 	};

   104 	class IThreadCreator;

   106 	/**

   107 	 * @brief Describes a handle to a thread.

   108 	 */

   109 	class IThreadHandle

   110 	{

   111 	public:

   112 		/** Virtual destructor */

   113 		virtual ~IThreadHandle() { };

   114 	public:

   115 		/**

   116 		 * @brief Pauses parent thread until this thread completes.

   117 		 *

   118 		 * @return			True if successful, false otherwise.

   119 		 */

   120 		virtual bool WaitForThread() =0;

   122 		/**

   123 		 * @brief Destroys the thread handle.  This will not necessarily cancel the thread.

   124 		 */

   125 		virtual void DestroyThis() =0;

   127 		/**

   128 		 * @brief Returns the parent threader.

   129 		 *

   130 		 * @return			IThreadCreator that created this thread.

   131 		 */

   132 		virtual IThreadCreator *Parent() =0;

   134 		/**

   135 		 * @brief Returns the thread states.

   136 		 *

   137 		 * @param ptparams	Pointer to a ThreadParams buffer.

   138 		 */

   139 		virtual void GetParams(ThreadParams *ptparams) =0;

   141 		/**

   142 		 * @brief Returns the thread priority.

   143 		 *

   144 		 * @return			Thread priority.

   145 		 */

   146 		virtual ThreadPriority GetPriority() =0;

   148 		/**

   149 		 * @brief Sets thread priority.

   150 		 * NOTE: On Linux, this always returns false.

   151 		 *

   152 		 * @param prio		Thread priority to set.

   153 		 * @return			True if successful, false otherwise.

   154 		 */

   155 		virtual bool SetPriority(ThreadPriority prio) =0;

   157 		/**

   158 		 * @brief Returns the thread state.

   159 		 *

   160 		 * @return			Current thread state.

   161 		 */

   162 		virtual ThreadState GetState() =0;

   164 		/**

   165 		 * @brief Attempts to unpause a paused thread.

   166 		 *

   167 		 * @return			True on success, false otherwise.

   168 		 */

   169 		virtual bool Unpause() =0;

   170 	};

   172 	/**

   173 	 * @brief Handles a single thread's execution.

   174 	 */

   175 	class IThread

   176 	{

   177 	public:

   178 		/** Virtual destructor */

   179 		virtual ~IThread() { };

   180 	public:

   181 		/**

   182 		 * @brief Called when the thread runs (in its own thread).

   183 		 *

   184 		 * @param pHandle		Pointer to the thread's handle.

   185 		 */

   186 		virtual void RunThread(IThreadHandle *pHandle) =0;

   188 		/**

   189 		 * @brief Called when the thread terminates.  This occurs inside the thread as well.

   190 		 *

   191 		 * @param pHandle		Pointer to the thread's handle.

   192 		 * @param cancel		True if the thread did not finish, false otherwise.

   193 		 */

   194 		virtual void OnTerminate(IThreadHandle *pHandle, bool cancel) =0;

   195 	};

   198 	/**

   199 	 * @brief Describes a thread creator

   200 	 */

   201 	class IThreadCreator

   202 	{

   203 	public:

   204 		/** Virtual Destructor */

   205 		virtual ~IThreadCreator() { };

   206 	public:

   207 		/**

   208 		 * @brief Creates a basic thread.

   209 		 *

   210 		 * @param pThread		IThread pointer for callbacks.

   211 		 */

   212 		virtual void MakeThread(IThread *pThread) =0;

   214 		/**

   215 		 * @brief Creates a thread with specific options.

   216 		 *

   217 		 * @param pThread		IThread pointer for callbacks.

   218 		 * @param flags			Flags for the thread.

   219 		 * @return				IThreadHandle pointer (must be released).

   220 		 */

   221 		virtual IThreadHandle *MakeThread(IThread *pThread, ThreadFlags flags) =0;

   223 		/**

   224 		 * @brief Creates a thread with specific options.

   225 		 *

   226 		 * @param pThread		IThread pointer for callbacks.

   227 		 * @param params		Extended options for the thread.

   228 		 * @return				IThreadHandle pointer (must be released).

   229 		 */

   230 		virtual IThreadHandle *MakeThread(IThread *pThread, const ThreadParams *params) =0;

   232 		/**

   233 		 * @brief Returns the priority bounds.

   234 		 * Note: On Linux, the min and max are both Thread_Normal.

   235 		 *

   236 		 * @param max			Stores the maximum priority level.

   237 		 * @param min			Stores the minimum priority level.

   238 		 */

   239 		virtual void GetPriorityBounds(ThreadPriority &max, ThreadPriority &min) =0;

   240 	};

   242 	/**

   243 	 * @brief Describes a simple locking mutex.

   244 	 */

   245 	class IMutex

   246 	{

   247 	public:

   248 		/** Virtual Destructor */

   249 		virtual ~IMutex() { };

   250 	public:

   251 		/**

   252 		 * @brief Attempts to lock, but returns instantly.

   253 		 *

   254 		 * @return		True if lock was obtained, false otherwise.

   255 		 */

   256 		virtual bool TryLock() =0;

   258 		/**

   259  		 * @brief Attempts to lock by waiting for release.

   260 		 */

   261 		virtual void Lock() =0;

   263 		/**

   264 		 * @brief Unlocks the mutex.

   265 		 */

   266 		virtual void Unlock() =0;

   268 		/**

   269 		 * @brief Destroys the mutex handle.

   270 		 */

   271 		virtual void DestroyThis() =0;

   272 	};

   274 	/**

   275 	 * @brief Describes a simple "condition variable"/signal lock.

   276 	 */

   277 	class IEventSignal

   278 	{

   279 	public:

   280 		/** Virtual Destructor */

   281 		virtual ~IEventSignal() { };

   282 	public:

   283 		/**

   284 		 * @brief Waits for a signal.

   285 		 */

   286 		virtual void Wait() =0;

   288 		/**

   289 		 * @brief Triggers the signal and resets the signal after triggering.

   290 		 */

   291 		virtual void Signal() =0;

   293 		/**

   294 		 * @brief Frees the signal handle.

   295 		 */

   296 		virtual void DestroyThis() =0;

   297 	};

   299 	/**

   300 	 * @brief Describes possible worker states

   301 	 */

   302 	enum WorkerState

   303 	{

   304 		Worker_Invalid = -3,

   305 		Worker_Stopped = -2,

   306 		Worker_Paused = -1,

   307 		Worker_Running,

   308 	};

   310 	/**

   311 	 * @brief This is a "worker pool."  A single thread places tasks in a queue.

   312 	 * Each IThread is then a task, rather than its own separate thread.

   313 	 */

   314 	class IThreadWorker : public IThreadCreator

   315 	{

   316 	public:

   317 		/** Virtual Destructor */

   318 		virtual ~IThreadWorker()

   319 		{

   320 		};

   321 	public:

   322 		/**

   323 		 * @brief Runs one "frame" of the worker.

   324 		 *

   325 		 * @return			Number of tasks processed.

   326 		 */

   327 		virtual unsigned int RunFrame() =0;

   328 	public:

   329 		/**

   330 		 * @brief Pauses the worker.

   331 		 *

   332 		 * @return			True on success, false otherwise.

   333 		 */

   334 		virtual bool Pause() =0;

   336 		/**

   337 		 * @brief Unpauses the worker.

   338 		 *

   339 		 * @return			True on success, false otherwise.

   340 		 */

   341 		virtual bool Unpause() =0;

   343 		/**

   344 		 * @brief Starts the worker thread.

   345 		 *

   346 		 * @return			True on success, false otherwise.

   347 		 */

   348 		virtual bool Start() =0;

   350 		/**

   351 		 * @brief Stops the worker thread.

   352 		 *

   353 		 * @param flush		If true, all remaining tasks will be cancelled.

   354 		 *					Otherwise, the threader will wait until the queue is empty.

   355 		 * @return			True on success, false otherwise.

   356 		 */

   357 		virtual bool Stop(bool flush) =0;

   359 		/**

   360 		 * @brief Returns the status of the worker.

   361 		 *

   362 		 * @param numThreads	Pointer to store number of threads in the queue.

   363 		 * @return				State of the worker.

   364 		 */

   365 		virtual WorkerState GetStatus(unsigned int *numThreads) =0;

   366 	};

   368 	/**

   369 	 * @brief Describes thread worker callbacks.

   370 	 */

   371 	class IThreadWorkerCallbacks

   372 	{

   373 	public:

   374 		/**

   375 		 * @brief Called when the worker thread is initialized.

   376 		 *

   377 		 * @param pWorker		Pointer to the worker.

   378 		 */

   379 		virtual void OnWorkerStart(IThreadWorker *pWorker)

   380 		{

   381 		}

   383 		/**

   384 		 * @brief Called when the worker thread is cleaning up.

   385 		 *

   386 		 * @param pWorker		Pointer to the worker.

   387 		 */

   388 		virtual void OnWorkerStop(IThreadWorker *pWorker)

   389 		{

   390 		}

   391 	};

   393 	/**

   394 	 * @brief Describes a threading system

   395 	 */

   396 	class IThreader : public SMInterface, public IThreadCreator

   397 	{

   398 	public:

   399 		virtual const char *GetInterfaceName()

   400 		{

   401 			return SMINTERFACE_THREADER_NAME;

   402 		}

   403 		virtual unsigned int GetInterfaceVersion()

   404 		{

   405 			return SMINTERFACE_THREADER_VERSION;

   406 		}

   407 		virtual bool IsVersionCompatible(unsigned int version)

   408 		{

   409 			if (version < 2)

   410 			{

   411 				return false;

   412 			}

   413 			return SMInterface::IsVersionCompatible(version);

   414 		}

   415 	public:

   416 		/**

   417 		 * @brief Creates a mutex (mutual exclusion lock).

   418 		 *

   419 		 * @return			A new IMutex pointer (must be destroyed).

   420 		 */

   421 		virtual IMutex *MakeMutex() =0;

   423 		/**

   424 		 * @brief Sleeps the calling thread for a number of milliseconds.

   425 		 *

   426 		 * @param ms		Millisecond count to sleep.

   427 		 */

   428 		virtual void ThreadSleep(unsigned int ms) =0;

   430 		/**

   431 		 * @brief Creates a non-signalled event.

   432 		 *

   433 		 * @return			A new IEventSignal pointer (must be destroyed).

   434 		 */

   435 		virtual IEventSignal *MakeEventSignal() =0;

   437 		/**

   438 		 * @brief Creates a thread worker.

   439 		 *

   440 		 * @param hooks		Optional pointer to callback interface.

   441 		 * @param threaded	If true, the worker will be threaded.

   442 		 *					If false, the worker will require manual frame execution.

   443 		 * @return			A new IThreadWorker pointer (must be destroyed).

   444 		 */

   445 		virtual IThreadWorker *MakeWorker(IThreadWorkerCallbacks *hooks, bool threaded) =0;

   447 		/**

   448 		 * @brief Destroys an IThreadWorker pointer.

   449 		 *

   450 		 * @param pWorker	IThreadWorker pointer to destroy.

   451 		 */

   452 		virtual void DestroyWorker(IThreadWorker *pWorker) =0;

   453 	};

   454 };

   456 #endif //_INCLUDE_SOURCEMOD_THREADER_H

author	Phong Dang <teame06@gmail.com>
	Wed Aug 01 07:29:40 2007 +0000 (2007-08-01)
changeset 1241	2e8046793bc9
parent 1226	478550a4d5ec
child 1330	ab94316bb52b
permissions	-rw-r--r--