View source for Multi-Threading: How to Create Threads in UE4

{{Rating|Type=Article|Versions=(please verify)}}
==Overview==

'''Author''' [[User:Rama|Rama]] ([[User talk:Rama|talk]])

Dear Community,

Here is how you can create your own threads in UE4!

This is the code you'd use for a very large task.

For small incremental tasks that can be divided into chunks check out my Task Graph Tutorial:
	
'''[[Multi-Threading:_Task_Graph_System]]'''

''Note start ([[User:Zyr|Zyr]] | [[User talk:Zyr|talk]])''

The ''FRunnable'' and ''FRunnableThread'' approach Rama presents here is certainly a viable solution for most problems. However, when creating many tasks you might hit the upper limit of concurrency a CPU can handle, at which point the concurrent threads are actually going to hinder each other while fighting for CPU time. It might then be worth looking at the [https://docs.unrealengine.com/latest/INT/API/Runtime/Core/Misc/FQueuedThreadPool/index.html FQueuedThreadPool] to limit the number of threads available to your tasks.

The Unreal Engine 4 also provides a global ''GThreadPool'', however this thread pool is set to only a single thread (UE4.14.3). It seems to be intended for simply running a concurrent task on another core.

''Note end''

===What The Code Below Does===

* Creates a thread to compute the first 50,000 prime numbers
* Sends incremental completion data back to the Game Thread
* Has static accessors for starting, shutting down, and finding out if thread is done.

===Static Functions===

You will note in the code below I am using static functions to easily start the new thread, and I could also use a static Shutdown() function from the GameThread if I ever needed to shut the thread down in a hurry (such as player exiting the game)

===Performance===

I first computed the first 50,000 prime numbers using the Task Graph System, and creating 50,000 tasks (1 for each prime to find).

In the code you see in this tutorial, I instead created a dedicated thread to calculate the first 50,000 prime numbers!

'''The performance benefit was phenomenal!'''

My fps stayed solid 90 (my chosen max fps) for the entire running of this thread in code below.

Whereas for with the task graph system, as I got closer to 50,000 the fps dropped by a max of 40.

For larger tasks make sure to try out actual multi-threading!

===Video===

The below is video for the multi-task version, which had marked fps drop as compared with this method of creating an actual thread.

It's the same general idea though, the first 50,000 prime numbers get computed while you continue to do whatever you want in main game thread :)

I show my results at the end of the video.

You can compare them with this webpage!

My multi-threading system did actually calculate the first 50,000 (+1) prime numbers!

'''[http://www.cs.arizona.edu/icon/oddsends/primes.htm |First 50,000 Prime Numbers]'''

<youtube>https://www.youtube.com/watch?v=cgELOodtoSU&feature=youtu.be</youtube>

==.H==
<syntaxhighlight lang="cpp">
//~~~~~ Multi Threading ~~~
class FPrimeNumberWorker : public FRunnable
{	
	/** Singleton instance, can access the thread any time via static accessor, if it is active! */
	static  FPrimeNumberWorker* Runnable;
	
	/** Thread to run the worker FRunnable on */
	FRunnableThread* Thread;
	
	/** The Data Ptr */
	TArray<uint32>* PrimeNumbers;
	
	/** The PC */
	AVictoryGamePlayerController* ThePC;
	
	/** Stop this thread? Uses Thread Safe Counter */
	FThreadSafeCounter StopTaskCounter;
	
	//The actual finding of prime numbers
	int32 FindNextPrimeNumber();
	
private:
	int32				PrimesFoundCount;
public:
	
	int32				TotalPrimesToFind;

	//Done?
	bool IsFinished() const
	{
		return PrimesFoundCount >= TotalPrimesToFind;
	}
	
	//~~~ Thread Core Functions ~~~
	
	//Constructor / Destructor
	FPrimeNumberWorker(TArray<uint32>& TheArray, const int32 IN_PrimesToFindPerTick, AVictoryGamePlayerController* IN_PC);
	virtual ~FPrimeNumberWorker();

	// Begin FRunnable interface.
	virtual bool Init();
	virtual uint32 Run();
	virtual void Stop();
	// End FRunnable interface
	
	/** Makes sure this thread has stopped properly */
	void EnsureCompletion();
	
	
	
	//~~~ Starting and Stopping Thread ~~~
	
	
	
	/* 
		Start the thread and the worker from static (easy access)! 
		This code ensures only 1 Prime Number thread will be able to run at a time. 
		This function returns a handle to the newly started instance.
	*/
	static FPrimeNumberWorker* JoyInit(TArray<uint32>& TheArray, const int32 IN_TotalPrimesToFind, AVictoryGamePlayerController* IN_PC);

	/** Shuts down the thread. Static so it can easily be called from outside the thread context */
	static void Shutdown();

        static bool IsThreadFinished();

};
</syntaxhighlight>

==.CPP==

<syntaxhighlight lang="cpp">
//***********************************************************
//Thread Worker Starts as NULL, prior to being instanced
//		This line is essential! Compiler error without it
FPrimeNumberWorker* FPrimeNumberWorker::Runnable = NULL;
//***********************************************************

FPrimeNumberWorker::FPrimeNumberWorker(TArray<uint32>& TheArray, const int32 IN_TotalPrimesToFind, AVictoryGamePlayerController* IN_PC)
	: ThePC(IN_PC)
	, TotalPrimesToFind(IN_TotalPrimesToFind)
	, StopTaskCounter(0)
	, PrimesFoundCount(0)
{
	//Link to where data should be stored
	PrimeNumbers = &TheArray;
	
	Thread = FRunnableThread::Create(this, TEXT("FPrimeNumberWorker"), 0, TPri_BelowNormal); //windows default = 8mb for thread, could specify more
}

FPrimeNumberWorker::~FPrimeNumberWorker()
{
	delete Thread;
	Thread = NULL;
}

//Init
bool FPrimeNumberWorker::Init()
{
	//Init the Data 
	PrimeNumbers->Empty();
	PrimeNumbers->Add(2);
	PrimeNumbers->Add(3);
	
	if(ThePC) 
	{
		ThePC->ClientMessage("**********************************");
		ThePC->ClientMessage("Prime Number Thread Started!");
		ThePC->ClientMessage("**********************************");
	}
	return true;
}

//Run
uint32 FPrimeNumberWorker::Run()
{
	//Initial wait before starting
	FPlatformProcess::Sleep(0.03);
	
	//While not told to stop this thread 
	//		and not yet finished finding Prime Numbers
	while (StopTaskCounter.GetValue() == 0 && ! IsFinished())
	{
		PrimeNumbers->Add(FindNextPrimeNumber());
		PrimesFoundCount++;
		
		//***************************************
		//Show Incremental Results in Main Game Thread!
		
		//	Please note you should not create, destroy, or modify UObjects here.
		//	  Do those sort of things after all thread are completed.
		
		//	  All calcs for making stuff can be done in the threads
		//	     But the actual making/modifying of the UObjects should be done in main game thread.
		ThePC->ClientMessage(FString::FromInt(PrimeNumbers->Last()));
		//***************************************
		
		//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
		//prevent thread from using too many resources
		//FPlatformProcess::Sleep(0.01);
		//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	}
	
	//Run FPrimeNumberWorker::Shutdown() from the timer in Game Thread that is watching
        //to see when FPrimeNumberWorker::IsThreadFinished()
	
	return 0;
}

//stop
void FPrimeNumberWorker::Stop()
{
	StopTaskCounter.Increment();
}

FPrimeNumberWorker* FPrimeNumberWorker::JoyInit(TArray<uint32>& TheArray, const int32 IN_TotalPrimesToFind, AVictoryGamePlayerController* IN_PC)
{
	//Create new instance of thread if it does not exist
	//		and the platform supports multi threading!
	if (!Runnable && FPlatformProcess::SupportsMultithreading())
	{
		Runnable = new FPrimeNumberWorker(TheArray,IN_TotalPrimesToFind,IN_PC);			
	}
	return Runnable;
}

void FPrimeNumberWorker::EnsureCompletion()
{
	Stop();
	Thread->WaitForCompletion();
}

void FPrimeNumberWorker::Shutdown()
{
	if (Runnable)
	{
		Runnable->EnsureCompletion();
		delete Runnable;
		Runnable = NULL;
	}
}

bool FPrimeNumberWorker::IsThreadFinished()
{
	if(Runnable) return Runnable->IsFinished();
	return true;
}
int32 FPrimeNumberWorker::FindNextPrimeNumber()
{
	//Last known prime number  + 1
	int32 TestPrime = PrimeNumbers->Last();
	
	bool NumIsPrime = false;
	while( ! NumIsPrime)
	{
		NumIsPrime = true;
		
		//Try Next Number
		TestPrime++;
		
		//Modulus from 2 to current number - 1 
		for(int32 b = 2; b < TestPrime; b++)
		{
			//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
			//prevent thread from using too many resources
			//FPlatformProcess::Sleep(0.01);
			//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	
			if(TestPrime % b == 0) 
			{
				NumIsPrime = false;
				break;
				//~~~
			}
		}
	}
	
	//Success!
	return TestPrime;
}
</syntaxhighlight>

==Starting the thread==

<syntaxhighlight lang="cpp">
//In the .h for the player controller
// this is the actual data
TArray<uint32> PrimeNumbers;
</syntaxhighlight>


<syntaxhighlight lang="cpp">
//player controller .cpp
//Multi-threading, returns handle that could be cached.
//		use static function FPrimeNumberWorker::Shutdown() if necessary
FPrimeNumberWorker::JoyInit(PrimeNumbers, 50000, this);
</syntaxhighlight>

== Thread Management ==

You should look in the code base for "FRunnable" to see expanded uses of multi threading and lock / unlocking protection.

I used a simple example to get you started, but there's a lot to consider when multi-threading :)

=== Using Sleep for Thread Management ===

You should consider using 

<syntaxhighlight lang="cpp">
FPlatformProcess::Sleep(seconds);
</syntaxhighlight>

to prevent 1 thread from taking too many system resources :)

==What Not to Do==

* Do not try to modify, create, or delete UObjects from other threads!

You can prepare all the data / do all the calculations, but only the game thread should be actually spawning / modifying / deleting UObjects / AActors.

* Dont try to use TimerManager outside of the game thread :)

* Don't try to draw debug lines/points etc, as it will likely crash, ie DrawDebugLine(etc...)

Notice (since 4.11):

If you want to use the timer, remove, and modify variables use it:

<syntaxhighlight lang="cpp">
#include "Async.h"
...
AsyncTask(ENamedThreads::GameThread, []() {
     // code to execute on game thread here
 });
</syntaxhighlight>

==Timer Functions in GameThread==

You can run a timer function in the game thread to periodically check on the data being gathered by the other threads you create.

==How to Support Single Threaded Platforms?==

If your code absolutely has to run even in a single threaded environment such as HTML5, then check out

'''AsyncIOSystemBase.h'''
  struct CORE_API FAsyncIOSystemBase : public FIOSystem, FRunnable, FSingleThreadRunnable

A Runnable can extend SingleThreadRunnable and return itself for FRunnable's hook for single threaded cases:

<syntaxhighlight lang="cpp">
/**
 * Gets single thread interface pointer used for ticking this runnable when multi-threading is disabled.
 * If the interface is not implemented, this runnable will not be ticked when FPlatformProcess::SupportsMultithreading() is false.
 *
 * @return Pointer to the single thread interface or nullptr if not implemented.
 */
virtual class FSingleThreadRunnable* GetSingleThreadInterface( )
{
	return nullptr;
}
</syntaxhighlight>

==Conclusion==

Enjoy!

[[User:Rama|Rama]] ([[User talk:Rama|talk]])

[[Category:Tutorials]]
[[Category:Code]]
[[Category:Community Created Content]]