minetest/src/script/lua_api/l_async_events.h

221 lines
5.8 KiB
C++

/*
Minetest
Copyright (C) 2013 sapier, <sapier AT gmx DOT net>
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
*/
#ifndef L_ASYNC_EVENTS_H_
#define L_ASYNC_EVENTS_H_
#include <vector>
#include <map>
/******************************************************************************/
/* Includes */
/******************************************************************************/
#include "jthread/jthread.h"
#include "jthread/jmutex.h"
#include "jthread/jsemaphore.h"
#include "debug.h"
#include "lua.h"
/******************************************************************************/
/* Typedefs and macros */
/******************************************************************************/
#define MAINMENU_NUMBER_OF_ASYNC_THREADS 4
/******************************************************************************/
/* forward declarations */
/******************************************************************************/
class AsyncEngine;
/******************************************************************************/
/* declarations */
/******************************************************************************/
/** a struct to encapsulate data required to queue a job **/
struct LuaJobInfo {
/** function to be called in async environment **/
std::string serializedFunction;
/** parameter table to be passed to function **/
std::string serializedParams;
/** result of function call **/
std::string serializedResult;
/** jobid used to identify a job and match it to callback **/
unsigned int JobId;
/** valid marker **/
bool valid;
};
/** class encapsulating a asynchronous working environment **/
class AsyncWorkerThread : public JThread {
public:
/**
* default constructor
* @param pointer to job dispatcher
*/
AsyncWorkerThread(AsyncEngine* jobdispatcher, unsigned int threadnumber);
/**
* default destructor
*/
virtual ~AsyncWorkerThread();
/**
* thread function
*/
void* Thread() {
ThreadStarted();
return worker_thread_wrapper(this);
}
private:
/**
* helper function to run a lua script
* @param path of script
*/
bool runScript(std::string script);
/**
* main function of thread
*/
void* worker_thread_main();
/**
* static wrapper for thread creation
* @param this pointer to the thread to be created
*/
static void* worker_thread_wrapper(void* thread);
/**
* pointer to job dispatcher
*/
AsyncEngine* m_JobDispatcher;
/**
* the lua stack to run at
*/
lua_State* m_LuaStack;
/**
* lua internal stack number of error handler
*/
int m_luaerrorhandler;
/**
* thread number used for debug output
*/
unsigned int m_threadnum;
};
/** asynchornous thread and job management **/
class AsyncEngine {
friend class AsyncWorkerThread;
public:
/**
* default constructor
*/
AsyncEngine();
/**
* default destructor
*/
~AsyncEngine();
/**
* register function to be used within engines
* @param name function name to be used within lua environment
* @param fct c-function to be called
*/
bool registerFunction(const char* name, lua_CFunction fct);
/**
* create async engine tasks and lock function registration
* @param numengines number of async threads to be started
*/
void Initialize(unsigned int numengines);
/**
* queue/run a async job
* @param fct serialized lua function
* @param params serialized parameters
* @return jobid the job is queued
*/
unsigned int doAsyncJob(std::string fct, std::string params);
/**
* engine step to process finished jobs
* the engine step is one way to pass events back, PushFinishedJobs another
* @param L the lua environment to do the step in
*/
void Step(lua_State *L);
void PushFinishedJobs(lua_State* L);
protected:
/**
* Get a Job from queue to be processed
* this function blocks until a job is ready
* @return a job to be processed
*/
LuaJobInfo getJob();
/**
* put a Job result back to result queue
* @param result result of completed job
*/
void putJobResult(LuaJobInfo result);
/**
* initialize environment with current registred functions
* this function adds all functions registred by registerFunction to the
* passed lua stack
* @param L lua stack to initialize
* @param top stack position
*/
void PrepareEnvironment(lua_State* L, int top);
private:
/** variable locking the engine against further modification **/
bool m_initDone;
/** internal store for registred functions **/
std::map<std::string,lua_CFunction> m_FunctionList;
/** internal counter to create job id's **/
unsigned int m_JobIdCounter;
/** mutex to protect job queue **/
JMutex m_JobQueueMutex;
/** job queue **/
std::vector<LuaJobInfo> m_JobQueue;
/** mutext to protect result queue **/
JMutex m_ResultQueueMutex;
/** result queue **/
std::vector<LuaJobInfo> m_ResultQueue;
/** list of current worker threads **/
std::vector<AsyncWorkerThread*> m_WorkerThreads;
/** counter semaphore for job dispatching **/
JSemaphore m_JobQueueCounter;
};
#endif /* L_ASYNC_EVENTS_H_ */