src/script/cpp_api/s_async.h

   1 /*
   2 Minetest
   3 Copyright (C) 2013 sapier, <sapier AT gmx DOT net>
   4
   5 This program is free software; you can redistribute it and/or modify
   6 it under the terms of the GNU Lesser General Public License as published by
   7 the Free Software Foundation; either version 2.1 of the License, or
   8 (at your option) any later version.
   9
  10 This program is distributed in the hope that it will be useful,
  11 but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 GNU Lesser General Public License for more details.
  14
  15 You should have received a copy of the GNU Lesser General Public License along
  16 with this program; if not, write to the Free Software Foundation, Inc.,
  17 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  18 */
  19
  20 #ifndef CPP_API_ASYNC_EVENTS_HEADER
  21 #define CPP_API_ASYNC_EVENTS_HEADER
  22
  23 #include <vector>
  24 #include <deque>
  25 #include <map>
  26
  27 #include "jthread/jthread.h"
  28 #include "jthread/jmutex.h"
  29 #include "jthread/jsemaphore.h"
  30 #include "debug.h"
  31 #include "lua.h"
  32 #include "cpp_api/s_base.h"
  33
  34 // Forward declarations
  35 class AsyncEngine;
  36
  37
  38 // Declarations
  39
  40 // Data required to queue a job
  41 struct LuaJobInfo {
  42         // Function to be called in async environment
  43         std::string serializedFunction;
  44         // Parameter to be passed to function
  45         std::string serializedParams;
  46         // Result of function call
  47         std::string serializedResult;
  48         // JobID used to identify a job and match it to callback
  49         unsigned int id;
  50
  51         bool valid;
  52 };
  53
  54 // Asynchronous working environment
  55 class AsyncWorkerThread : public JThread, public ScriptApiBase {
  56 public:
  57         /**
  58          * default constructor
  59          * @param pointer to job dispatcher
  60          */
  61         AsyncWorkerThread(AsyncEngine* jobDispatcher, unsigned int threadNum);
  62
  63         virtual ~AsyncWorkerThread();
  64
  65         void *Thread();
  66
  67 private:
  68         AsyncEngine *jobDispatcher;
  69
  70         // Thread number. Used for debug output
  71         unsigned int threadnum;
  72
  73 };
  74
  75 // Asynchornous thread and job management
  76 class AsyncEngine {
  77         friend class AsyncWorkerThread;
  78 public:
  79         AsyncEngine();
  80         ~AsyncEngine();
  81
  82         /**
  83          * Register function to be used within engine
  84          * @param name Function name to be used within Lua environment
  85          * @param func C function to be called
  86          */
  87         bool registerFunction(const char* name, lua_CFunction func);
  88
  89         /**
  90          * Create async engine tasks and lock function registration
  91          * @param numEngines Number of async threads to be started
  92          */
  93         void initialize(unsigned int numEngines);
  94
  95         /**
  96          * Queue an async job
  97          * @param func Serialized lua function
  98          * @param params Serialized parameters
  99          * @return jobid The job is queued
 100          */
 101         unsigned int queueAsyncJob(std::string func, std::string params);
 102
 103         /**
 104          * Engine step to process finished jobs
 105          *   the engine step is one way to pass events back, PushFinishedJobs another
 106          * @param L The Lua stack
 107          * @param errorhandler Stack index of the Lua error handler
 108          */
 109         void step(lua_State *L, int errorhandler);
 110
 111         /**
 112          * Push a list of finished jobs onto the stack
 113          * @param L The Lua stack
 114          */
 115         void pushFinishedJobs(lua_State *L);
 116
 117 protected:
 118         /**
 119          * Get a Job from queue to be processed
 120          *  this function blocks until a job is ready
 121          * @return a job to be processed
 122          */
 123         LuaJobInfo getJob();
 124
 125         /**
 126          * Put a Job result back to result queue
 127          * @param result result of completed job
 128          */
 129         void putJobResult(LuaJobInfo result);
 130
 131         /**
 132          * Initialize environment with current registred functions
 133          *  this function adds all functions registred by registerFunction to the
 134          *  passed lua stack
 135          * @param L Lua stack to initialize
 136          * @param top Stack position
 137          */
 138         void prepareEnvironment(lua_State* L, int top);
 139
 140 private:
 141         // Variable locking the engine against further modification
 142         bool initDone;
 143
 144         // Internal store for registred functions
 145         std::map<std::string, lua_CFunction> functionList;
 146
 147         // Internal counter to create job IDs
 148         unsigned int jobIdCounter;
 149
 150         // Mutex to protect job queue
 151         JMutex jobQueueMutex;
 152
 153         // Job queue
 154         std::deque<LuaJobInfo> jobQueue;
 155
 156         // Mutex to protect result queue
 157         JMutex resultQueueMutex;
 158         // Result queue
 159         std::deque<LuaJobInfo> resultQueue;
 160
 161         // List of current worker threads
 162         std::vector<AsyncWorkerThread*> workerThreads;
 163
 164         // Counter semaphore for job dispatching
 165         JSemaphore jobQueueCounter;
 166 };
 167
 168 #endif // CPP_API_ASYNC_EVENTS_HEADER