integration/Source/Integration/TriggeredTask.h

#pragma once

#include "CoreMinimal.h"

///////////////////////////////////////////////
//
// TRIGGERED TASKS
//
// This is the situation where this class is
// useful:
// 
// * You have a function to run in the background.
// * It should start the instant a foreground thread says "NOW".
// * It should be run exactly once for each "NOW".
// * The foreground thread eventually waits for the background thread to finish.
//
// To use this class, construct an FTriggeredTask,
// and provide a runnable object.  The runnable
// object's "Run" method will get executed in
// each time you call 'Trigger' on the FTriggeredTask.
//
///////////////////////////////////////////////

class FTriggeredTask : public FRunnable
{
private:
	// Mutex used by control routines.
	//
	FCriticalSection Mutex;

	// The worker thread.
	//
	FRunnableThread* Thread;

	// Used to tell the worker thread to stop.
	//
	bool ThreadStopRequested;

	// This event is used to wake up the thread.
	//
	// This is an auto-reset event, meaning that each time we
	// call trigger, the background thread is gated exactly once.
	//
	// Normally, this means we want the worker to run the task
	// once. But if ThreadStopRequested is true, it means we
	// want the thread to exit.
	//
	FEvent* CallEvent;

	// This event is used when the thread is done with its work.  
	//
	// This is not an auto-reset event.  This event stays triggered
	// whenever the background thread is not running.
	//
	FEvent* ReturnEvent;

	// The client whose task we're triggering.
	//
	FRunnable* Client;

private:
	/////////////////////////////////////////////
	// 
	// This section contains routines that are
	// executed by the thread itself.
	//
	/////////////////////////////////////////////

	// Method of FRunnable, called by the Luprex thread.
	//
	virtual uint32 Run() override;

public:
	/////////////////////////////////////////////
	//
	// This section contains thread control routines.
	// These are not invoked by the thread, but by the
	// outside entity that started the thread.
	//
	/////////////////////////////////////////////

	// Constructor.
	//
	// The client must outlive the FTriggeredTask.
	//
	FTriggeredTask();
	
	// Startup.
	//
	// Bring the system online, put it in ready mode.
	//
	void Startup(FRunnable* client);

	// Shutdown.
	//
	// Bring the system down, deallocate all threads.
	//
	void Shutdown();

	// Trigger
	//
	// Run the client's 'RUN' method once, in the
	// background.
	//
	void Trigger();

	// Wait
	//
	// Wait for the background task to finish its work.
	// If the background thread isn't running, then this
	// returns immediately.
	//
	void Wait();

	// IsRunning
	//
	bool IsRunning();
};