View source for Threads

{{Abstract Coding}}
{{toc-right}}

'''Threads''' are code execution paths that run simultaneously. On single-core systems this is achieved by switching rapidly between threads, while on multi-core systems things really do happen at exactly the same time.

As of 2024, less than 0.07% of systems were single-core, [http://store.steampowered.com/hwsurvey/cpus/?sort=pct and that figure is decreasing all the time]. It is important to thread resource-intensive code where sensible or you will be limited to just one of the user's cores, which as time goes on will be less and less of their system's true capacity.

As well as improving performance, threading can be used simply to process asynchronously. This is good when you have a job that the main thread can continue without knowing the result of (updating the UI, playing incidental music) or that could take a very long time (downloading a file from the internet). If you just want to postpone code until the future however, use <code>[[Think()]]</code>.

To learn about how Source handles threads under the hood, [https://cdn.akamai.steamstatic.com/apps/valve/2007/GDC2007_SourceMulticore.pdf see Tom Leonard's GDC 2007 presentation].

== Thread safety ==

{{todo|[[W:Thread safety|Thread safety]]}}

== Using the thread pool ==

The engine provides (system cores - 1) threads that you can throw jobs onto very easily. 

{{warning|Since each pooled thread will run its assigned job to completion before moving to the next, and since many important jobs are thrown into the pool, you should not use these methods to perform operations that will take an indefinite amount of time (e.g. downloading a file). [[#Creating new threads|Create entirely new threads]] for such tasks.}}

=== ParallelProcess() ===

<source lang=cpp>
void MyThreadedFunc(int& data)
{
	Msg("Job %i started\n",data);
	ThreadSleep(1000);
	Msg("\tJob %i complete\n",data);
}

CUtlVector<int> jobvec;
for (int i=0;i<10;i++)
	jobvec.AddToTail(i);
ParallelProcess(jobvec.Base(),jobvec.Count(),&MyThreadedFunc);
// current thread waits for completion
Msg("All jobs complete\n");
</source>

This function takes a <code>[[CUtlVector]]</code> containing the data you want to process, and the function that does the processing, and splits the ensuing work optimally across the thread pool ''and the current thread''. The current thread therefore does not continue until all parallel processing is complete.

{{tip|<code>ParallelProcess()</code> is [[W:Template (programming)|templated]]. <code>ITEM_TYPE</code> and <code>OBJECT_TYPE</code>, below, are defined by what you provide.}}

; <code>ITEM_TYPE* pItems</code>
: Pass <code>MyUtlVector.Base()</code>
; <code>[[int]] items</code>
: Pass <code>MyUtlVector.Count()</code>
; <code>OBJECT_TYPE* pObject</code>
: ''Optional.'' If <code>pfnProcess</code> needs to access members of a specific object, pass it here.
; <code>void* pfnProcess(ITEM_TYPE&)</code>
: A pointer to a void function that accepts a reference to <code>ITEM_TYPE</code>. {{note|If the argument is a pointer, that means your function must accept <code>ITEM_TYPE*&</code>!}}
; <code>void* pfnBegin()</code>
; <code>void* pfnEnd()</code>
: ''Optional.'' Functions to call before and after each thread completes its assigned jobs. 
; <code>int nMaxParallel</code>
: ''Optional.'' The maximum number of threads to split the job across.

=== ThreadExecute() ===

<source lang=cpp>
void test(int& data)
{
	Msg("thread %i started\n",data);
	ThreadSleep(1000);
	Msg("\tthread %i woke\n",data);
}

for (int i=0;i<10;i++)
	ThreadExecute(test,i);
</source>

Each call to <code>ThreadExecute()</code> queues up a new job for the thread pool to process (it's actually a macro for <code>g_pThreadPool->QueueCall()</code>). The current thread is not used, and so execution continues immediately.

<code>ThreadExecute()</code> returns a <code>[[CJob]]</code> object, which can be used to control the job's execution.

; <code>OBJECT_TYPE* pObject</code>
: ''Optional.'' If <code>pfnProxied</code> needs to access members of a specific object, pass it here.
; <code>void* pfnProxied([ARG_TYPE_1 ... ARG_TYPE_14])</code>
: The function to execute. It can have up to 14 arguments of any type.
; <code>ARG_TYPE_1</code> <span style="font-weight:normal;">to</span> <code>ARG_TYPE_14</code>
: ''Optional.'' The arguments to pass to the function. Must match the number of arguments it accepts.

=== g_pThreadPool->AddCall() ===

Identical to <code>ThreadExecute()</code>/<code>g_pThreadPool->QueueCall()</code>, except that the job is added to the front of the queue instead of the back.

== Creating new threads ==

=== Simple threads ===

Simple threads run a function asynchronously: the engine will set it running, then continue without waiting for it to complete. Please note that threads are expensive resources. If you can reuse a thread for a common task, then set up an event loop and send messages to it, instead of creating a new thread for each task of the same type.

<source lang=cpp>
struct MyThreadParams_t
{
	int number;
	char letter;
};

unsigned MyThread( void *params )
{
	MyThreadParams_t* vars = (MyThreadParams_t*) params; // always use a struct!

	// do some stuff

	Msg("Cannot print to console from this threaded function\n");

	// clean up the memory
	delete vars;

	return 0;
}

void SomeFunc()
{
	MyThreadParams_t* vars = new MyThreadParams_t;
	vars->number = 5;
	CreateSimpleThread( MyThread, vars );
}
</source>

{{note|<code>CreateSimpleThread()</code> expects a static function. If you are trying to call a member function of a class, you ''must'' type <code>MyClass::MyThread</code> to make the reference static. Include a pointer in the params if you need the thread to access its invoking object.}}
{{note|Do not use the stack to store memory on when sending parameters to another thread, as the values only exist while you are inside the scope in the function. Instead, use dynamic memory allocation or global variables!}}

=== Worker threads ===

<!--<code>CWorkerThread</code> threads are designed to split frame processing across cores. A frame will not be finished until all of its <code>CWorkerThread</code>s exit, so do not use them if you want a function to start now and report back at a later time.-->

Each <code>CWorkerThread</code> contains a number of variables, a calling command, and the mainloop <code>int Run()</code>. An instance of the class is declared inside a source file. The other threads can call this thread by calling the proper functions in this instance. The thread is not necessarily running when these functions are executed and will most likely be required to be started prior to any calls. A sample thread with a single function would look like this.

{{warning|All code in this article is only tested for the client. A radically different approach might be used by the server!}}

<source lang="cpp">
//-----------------------------------------------------------------------------
// A thread that can execute a function asynchronously.
//-----------------------------------------------------------------------------
class CMyAsyncThread: public CWorkerThread 
{
public:
	CMyAsyncThread() :
	m_Parameter1( NULL ) ,
	m_Parameter2( NULL )
	{
		SetName( "MyAsyncThread" );
	}

	~CMyAsyncThread()
	{
	}

	enum
	{
		CALL_FUNC,
		EXIT,
	};

	bool	CallThreadFunction( char* Parameter1, char* Parameter2 )
	{
		Assert( !Parameter1);
		Assert( !Parameter2 );
		m_Parameter1 = Parameter1;
		m_Parameter2 = Parameter2;
		CallWorker( CALL_FUNC );

		return true;
	}

	int Run()
	{
		unsigned nCall;
		while ( WaitForCall( &nCall ) )
		{
			if ( nCall == EXIT )
			{
				Reply( 1 );
				break;
			}

			// Reset some variables
			char* Parameter1 = m_Parameter1;
			char* Parameter2 = m_Parameter2;
			m_Parameter1 = 0;
			m_Parameter2 = 0;

			Reply( 1 );
			FunctionToBeRunFromInsideTheThread(Parameter1,Parameter2);

		}
		return 0;
	}

private:
	char* m_Parameter1;
	char* m_Parameter2;
};

static CMyAsyncThread g_CMyAsyncThread;
</source>

This sample will now be explained in details. However parts of the following might not be confirmed and is based on guesses and experience.

A thread is declared as a child class of CWorkerThread. The constructor sets the name of the thread. The official Valve Threads the name of the class without the leading C, but in theory this value could be anything. In the constructor all parameters should be initalized to zero, avoiding any nasty situations where they could by accident be initalized to something else. The destructor is defined and should be used to clean up, but with thread safety in mind.

<source lang="cpp">
class CMyAsyncThread: public CWorkerThread 
{
public:
	CMyAsyncThread() :
	m_Parameter1( NULL ) ,
	m_Parameter2( NULL )
	{
		SetName( "MyAsyncThread" );
	}

	~CMyAsyncThread()
	{
	}
</source>

Like most programs written for Win32, the thread waits for messages before executing code. For simplicity these messages could be written from within a enum. The values of these constants do not matter, as long they're not equal. It is recommended to have an EXIT command in case you wish to shut down the thread, which is nessesary to avoid memory leaks, when the game closes.

<source lang="cpp">
enum
{
	CALL_FUNC,
	EXIT,
};
</source>

When you wish to run a certain function in a thread, you can send a message to the thread's main loop. You can in addition copy memory to variables declared within the class, which apparently seems to be shared with the thread, or transmitted. The details of this remains unknown but experience shows that all memory copied to these variables is available when running from within the custom thread. Valve tests the pointers sent to the threads, so we left the testing code here. The parameters sent to the function is then copied into the shared memory and sent to the thread prior to execution, but as previously stated, the details are unknown.

<source lang="cpp">
bool	CallThreadFunction( char* Parameter1, char* Parameter2 )
{
	Assert( !Parameter1);
	Assert( !Parameter2 );
	m_Parameter1 = Parameter1;
	m_Parameter2 = Parameter2;
	CallWorker( CALL_FUNC );

	return true;
}
</source>

When the thread is started, the mainloop <code>Run()</code> is run. Like Win32 applications it patiently wait for messages to arrive and do not use any CPU when waiting. When another thread sends a message to the thread, the thread will begin executing again. The message sent to the thread can be read from the <code>nCall</code> integer sent to <code>WaitForCall()</code>. In this sample we check if it's the <code>EXIT</code> code and breaks the main loop if it is. Please note that we do not check whether the actual message sent were CALL_FUNC since we only have one function. A proper thread with multiple functions should do this.

We read the parameters sent along from the class's memory and afterwards we reset them to <code>NULL</code>. This was originally used by Valve to avoid running the function two times at the same time, where <code>ASSERT</code>s would detect if the variables were set. It is easily possible to call other functions outside the class from within the main loop, which we will demonstrate later. The <code>Reply()</code> command sends back a reply, but how this value is retrieved elsewhere is unknown.

<source lang="cpp">
int Run()
{
	unsigned nCall;
	while ( WaitForCall( &nCall ) )
	{
		if ( nCall == EXIT )
		{
			Reply( 1 );
			break;
		}

		// Reset some variables
		char* Parameter1 = m_Parameter1;
		char* Parameter2 = m_Parameter2;
		m_Parameter1 = 0;
		m_Parameter2 = 0;

		Reply( 1 );
		FunctionToBeRunFromInsideTheThread(Parameter1,Parameter2);

	}
	return 0;
}
</source>

It is possible to share memory between the creating thread and the calling thread, and perhaps others as well. This is done by adding variables to the private section of the thread class. The engine automatically takes care of the copying and no further declarations is required.

<source lang="cpp">
private:
	char* m_Parameter1;
	char* m_Parameter2;
};
</source>

Most importantly, when the thread class is defined an instance of the thread must be created. Simply write the following line of code just after the class definition.

<source lang="cpp">
static CMyAsyncThread g_CMyAsyncThread;
</source>

==== Calling worker threads ====

With the interface set, all that is left to do is declare functions that call the thread and functions that are called by the thread. Threads can be for instance called this way.

{{note|Make a copy of all data referred to by a pointer instead of passing the pointer. The data within the pointer is subject to change, or be deleted, during execution of the thread. This is basic Thread Safety.}}

<source lang="cpp">
// Creates the thread and calls it
bool	CreateAThreadAndCallTheFunction( char* Parameter1, char* Parameter2 )
{		
	if ( !g_CMyAsyncThread.IsAlive() )
		g_CMyAsyncThread.Start();

	if ( !g_CMyAsyncThread.IsAlive() )
		Warning("CreateAThreadAndCallTheFunction() failed to start the thread!\n");

	// Thread safety: make some local copies! The real ones could be deleted/changed while we execute.
	char* NewParameter1 = FUNCTION_THAT_CREATES_A_COPY_OF_THE_MEMORY(Parameter1);
	char* NewParameter2 = FUNCTION_THAT_CREATES_A_COPY_OF_THE_MEMORY(Parameter1);
	
	g_CMyAsyncThread.CallThreadFunction( NewParameter1, NewParameter2);

	g_CMyAsyncThread.CallWorker( CMyAsyncThread::EXIT );
	return true;
}
</source>

Lastly we will define a function that is called by the thread.

<source lang="cpp">
// This function is run from within the thread
bool FunctionToBeRunFromInsideTheThread( char* Parameter1 , char* Parameter2 )
{
	Msg("The thread works. The parameters are %s, %s",Parameter1,Parameter2);
	return true;
}
</source>

The function that should be run from within the thread (<code>FunctionToBeRunFromInsideTheThread()</code>) can be requested executed by other threads by calling <code>CreateAThreadAndCallTheFunction()</code>, which will create a new instance of the thread, execute the function, and delete the new thread. If you wish to learn more about how threads work in Source, try look for different implementations made by Valve, which is available within the latest Source SDK Code.

[[Category:Programming]]