AsyncEngine Class Reference

#include <s_async.h>

Collaboration diagram for AsyncEngine:

Public Member Functions
	AsyncEngine ()=default
	AsyncEngine (Server *server)
	~AsyncEngine ()
void	registerStateInitializer (StateInitializer func)
	Register function to be called on new states.
void	initialize (unsigned int numEngines)
	Create async engine tasks and lock function registration.
u32	queueAsyncJob (std::string &&func, std::string &&params, const std::string &mod_origin="")
	Queue an async job.
u32	queueAsyncJob (std::string &&func, PackedValue *params, const std::string &mod_origin="")
	Queue an async job.
bool	cancelAsyncJob (u32 id)
	Try to cancel an async job.
void	step (lua_State *L)
	Engine step to process finished jobs.
unsigned int	getThreadingCapacity () const
	Get the maximum number of threads that can be used by the async environment.

Protected Member Functions
bool	getJob (LuaJobInfo *job)
	Get a Job from queue to be processed this function blocks until a job is ready.
u32	queueAsyncJob (LuaJobInfo &&job)
	Queue an async job.
void	putJobResult (LuaJobInfo &&result)
	Put a Job result back to result queue.
void	addWorkerThread ()
	Start an additional worker thread.
void	stepJobResults (lua_State *L)
	Process finished jobs callbacks.
void	stepAutoscale ()
	Handle automatic scaling of worker threads.
void	stepStuckWarning ()
	Print warning message if too many jobs are stuck.
bool	prepareEnvironment (lua_State *L, int top)
	Initialize environment with current registred functions this function adds all functions registred by registerFunction to the passed lua stack.

Private Types
typedef void(*	StateInitializer) (lua_State *L, int top)

Private Member Functions
template<typename T>
void	snapshotJobs (T &to)
template<typename T>
size_t	compareJobs (const T &from)

Private Attributes
bool	initDone = false
unsigned int	autoscaleMaxWorkers = 0
u64	autoscaleTimer = 0
std::unordered_set< u32 >	autoscaleSeenJobs
u64	stuckTimer = 0
std::unordered_set< u32 >	stuckSeenJobs
Server *	server = nullptr
std::vector< StateInitializer >	stateInitializers
u32	jobIdCounter = 0
std::mutex	jobQueueMutex
std::deque< LuaJobInfo >	jobQueue
std::mutex	resultQueueMutex
std::deque< LuaJobInfo >	resultQueue
std::vector< AsyncWorkerThread * >	workerThreads
Semaphore	jobQueueCounter

Friends
class	AsyncWorkerThread

Member Typedef Documentation

StateInitializer

typedef void(* AsyncEngine::StateInitializer) (lua_State *L, int top)

private

Constructor & Destructor Documentation

AsyncEngine() [1/2]

AsyncEngine::AsyncEngine ( )

default

AsyncEngine() [2/2]

AsyncEngine::AsyncEngine ( Server * server )

inline

~AsyncEngine()

AsyncEngine::~AsyncEngine

(

)

References AsyncWorkerThread, infostream, jobQueue, jobQueueCounter, jobQueueMutex, and workerThreads.

Here is the call graph for this function:

Member Function Documentation

addWorkerThread()

void AsyncEngine::addWorkerThread ( )

protected

Start an additional worker thread.

References AsyncWorkerThread, itos(), Thread::start(), and workerThreads.

Referenced by initialize(), and stepAutoscale().

Here is the call graph for this function:

Here is the caller graph for this function:

cancelAsyncJob()

bool AsyncEngine::cancelAsyncJob

(

u32

id

)

Try to cancel an async job.

Parameters

id	The ID of the job

Returns

Whether the job was cancelled

References jobQueue, and jobQueueMutex.

compareJobs()

template<typename T>

size_t AsyncEngine::compareJobs ( const T & from )

inlineprivate

References jobQueue.

Referenced by stepAutoscale(), and stepStuckWarning().

Here is the caller graph for this function:

getJob()

bool AsyncEngine::getJob ( LuaJobInfo * job )

protected

Get a Job from queue to be processed this function blocks until a job is ready.

Parameters

job	a job to be processed

Returns

whether a job was available

References jobQueue, jobQueueCounter, and jobQueueMutex.

getThreadingCapacity()

unsigned int AsyncEngine::getThreadingCapacity ( ) const

inline

Get the maximum number of threads that can be used by the async environment.

References autoscaleMaxWorkers, MYMAX, and workerThreads.

initialize()

void AsyncEngine::initialize

(

unsigned int

numEngines

)

Create async engine tasks and lock function registration.

Parameters

numEngines

Number of worker threads, 0 for automatic scaling

References addWorkerThread(), autoscaleMaxWorkers, Thread::getNumberOfProcessors(), infostream, and initDone.

Here is the call graph for this function:

prepareEnvironment()

bool AsyncEngine::prepareEnvironment ( lua_State * L, int top )

protected

Initialize environment with current registred functions this function adds all functions registred by registerFunction to the passed lua stack.

Parameters

L	Lua stack to initialize
top	Stack position

Returns

false if a mod error ocurred

References BUILTIN_MOD_NAME, DIR_DELIM, errorstream, Server::getBuiltinLuaPath(), ModApiBase::getScriptApiBase(), stateInitializers, and BaseException::what().

Here is the call graph for this function:

putJobResult()

void AsyncEngine::putJobResult ( LuaJobInfo && result )

protected

Put a Job result back to result queue.

Parameters

result

result of completed job

References resultQueue, and resultQueueMutex.

queueAsyncJob() [1/3]

u32 AsyncEngine::queueAsyncJob ( LuaJobInfo && job )

protected

Queue an async job.

Parameters

job	The job to queue (takes ownership!)

Returns

Id of the queued job

References jobIdCounter, jobQueue, jobQueueCounter, and jobQueueMutex.

queueAsyncJob() [2/3]

u32 AsyncEngine::queueAsyncJob	(	std::string &&	func,
		PackedValue *	params,
		const std::string &	mod_origin = "" )

Queue an async job.

Parameters

func	Serialized lua function
params	Serialized parameters (takes ownership!)

Returns

ID of queued job

References queueAsyncJob().

Here is the call graph for this function:

queueAsyncJob() [3/3]

u32 AsyncEngine::queueAsyncJob	(	std::string &&	func,
		std::string &&	params,
		const std::string &	mod_origin = "" )

Queue an async job.

Parameters

func	Serialized lua function
params	Serialized parameters

Returns

jobid The job is queued

References queueAsyncJob().

Referenced by queueAsyncJob(), and queueAsyncJob().

Here is the call graph for this function:

Here is the caller graph for this function:

registerStateInitializer()

void AsyncEngine::registerStateInitializer

(

StateInitializer

func

)

Register function to be called on new states.

Parameters

func	C function to be called

References FATAL_ERROR_IF, initDone, and stateInitializers.

snapshotJobs()

template<typename T>

void AsyncEngine::snapshotJobs ( T & to )

inlineprivate

References jobQueue.

Referenced by stepAutoscale(), and stepStuckWarning().

Here is the caller graph for this function:

step()

void AsyncEngine::step

(

lua_State *

L

)

Engine step to process finished jobs.

Parameters

L	The Lua stack

References stepAutoscale(), stepJobResults(), and stepStuckWarning().

Here is the call graph for this function:

stepAutoscale()

void AsyncEngine::stepAutoscale ( )

protected

Handle automatic scaling of worker threads.

References addWorkerThread(), AUTOSCALE_DELAY_MS, autoscaleMaxWorkers, autoscaleSeenJobs, autoscaleTimer, compareJobs(), porting::getTimeMs(), infostream, jobQueue, jobQueueMutex, snapshotJobs(), and workerThreads.

Referenced by step().

Here is the call graph for this function:

Here is the caller graph for this function:

stepJobResults()

void AsyncEngine::stepJobResults ( lua_State * L )

protected

Process finished jobs callbacks.

References FATAL_ERROR, ModApiBase::getScriptApiBase(), LuaJobInfo::id, LuaJobInfo::mod_origin, PUSH_ERROR_HANDLER, LuaJobInfo::result, LuaJobInfo::result_ext, resultQueue, resultQueueMutex, script_error(), script_unpack(), and ScriptApiBase::setOriginDirect().

Referenced by step().

Here is the call graph for this function:

Here is the caller graph for this function:

stepStuckWarning()

void AsyncEngine::stepStuckWarning ( )

protected

Print warning message if too many jobs are stuck.

References compareJobs(), porting::getTimeMs(), jobQueue, jobQueueMutex, snapshotJobs(), STUCK_DELAY_MS, stuckSeenJobs, stuckTimer, warningstream, and workerThreads.

Referenced by step().

Here is the call graph for this function:

Here is the caller graph for this function:

Friends And Related Symbol Documentation

AsyncWorkerThread

friend class AsyncWorkerThread

friend

References AsyncWorkerThread.

Referenced by ~AsyncEngine(), addWorkerThread(), and AsyncWorkerThread.

Member Data Documentation

autoscaleMaxWorkers

unsigned int AsyncEngine::autoscaleMaxWorkers = 0

private

Referenced by getThreadingCapacity(), initialize(), and stepAutoscale().

autoscaleSeenJobs

std::unordered_set<u32> AsyncEngine::autoscaleSeenJobs

private

Referenced by stepAutoscale().

autoscaleTimer

u64 AsyncEngine::autoscaleTimer = 0

private

Referenced by stepAutoscale().

initDone

bool AsyncEngine::initDone = false

private

Referenced by initialize(), and registerStateInitializer().

jobIdCounter

u32 AsyncEngine::jobIdCounter = 0

private

Referenced by queueAsyncJob().

jobQueue

std::deque<LuaJobInfo> AsyncEngine::jobQueue

private

Referenced by ~AsyncEngine(), cancelAsyncJob(), compareJobs(), getJob(), queueAsyncJob(), snapshotJobs(), stepAutoscale(), and stepStuckWarning().

jobQueueCounter

Semaphore AsyncEngine::jobQueueCounter

private

Referenced by ~AsyncEngine(), getJob(), and queueAsyncJob().

jobQueueMutex

std::mutex AsyncEngine::jobQueueMutex

private

Referenced by ~AsyncEngine(), cancelAsyncJob(), getJob(), queueAsyncJob(), stepAutoscale(), and stepStuckWarning().

resultQueue

std::deque<LuaJobInfo> AsyncEngine::resultQueue

private

Referenced by putJobResult(), and stepJobResults().

resultQueueMutex

std::mutex AsyncEngine::resultQueueMutex

private

Referenced by putJobResult(), and stepJobResults().

server

Server* AsyncEngine::server = nullptr

private

stateInitializers

std::vector<StateInitializer> AsyncEngine::stateInitializers

private

Referenced by prepareEnvironment(), and registerStateInitializer().

stuckSeenJobs

std::unordered_set<u32> AsyncEngine::stuckSeenJobs

private

Referenced by stepStuckWarning().

stuckTimer

u64 AsyncEngine::stuckTimer = 0

private

Referenced by stepStuckWarning().

workerThreads

std::vector<AsyncWorkerThread*> AsyncEngine::workerThreads

private

Referenced by ~AsyncEngine(), addWorkerThread(), getThreadingCapacity(), stepAutoscale(), and stepStuckWarning().

---

The documentation for this class was generated from the following files:

• script/cpp_api/s_async.h
• script/cpp_api/s_async.cpp