Multi-Threading: How to Create Threads in UE4

Rate this Article:

5.00

  (one vote)

Approved for Versions:(please verify)

Overview

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

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 for the entiring 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 :)

width="560" height="315" src="https://www.youtube.com/embed/cgELOodtoSU" frameborder="0" allowfullscreen="">

.H

//~~~~~ 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();
 
};

.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;
 
	const bool bAutoDeleteSelf = false;
	const bool bAutoDeleteRunnable = false;
	Thread = FRunnableThread::Create(this, TEXT("FPrimeNumberWorker"), bAutoDeleteSelf, bAutoDeleteRunnable, 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;
}

Starting the thread

//In the .h for the player controller
// this is the actual data
TArray<uint32> PrimeNumbers;

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

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

FPlatformProcess::Sleep(seconds);

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...)

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.

Conclusion

Enjoy!

Rama (talk)

Categories: 

• Tutorials
• Code
• Community Created Content

Rate this Article:

5.00

  (one vote)

Approved for Versions:(please verify)

Overview

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

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 for the entiring 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 :)

width="560" height="315" src="https://www.youtube.com/embed/cgELOodtoSU" frameborder="0" allowfullscreen="">

.H

//~~~~~ 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();
 
};

.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;
 
	const bool bAutoDeleteSelf = false;
	const bool bAutoDeleteRunnable = false;
	Thread = FRunnableThread::Create(this, TEXT("FPrimeNumberWorker"), bAutoDeleteSelf, bAutoDeleteRunnable, 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;
}

Starting the thread

//In the .h for the player controller
// this is the actual data
TArray<uint32> PrimeNumbers;

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

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

FPlatformProcess::Sleep(seconds);

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...)

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.

Conclusion

Enjoy!

Rama (talk)

Categories: 

• Tutorials
• Code
• Community Created Content