From c6810c174e06aa85fc58808f916c6e9cd1d989ea Mon Sep 17 00:00:00 2001 From: Paul Gilbert Date: Fri, 11 May 2012 23:08:27 +1000 Subject: COMMON: Moved the Tinsel Coroutine code into it's own Common class --- common/coroutines.h | 398 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 398 insertions(+) create mode 100644 common/coroutines.h (limited to 'common/coroutines.h') diff --git a/common/coroutines.h b/common/coroutines.h new file mode 100644 index 0000000000..3303028e1c --- /dev/null +++ b/common/coroutines.h @@ -0,0 +1,398 @@ +/* ScummVM - Graphic Adventure Engine + * + * ScummVM is the legal property of its developers, whose names + * are too numerous to list here. Please refer to the COPYRIGHT + * file distributed with this source distribution. + * + * This program is free software; you can redistribute it and/or + * modify it under the terms of the GNU General Public License + * as published by the Free Software Foundation; either version 2 + * 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 General Public License for more details. + * + * You should have received a copy of the GNU 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 COMMON_COROUTINES_H +#define COMMON_COROUTINES_H + +#include "common/scummsys.h" +#include "common/util.h" // for SCUMMVM_CURRENT_FUNCTION +#include "common/list.h" +#include "common/singleton.h" + +namespace Common { + +/** + * @defgroup Coroutine support for simulating multi-threading. + * + * The following is loosely based on an article by Simon Tatham: + * . + * However, many improvements and tweaks have been made, in particular + * by taking advantage of C++ features not available in C. + */ +//@{ + +#define CoroScheduler (Common::CoroutineScheduler::instance()) + + +// Enable this macro to enable some debugging support in the coroutine code. +//#define COROUTINE_DEBUG 1 + +/** + * The core of any coroutine context which captures the 'state' of a coroutine. + * Private use only. + */ +struct CoroBaseContext { + int _line; + int _sleep; + CoroBaseContext *_subctx; +#if COROUTINE_DEBUG + const char *_funcName; +#endif + CoroBaseContext(const char *func); + ~CoroBaseContext(); +}; + +typedef CoroBaseContext *CoroContext; + + +/** This is a special constant that can be temporarily used as a parameter to call coroutine-ised + * from methods from methods that haven't yet been converted to being a coroutine, so code at least + * compiles correctly. Be aware, though, that if you use this, you will get runtime errors. + */ +extern CoroContext nullContext; + +/** + * Wrapper class which holds a pointer to a pointer to a CoroBaseContext. + * The interesting part is the destructor, which kills the context being held, + * but ONLY if the _sleep val of that context is zero. This way, a coroutine + * can just 'return' w/o having to worry about freeing the allocated context + * (in Simon Tatham's original code, one had to use a special macro to + * return from a coroutine). + */ +class CoroContextHolder { + CoroContext &_ctx; +public: + CoroContextHolder(CoroContext &ctx) : _ctx(ctx) { + assert(ctx); + assert(ctx->_sleep >= 0); + ctx->_sleep = 0; + } + ~CoroContextHolder() { + if (_ctx && _ctx->_sleep == 0) { + delete _ctx; + _ctx = 0; + } + } +}; + +/** Methods that have been converted to being a coroutine should have this as the first parameter */ +#define CORO_PARAM Common::CoroContext &coroParam + + +/** + * Begin the declaration of a coroutine context. + * This allows declaring variables which are 'persistent' during the + * lifetime of the coroutine. An example use would be: + * + * CORO_BEGIN_CONTEXT; + * int var; + * char *foo; + * CORO_END_CONTEXT(_ctx); + * + * It is not possible to initialize variables here, due to the way this + * macro is implemented. Furthermore, to use the variables declared in + * the coroutine context, you have to access them via the context variable + * name that was specified as parameter to CORO_END_CONTEXT, e.g. + * _ctx->var = 0; + * + * @see CORO_END_CONTEXT + * + * @note We declare a variable 'DUMMY' to allow the user to specify an 'empty' + * context, and so compilers won't complain about ";" following the macro. + */ +#define CORO_BEGIN_CONTEXT \ + struct CoroContextTag : Common::CoroBaseContext { \ + CoroContextTag() : CoroBaseContext(SCUMMVM_CURRENT_FUNCTION) {} \ + int DUMMY + +/** + * End the declaration of a coroutine context. + * @param x name of the coroutine context + * @see CORO_BEGIN_CONTEXT + */ +#define CORO_END_CONTEXT(x) } *x = (CoroContextTag *)coroParam + +/** + * Begin the code section of a coroutine. + * @param x name of the coroutine context + * @see CORO_BEGIN_CODE + */ +#define CORO_BEGIN_CODE(x) \ + if (&coroParam == &Common::nullContext) assert(!Common::nullContext);\ + if (!x) {coroParam = x = new CoroContextTag();}\ + Common::CoroContextHolder tmpHolder(coroParam);\ + switch (coroParam->_line) { case 0:; + +/** + * End the code section of a coroutine. + * @see CORO_END_CODE + */ +#define CORO_END_CODE \ + if (&coroParam == &Common::nullContext) { \ + delete Common::nullContext; \ + Common::nullContext = NULL; \ + } \ + } + +/** + * Sleep for the specified number of scheduler cycles. + */ +#define CORO_SLEEP(delay) do {\ + coroParam->_line = __LINE__;\ + coroParam->_sleep = delay;\ + assert(&coroParam != &Common::nullContext);\ + return; case __LINE__:;\ + } while (0) + +#define CORO_GIVE_WAY do { CoroScheduler.giveWay(); CORO_SLEEP(1); } while (0) +#define CORO_RESCHEDULE do { CoroScheduler.reschedule(); CORO_SLEEP(1); } while (0) + +/** + * Stop the currently running coroutine and all calling coroutines. + * + * This sets _sleep to -1 rather than 0 so that the context doesn't get + * deleted by CoroContextHolder, since we want CORO_INVOKE_ARGS to + * propogate the _sleep value and return immediately (the scheduler will + * then delete the entire coroutine's state, including all subcontexts). + */ +#define CORO_KILL_SELF() \ + do { if (&coroParam != &Common::nullContext) { coroParam->_sleep = -1; } return; } while (0) + + +/** + * This macro is to be used in conjunction with CORO_INVOKE_ARGS and + * similar macros for calling coroutines-enabled subroutines. + */ +#define CORO_SUBCTX coroParam->_subctx + +/** + * Invoke another coroutine. + * + * If the subcontext still exists after the coroutine is invoked, it has + * either yielded/slept or killed itself, and so we copy the _sleep value + * to our own context and return (execution will continue at the case + * statement below, where we loop and call the coroutine again). + * If the subcontext is null, the coroutine ended normally, and we can + * simply break out of the loop and continue execution. + * + * @param subCoro name of the coroutine-enabled function to invoke + * @param ARGS list of arguments to pass to subCoro + * + * @note ARGS must be surrounded by parentheses, and the first argument + * in this list must always be CORO_SUBCTX. For example, the + * regular function call + * myFunc(a, b); + * becomes the following: + * CORO_INVOKE_ARGS(myFunc, (CORO_SUBCTX, a, b)); + */ +#define CORO_INVOKE_ARGS(subCoro, ARGS) \ + do {\ + coroParam->_line = __LINE__;\ + coroParam->_subctx = 0;\ + do {\ + subCoro ARGS;\ + if (!coroParam->_subctx) break;\ + coroParam->_sleep = coroParam->_subctx->_sleep;\ + assert(&coroParam != &Common::nullContext);\ + return; case __LINE__:;\ + } while (1);\ + } while (0) + +/** + * Invoke another coroutine. Similar to CORO_INVOKE_ARGS, + * but allows specifying a return value which is returned + * if invoked coroutine yields (thus causing the current + * coroutine to yield, too). + */ +#define CORO_INVOKE_ARGS_V(subCoro, RESULT, ARGS) \ + do {\ + coroParam->_line = __LINE__;\ + coroParam->_subctx = 0;\ + do {\ + subCoro ARGS;\ + if (!coroParam->_subctx) break;\ + coroParam->_sleep = coroParam->_subctx->_sleep;\ + assert(&coroParam != &Common::nullContext);\ + return RESULT; case __LINE__:;\ + } while (1);\ + } while (0) + +/** + * Convenience wrapper for CORO_INVOKE_ARGS for invoking a coroutine + * with no parameters. + */ +#define CORO_INVOKE_0(subCoroutine) \ + CORO_INVOKE_ARGS(subCoroutine,(CORO_SUBCTX)) + +/** + * Convenience wrapper for CORO_INVOKE_ARGS for invoking a coroutine + * with one parameter. + */ +#define CORO_INVOKE_1(subCoroutine, a0) \ + CORO_INVOKE_ARGS(subCoroutine,(CORO_SUBCTX,a0)) + +/** + * Convenience wrapper for CORO_INVOKE_ARGS for invoking a coroutine + * with two parameters. + */ +#define CORO_INVOKE_2(subCoroutine, a0,a1) \ + CORO_INVOKE_ARGS(subCoroutine,(CORO_SUBCTX,a0,a1)) + +/** + * Convenience wrapper for CORO_INVOKE_ARGS for invoking a coroutine + * with three parameters. + */ +#define CORO_INVOKE_3(subCoroutine, a0,a1,a2) \ + CORO_INVOKE_ARGS(subCoroutine,(CORO_SUBCTX,a0,a1,a2)) + +/** + * Convenience wrapper for CORO_INVOKE_ARGS for invoking a coroutine + * with four parameters. + */ +#define CORO_INVOKE_4(subCoroutine, a0,a1,a2,a3) \ + CORO_INVOKE_ARGS(subCoroutine,(CORO_SUBCTX,a0,a1,a2,a3)) + + + +// the size of process specific info +#define CORO_PARAM_SIZE 32 + +// the maximum number of processes +#define CORO_NUM_PROCESS 100 +#define CORO_MAX_PROCESSES 100 + +#define CORO_INFINITE 0xffffffff +#define CORO_INVALID_PID_VALUE 0 + +typedef void (*CORO_ADDR)(CoroContext &, const void *); + +/** process structure */ +struct PROCESS { + PROCESS *pNext; ///< pointer to next process in active or free list + PROCESS *pPrevious; ///< pointer to previous process in active or free list + + CoroContext state; ///< the state of the coroutine + CORO_ADDR coroAddr; ///< the entry point of the coroutine + + int sleepTime; ///< number of scheduler cycles to sleep + uint32 pid; ///< process ID + bool waiting; ///< process is currently in a waiting state + char param[CORO_PARAM_SIZE]; ///< process specific info +}; +typedef PROCESS *PPROCESS; + + +/** Event structure */ +struct EVENT { + uint32 pid; + bool manualReset; + bool signalled; +}; + + +/** + * Creates and manages "processes" (really coroutines). + */ +class CoroutineScheduler: public Singleton { +public: + /** Pointer to a function of the form "void function(PPROCESS)" */ + typedef void (*VFPTRPP)(PROCESS *); + +private: + + /** list of all processes */ + PROCESS *processList; + + /** active process list - also saves scheduler state */ + PROCESS *active; + + /** pointer to free process list */ + PROCESS *pFreeProcesses; + + /** the currently active process */ + PROCESS *pCurrent; + + /** Auto-incrementing process Id */ + int pidCounter; + + /** Event list */ + Common::List _events; + +#ifdef DEBUG + // diagnostic process counters + int numProcs; + int maxProcs; + + void CheckStack(); +#endif + + /** + * Called from killProcess() to enable other resources + * a process may be allocated to be released. + */ + VFPTRPP pRCfunction; + + PROCESS *getProcess(uint32 pid); + EVENT *getEvent(uint32 pid); +public: + + CoroutineScheduler(); + ~CoroutineScheduler(); + + void reset(); + + #ifdef DEBUG + void printStats(); + #endif + + void schedule(); + void rescheduleAll(); + void reschedule(PPROCESS pReSchedProc = NULL); + void giveWay(PPROCESS pReSchedProc = NULL); + void waitForSingleObject(CORO_PARAM, int pid, uint32 duration, bool *expired = NULL); + void waitForMultipleObjects(CORO_PARAM, int nCount, uint32 *pidList, bool bWaitAll, + uint32 duration, bool *expired = NULL); + void sleep(CORO_PARAM, uint32 duration); + + PROCESS *createProcess(uint32 pid, CORO_ADDR coroAddr, const void *pParam, int sizeParam); + uint32 createProcess(CORO_ADDR coroAddr, const void *pParam, int sizeParam); + uint32 createProcess(CORO_ADDR coroAddr, const void *pParam); + void killProcess(PROCESS *pKillProc); + + PROCESS *getCurrentProcess(); + int getCurrentPID() const; + int killMatchingProcess(uint32 pidKill, int pidMask = -1); + + void setResourceCallback(VFPTRPP pFunc); + + /* Event methods */ + uint32 createEvent(bool bManualReset, bool bInitialState); + void closeEvent(uint32 pidEvent); + void setEvent(uint32 pidEvent); + void resetEvent(uint32 pidEvent); + void pulseEvent(uint32 pidEvent); +}; + +//@} + +} // end of namespace Common + +#endif // COMMON_COROUTINES_H -- cgit v1.2.3 From 8153d7868b048bcea6df6e8e6c8227ccda0b83dc Mon Sep 17 00:00:00 2001 From: Paul Gilbert Date: Sun, 13 May 2012 00:19:04 +1000 Subject: COMMON: Improved waiting processes to store what PIDs they're waiting for This is then used in PulseEvent to only execute processes that are specifically waiting on the given PID, rather than all waiting events. --- common/coroutines.h | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'common/coroutines.h') diff --git a/common/coroutines.h b/common/coroutines.h index 3303028e1c..80748e352d 100644 --- a/common/coroutines.h +++ b/common/coroutines.h @@ -278,6 +278,7 @@ public: // the maximum number of processes #define CORO_NUM_PROCESS 100 #define CORO_MAX_PROCESSES 100 +#define CORO_MAX_PID_WAITING 5 #define CORO_INFINITE 0xffffffff #define CORO_INVALID_PID_VALUE 0 @@ -294,7 +295,7 @@ struct PROCESS { int sleepTime; ///< number of scheduler cycles to sleep uint32 pid; ///< process ID - bool waiting; ///< process is currently in a waiting state + uint32 pidWaiting[CORO_MAX_PID_WAITING]; ///< Process ID(s) process is currently waiting on char param[CORO_PARAM_SIZE]; ///< process specific info }; typedef PROCESS *PPROCESS; -- cgit v1.2.3 From bd5b65f0071ecb907a8930cff8e91e565b990fb9 Mon Sep 17 00:00:00 2001 From: Paul Gilbert Date: Sun, 13 May 2012 18:19:40 +1000 Subject: COMMON: Fix compilation of coroutines code when COROUTINE_DEBUG is defined --- common/coroutines.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'common/coroutines.h') diff --git a/common/coroutines.h b/common/coroutines.h index 80748e352d..fed82bf3f9 100644 --- a/common/coroutines.h +++ b/common/coroutines.h @@ -43,7 +43,7 @@ namespace Common { // Enable this macro to enable some debugging support in the coroutine code. -//#define COROUTINE_DEBUG 1 +//#define COROUTINE_DEBUG /** * The core of any coroutine context which captures the 'state' of a coroutine. @@ -53,7 +53,7 @@ struct CoroBaseContext { int _line; int _sleep; CoroBaseContext *_subctx; -#if COROUTINE_DEBUG +#ifdef COROUTINE_DEBUG const char *_funcName; #endif CoroBaseContext(const char *func); -- cgit v1.2.3 From 2341570e04e50fbe3c07af349cfe21534ccc4ea7 Mon Sep 17 00:00:00 2001 From: Paul Gilbert Date: Sun, 13 May 2012 18:51:41 +1000 Subject: COMMON: Converted Coro context structure definitions to instead use classes. This fixes a known problem with class variables declared in a method's context definition were not having their destructors called. --- common/coroutines.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'common/coroutines.h') diff --git a/common/coroutines.h b/common/coroutines.h index fed82bf3f9..6df843887c 100644 --- a/common/coroutines.h +++ b/common/coroutines.h @@ -57,7 +57,7 @@ struct CoroBaseContext { const char *_funcName; #endif CoroBaseContext(const char *func); - ~CoroBaseContext(); + virtual ~CoroBaseContext(); }; typedef CoroBaseContext *CoroContext; -- cgit v1.2.3 From a2b51174aad31f66280da91e9c7ec25babd045e6 Mon Sep 17 00:00:00 2001 From: Paul Gilbert Date: Fri, 25 May 2012 23:36:18 +1000 Subject: COMMON: Cleaned up coroutine comments --- common/coroutines.h | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'common/coroutines.h') diff --git a/common/coroutines.h b/common/coroutines.h index 6df843887c..06af245ba7 100644 --- a/common/coroutines.h +++ b/common/coroutines.h @@ -65,7 +65,8 @@ typedef CoroBaseContext *CoroContext; /** This is a special constant that can be temporarily used as a parameter to call coroutine-ised * from methods from methods that haven't yet been converted to being a coroutine, so code at least - * compiles correctly. Be aware, though, that if you use this, you will get runtime errors. + * compiles correctly. Be aware, though, that an error will occur if a coroutine that was passed + * the nullContext tries to sleep or yield control. */ extern CoroContext nullContext; @@ -283,6 +284,7 @@ public: #define CORO_INFINITE 0xffffffff #define CORO_INVALID_PID_VALUE 0 +/** Coroutine parameter for methods converted to coroutines */ typedef void (*CORO_ADDR)(CoroContext &, const void *); /** process structure */ -- cgit v1.2.3 From 415831987d542e249ef9032fdab49bece24934fa Mon Sep 17 00:00:00 2001 From: Paul Gilbert Date: Tue, 29 May 2012 21:51:10 +1000 Subject: COMMON: Copied coroutine doxygen method descriptions to the header file --- common/coroutines.h | 34 ++++++++++++++++++++++++++++++++-- 1 file changed, 32 insertions(+), 2 deletions(-) (limited to 'common/coroutines.h') diff --git a/common/coroutines.h b/common/coroutines.h index 06af245ba7..5daec4b426 100644 --- a/common/coroutines.h +++ b/common/coroutines.h @@ -356,7 +356,6 @@ private: PROCESS *getProcess(uint32 pid); EVENT *getEvent(uint32 pid); public: - CoroutineScheduler(); ~CoroutineScheduler(); @@ -366,31 +365,62 @@ public: void printStats(); #endif + /** Give all active processes a chance to run */ void schedule(); + + /** Reschedules all the processes to run again this tick */ void rescheduleAll(); + + /** If the specified process has already run on this tick, make it run again on the current tick. */ void reschedule(PPROCESS pReSchedProc = NULL); + + /** Moves the specified process to the end of the dispatch queue, so it can again in the current tick */ void giveWay(PPROCESS pReSchedProc = NULL); + + /** Continously makes a given process wait for another process to finish or event to signal. */ void waitForSingleObject(CORO_PARAM, int pid, uint32 duration, bool *expired = NULL); + + /** Continously makes a given process wait for given prcesses to finished or events to be set */ void waitForMultipleObjects(CORO_PARAM, int nCount, uint32 *pidList, bool bWaitAll, uint32 duration, bool *expired = NULL); - void sleep(CORO_PARAM, uint32 duration); + /** Make the active process sleep for the given duration in milliseconds */ + void sleep(CORO_PARAM, uint32 duration); + + /** Creates a new process. */ PROCESS *createProcess(uint32 pid, CORO_ADDR coroAddr, const void *pParam, int sizeParam); uint32 createProcess(CORO_ADDR coroAddr, const void *pParam, int sizeParam); uint32 createProcess(CORO_ADDR coroAddr, const void *pParam); + + /** Kills the specified process. */ void killProcess(PROCESS *pKillProc); + /** Returns a pointer to the currently running process. */ PROCESS *getCurrentProcess(); + + /** Returns the process identifier of the specified process. */ int getCurrentPID() const; + + /** Kills any process matching the specified PID. The current process cannot be killed. */ int killMatchingProcess(uint32 pidKill, int pidMask = -1); + /** Set pointer to a function to be called by killProcess() */ void setResourceCallback(VFPTRPP pFunc); /* Event methods */ + /** Creates a new event (semaphore) object */ uint32 createEvent(bool bManualReset, bool bInitialState); + + /** Destroys the given event */ void closeEvent(uint32 pidEvent); + + /** Sets the event */ void setEvent(uint32 pidEvent); + + /** Resets the event */ void resetEvent(uint32 pidEvent); + + /** Temporarily sets a given event to true, allowing other waiting processes to fire */ void pulseEvent(uint32 pidEvent); }; -- cgit v1.2.3 From 29ebb2823dfe5fff95c47a2847f11e11bde95fd1 Mon Sep 17 00:00:00 2001 From: Paul Gilbert Date: Thu, 31 May 2012 08:06:59 +1000 Subject: COMMON: Fix comment typo in coroutine comments --- common/coroutines.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'common/coroutines.h') diff --git a/common/coroutines.h b/common/coroutines.h index 5daec4b426..abc114e0cf 100644 --- a/common/coroutines.h +++ b/common/coroutines.h @@ -64,7 +64,7 @@ typedef CoroBaseContext *CoroContext; /** This is a special constant that can be temporarily used as a parameter to call coroutine-ised - * from methods from methods that haven't yet been converted to being a coroutine, so code at least + * methods from code that haven't yet been converted to being a coroutine, so code at least * compiles correctly. Be aware, though, that an error will occur if a coroutine that was passed * the nullContext tries to sleep or yield control. */ -- cgit v1.2.3 From b17b38cc364d13992b3be360a460d5b075e5848e Mon Sep 17 00:00:00 2001 From: Johannes Schickel Date: Thu, 7 Jun 2012 17:50:20 +0200 Subject: COMMON: Move coroutine documentation to the header file. --- common/coroutines.h | 161 ++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 143 insertions(+), 18 deletions(-) (limited to 'common/coroutines.h') diff --git a/common/coroutines.h b/common/coroutines.h index abc114e0cf..f5519902dd 100644 --- a/common/coroutines.h +++ b/common/coroutines.h @@ -56,7 +56,14 @@ struct CoroBaseContext { #ifdef COROUTINE_DEBUG const char *_funcName; #endif + /** + * Creates a coroutine context + */ CoroBaseContext(const char *func); + + /** + * Destructor for coroutine context + */ virtual ~CoroBaseContext(); }; @@ -344,6 +351,10 @@ private: int numProcs; int maxProcs; + /** + * Checks both the active and free process list to insure all the links are valid, + * and that no processes have been lost + */ void CheckStack(); #endif @@ -356,71 +367,185 @@ private: PROCESS *getProcess(uint32 pid); EVENT *getEvent(uint32 pid); public: + /** + * Constructor + */ CoroutineScheduler(); + + /** + * Destructor + */ ~CoroutineScheduler(); + /** + * Kills all processes and places them on the free list. + */ void reset(); #ifdef DEBUG + /** + * Shows the maximum number of process used at once. + */ void printStats(); #endif - /** Give all active processes a chance to run */ + /** + * Give all active processes a chance to run + */ void schedule(); - /** Reschedules all the processes to run again this tick */ + /** + * Reschedules all the processes to run again this tick + */ void rescheduleAll(); - /** If the specified process has already run on this tick, make it run again on the current tick. */ + /** + * If the specified process has already run on this tick, make it run + * again on the current tick. + */ void reschedule(PPROCESS pReSchedProc = NULL); - /** Moves the specified process to the end of the dispatch queue, so it can again in the current tick */ + /** + * Moves the specified process to the end of the dispatch queue + * allowing it to run again within the current game cycle. + * @param pGiveProc Which process + */ void giveWay(PPROCESS pReSchedProc = NULL); - /** Continously makes a given process wait for another process to finish or event to signal. */ + /** + * Continously makes a given process wait for another process to finish or event to signal. + * + * @param pid Process/Event identifier + * @param duration Duration in milliseconds + * @param expired If specified, set to true if delay period expired + */ void waitForSingleObject(CORO_PARAM, int pid, uint32 duration, bool *expired = NULL); - /** Continously makes a given process wait for given prcesses to finished or events to be set */ + /** + * Continously makes a given process wait for given prcesses to finished or events to be set + * + * @param nCount Number of Id's being passed + * @param evtList List of pids to wait for + * @param bWaitAll Specifies whether all or any of the processes/events + * @param duration Duration in milliseconds + * @param expired Set to true if delay period expired + */ void waitForMultipleObjects(CORO_PARAM, int nCount, uint32 *pidList, bool bWaitAll, uint32 duration, bool *expired = NULL); - /** Make the active process sleep for the given duration in milliseconds */ + /** + * Make the active process sleep for the given duration in milliseconds + * + * @param duration Duration in milliseconds + * @remarks This duration won't be precise, since it relies on the frequency the + * scheduler is called. + */ void sleep(CORO_PARAM, uint32 duration); - /** Creates a new process. */ + /** + * Creates a new process. + * + * @param pid process identifier + * @param coroAddr Coroutine start address + * @param pParam Process specific info + * @param sizeParam Size of process specific info + */ PROCESS *createProcess(uint32 pid, CORO_ADDR coroAddr, const void *pParam, int sizeParam); + + /** + * Creates a new process with an auto-incrementing Process Id. + * + * @param coroAddr Coroutine start address + * @param pParam Process specific info + * @param sizeParam Size of process specific info + */ uint32 createProcess(CORO_ADDR coroAddr, const void *pParam, int sizeParam); + + /** + * Creates a new process with an auto-incrementing Process Id, and a single pointer parameter. + * + * @param coroAddr Coroutine start address + * @param pParam Process specific info + */ uint32 createProcess(CORO_ADDR coroAddr, const void *pParam); - /** Kills the specified process. */ + /** + * Kills the specified process. + * + * @param pKillProc Which process to kill + */ void killProcess(PROCESS *pKillProc); - /** Returns a pointer to the currently running process. */ + /** + * Returns a pointer to the currently running process. + */ PROCESS *getCurrentProcess(); - /** Returns the process identifier of the specified process. */ + /** + * Returns the process identifier of the currently running process. + */ int getCurrentPID() const; - /** Kills any process matching the specified PID. The current process cannot be killed. */ + /** + * Kills any process matching the specified PID. The current + * process cannot be killed. + * + * @param pidKill Process identifier of process to kill + * @param pidMask Mask to apply to process identifiers before comparison + * @return The number of processes killed is returned. + */ int killMatchingProcess(uint32 pidKill, int pidMask = -1); - /** Set pointer to a function to be called by killProcess() */ + /** + * Set pointer to a function to be called by killProcess(). + * + * May be called by a resource allocator, the function supplied is + * called by killProcess() to allow the resource allocator to free + * resources allocated to the dying process. + * + * @param pFunc Function to be called by killProcess() + */ void setResourceCallback(VFPTRPP pFunc); /* Event methods */ - /** Creates a new event (semaphore) object */ + /** + * Creates a new event (semaphore) object + * + * @param bManualReset Events needs to be manually reset. Otherwise, + * events will be automatically reset after a + * process waits on the event finishes + * @param bInitialState Specifies whether the event is signalled or not + * initially + */ uint32 createEvent(bool bManualReset, bool bInitialState); - /** Destroys the given event */ + /** + * Destroys the given event + * @param pidEvent Event Process Id + */ void closeEvent(uint32 pidEvent); - /** Sets the event */ + /** + * Sets the event + * @param pidEvent Event Process Id + */ void setEvent(uint32 pidEvent); - /** Resets the event */ + /** + * Resets the event + * @param pidEvent Event Process Id + */ void resetEvent(uint32 pidEvent); - /** Temporarily sets a given event to true, allowing other waiting processes to fire */ + /** + * Temporarily sets a given event to true, and then runs all waiting + * processes,allowing any processes waiting on the event to be fired. It + * then immediately resets the event again. + * + * @param pidEvent Event Process Id + * + * @remarks Should not be run inside of another process + */ void pulseEvent(uint32 pidEvent); }; -- cgit v1.2.3 From 27aa0974499c6012da894872913f4f44cf6b6a5c Mon Sep 17 00:00:00 2001 From: Johannes Schickel Date: Thu, 7 Jun 2012 17:51:58 +0200 Subject: COMMON: Slightly adapt coroutine code to better match our guidelines. I used astyle here, which automatically removes the use of tabs in comments. --- common/coroutines.h | 203 ++++++++++++++++++++++++++-------------------------- 1 file changed, 102 insertions(+), 101 deletions(-) (limited to 'common/coroutines.h') diff --git a/common/coroutines.h b/common/coroutines.h index f5519902dd..3b8b1a77f9 100644 --- a/common/coroutines.h +++ b/common/coroutines.h @@ -23,7 +23,7 @@ #define COMMON_COROUTINES_H #include "common/scummsys.h" -#include "common/util.h" // for SCUMMVM_CURRENT_FUNCTION +#include "common/util.h" // for SCUMMVM_CURRENT_FUNCTION #include "common/list.h" #include "common/singleton.h" @@ -133,42 +133,43 @@ public: /** * End the declaration of a coroutine context. - * @param x name of the coroutine context + * @param x name of the coroutine context * @see CORO_BEGIN_CONTEXT */ #define CORO_END_CONTEXT(x) } *x = (CoroContextTag *)coroParam /** * Begin the code section of a coroutine. - * @param x name of the coroutine context + * @param x name of the coroutine context * @see CORO_BEGIN_CODE */ #define CORO_BEGIN_CODE(x) \ - if (&coroParam == &Common::nullContext) assert(!Common::nullContext);\ - if (!x) {coroParam = x = new CoroContextTag();}\ - Common::CoroContextHolder tmpHolder(coroParam);\ - switch (coroParam->_line) { case 0:; + if (&coroParam == &Common::nullContext) assert(!Common::nullContext); \ + if (!x) { coroParam = x = new CoroContextTag(); } \ + Common::CoroContextHolder tmpHolder(coroParam); \ + switch (coroParam->_line) { case 0:; /** * End the code section of a coroutine. * @see CORO_END_CODE */ #define CORO_END_CODE \ - if (&coroParam == &Common::nullContext) { \ - delete Common::nullContext; \ - Common::nullContext = NULL; \ - } \ - } + if (&coroParam == &Common::nullContext) { \ + delete Common::nullContext; \ + Common::nullContext = NULL; \ + } \ + } /** * Sleep for the specified number of scheduler cycles. */ -#define CORO_SLEEP(delay) do {\ - coroParam->_line = __LINE__;\ - coroParam->_sleep = delay;\ - assert(&coroParam != &Common::nullContext);\ - return; case __LINE__:;\ - } while (0) +#define CORO_SLEEP(delay) \ + do { \ + coroParam->_line = __LINE__; \ + coroParam->_sleep = delay; \ + assert(&coroParam != &Common::nullContext); \ + return; case __LINE__:; \ + } while (0) #define CORO_GIVE_WAY do { CoroScheduler.giveWay(); CORO_SLEEP(1); } while (0) #define CORO_RESCHEDULE do { CoroScheduler.reschedule(); CORO_SLEEP(1); } while (0) @@ -182,7 +183,7 @@ public: * then delete the entire coroutine's state, including all subcontexts). */ #define CORO_KILL_SELF() \ - do { if (&coroParam != &Common::nullContext) { coroParam->_sleep = -1; } return; } while (0) + do { if (&coroParam != &Common::nullContext) { coroParam->_sleep = -1; } return; } while (0) /** @@ -201,8 +202,8 @@ public: * If the subcontext is null, the coroutine ended normally, and we can * simply break out of the loop and continue execution. * - * @param subCoro name of the coroutine-enabled function to invoke - * @param ARGS list of arguments to pass to subCoro + * @param subCoro name of the coroutine-enabled function to invoke + * @param ARGS list of arguments to pass to subCoro * * @note ARGS must be surrounded by parentheses, and the first argument * in this list must always be CORO_SUBCTX. For example, the @@ -211,18 +212,18 @@ public: * becomes the following: * CORO_INVOKE_ARGS(myFunc, (CORO_SUBCTX, a, b)); */ -#define CORO_INVOKE_ARGS(subCoro, ARGS) \ - do {\ - coroParam->_line = __LINE__;\ - coroParam->_subctx = 0;\ - do {\ - subCoro ARGS;\ - if (!coroParam->_subctx) break;\ - coroParam->_sleep = coroParam->_subctx->_sleep;\ - assert(&coroParam != &Common::nullContext);\ - return; case __LINE__:;\ - } while (1);\ - } while (0) +#define CORO_INVOKE_ARGS(subCoro, ARGS) \ + do { \ + coroParam->_line = __LINE__; \ + coroParam->_subctx = 0; \ + do { \ + subCoro ARGS; \ + if (!coroParam->_subctx) break; \ + coroParam->_sleep = coroParam->_subctx->_sleep; \ + assert(&coroParam != &Common::nullContext); \ + return; case __LINE__:; \ + } while (1); \ + } while (0) /** * Invoke another coroutine. Similar to CORO_INVOKE_ARGS, @@ -230,62 +231,62 @@ public: * if invoked coroutine yields (thus causing the current * coroutine to yield, too). */ -#define CORO_INVOKE_ARGS_V(subCoro, RESULT, ARGS) \ - do {\ - coroParam->_line = __LINE__;\ - coroParam->_subctx = 0;\ - do {\ - subCoro ARGS;\ - if (!coroParam->_subctx) break;\ - coroParam->_sleep = coroParam->_subctx->_sleep;\ - assert(&coroParam != &Common::nullContext);\ - return RESULT; case __LINE__:;\ - } while (1);\ - } while (0) +#define CORO_INVOKE_ARGS_V(subCoro, RESULT, ARGS) \ + do { \ + coroParam->_line = __LINE__; \ + coroParam->_subctx = 0; \ + do { \ + subCoro ARGS; \ + if (!coroParam->_subctx) break; \ + coroParam->_sleep = coroParam->_subctx->_sleep; \ + assert(&coroParam != &Common::nullContext); \ + return RESULT; case __LINE__:; \ + } while (1); \ + } while (0) /** * Convenience wrapper for CORO_INVOKE_ARGS for invoking a coroutine * with no parameters. */ #define CORO_INVOKE_0(subCoroutine) \ - CORO_INVOKE_ARGS(subCoroutine,(CORO_SUBCTX)) + CORO_INVOKE_ARGS(subCoroutine, (CORO_SUBCTX)) /** * Convenience wrapper for CORO_INVOKE_ARGS for invoking a coroutine * with one parameter. */ #define CORO_INVOKE_1(subCoroutine, a0) \ - CORO_INVOKE_ARGS(subCoroutine,(CORO_SUBCTX,a0)) + CORO_INVOKE_ARGS(subCoroutine, (CORO_SUBCTX, a0)) /** * Convenience wrapper for CORO_INVOKE_ARGS for invoking a coroutine * with two parameters. */ #define CORO_INVOKE_2(subCoroutine, a0,a1) \ - CORO_INVOKE_ARGS(subCoroutine,(CORO_SUBCTX,a0,a1)) + CORO_INVOKE_ARGS(subCoroutine, (CORO_SUBCTX, a0, a1)) /** * Convenience wrapper for CORO_INVOKE_ARGS for invoking a coroutine * with three parameters. */ #define CORO_INVOKE_3(subCoroutine, a0,a1,a2) \ - CORO_INVOKE_ARGS(subCoroutine,(CORO_SUBCTX,a0,a1,a2)) + CORO_INVOKE_ARGS(subCoroutine, (CORO_SUBCTX, a0, a1, a2)) /** * Convenience wrapper for CORO_INVOKE_ARGS for invoking a coroutine * with four parameters. */ #define CORO_INVOKE_4(subCoroutine, a0,a1,a2,a3) \ - CORO_INVOKE_ARGS(subCoroutine,(CORO_SUBCTX,a0,a1,a2,a3)) + CORO_INVOKE_ARGS(subCoroutine, (CORO_SUBCTX, a0, a1, a2, a3)) // the size of process specific info -#define CORO_PARAM_SIZE 32 +#define CORO_PARAM_SIZE 32 // the maximum number of processes -#define CORO_NUM_PROCESS 100 -#define CORO_MAX_PROCESSES 100 +#define CORO_NUM_PROCESS 100 +#define CORO_MAX_PROCESSES 100 #define CORO_MAX_PID_WAITING 5 #define CORO_INFINITE 0xffffffff @@ -296,16 +297,16 @@ typedef void (*CORO_ADDR)(CoroContext &, const void *); /** process structure */ struct PROCESS { - PROCESS *pNext; ///< pointer to next process in active or free list - PROCESS *pPrevious; ///< pointer to previous process in active or free list + PROCESS *pNext; ///< pointer to next process in active or free list + PROCESS *pPrevious; ///< pointer to previous process in active or free list - CoroContext state; ///< the state of the coroutine - CORO_ADDR coroAddr; ///< the entry point of the coroutine + CoroContext state; ///< the state of the coroutine + CORO_ADDR coroAddr; ///< the entry point of the coroutine - int sleepTime; ///< number of scheduler cycles to sleep - uint32 pid; ///< process ID - uint32 pidWaiting[CORO_MAX_PID_WAITING]; ///< Process ID(s) process is currently waiting on - char param[CORO_PARAM_SIZE]; ///< process specific info + int sleepTime; ///< number of scheduler cycles to sleep + uint32 pid; ///< process ID + uint32 pidWaiting[CORO_MAX_PID_WAITING]; ///< Process ID(s) process is currently waiting on + char param[CORO_PARAM_SIZE]; ///< process specific info }; typedef PROCESS *PPROCESS; @@ -321,7 +322,7 @@ struct EVENT { /** * Creates and manages "processes" (really coroutines). */ -class CoroutineScheduler: public Singleton { +class CoroutineScheduler : public Singleton { public: /** Pointer to a function of the form "void function(PPROCESS)" */ typedef void (*VFPTRPP)(PROCESS *); @@ -355,7 +356,7 @@ private: * Checks both the active and free process list to insure all the links are valid, * and that no processes have been lost */ - void CheckStack(); + void checkStack(); #endif /** @@ -382,12 +383,12 @@ public: */ void reset(); - #ifdef DEBUG +#ifdef DEBUG /** * Shows the maximum number of process used at once. */ void printStats(); - #endif +#endif /** * Give all active processes a chance to run @@ -408,71 +409,71 @@ public: /** * Moves the specified process to the end of the dispatch queue * allowing it to run again within the current game cycle. - * @param pGiveProc Which process + * @param pGiveProc Which process */ void giveWay(PPROCESS pReSchedProc = NULL); /** * Continously makes a given process wait for another process to finish or event to signal. * - * @param pid Process/Event identifier - * @param duration Duration in milliseconds - * @param expired If specified, set to true if delay period expired + * @param pid Process/Event identifier + * @param duration Duration in milliseconds + * @param expired If specified, set to true if delay period expired */ void waitForSingleObject(CORO_PARAM, int pid, uint32 duration, bool *expired = NULL); /** * Continously makes a given process wait for given prcesses to finished or events to be set * - * @param nCount Number of Id's being passed - * @param evtList List of pids to wait for - * @param bWaitAll Specifies whether all or any of the processes/events - * @param duration Duration in milliseconds - * @param expired Set to true if delay period expired + * @param nCount Number of Id's being passed + * @param evtList List of pids to wait for + * @param bWaitAll Specifies whether all or any of the processes/events + * @param duration Duration in milliseconds + * @param expired Set to true if delay period expired */ - void waitForMultipleObjects(CORO_PARAM, int nCount, uint32 *pidList, bool bWaitAll, - uint32 duration, bool *expired = NULL); + void waitForMultipleObjects(CORO_PARAM, int nCount, uint32 *pidList, bool bWaitAll, + uint32 duration, bool *expired = NULL); /** * Make the active process sleep for the given duration in milliseconds * - * @param duration Duration in milliseconds - * @remarks This duration won't be precise, since it relies on the frequency the + * @param duration Duration in milliseconds + * @remarks This duration won't be precise, since it relies on the frequency the * scheduler is called. */ void sleep(CORO_PARAM, uint32 duration); - + /** * Creates a new process. * - * @param pid process identifier - * @param coroAddr Coroutine start address - * @param pParam Process specific info - * @param sizeParam Size of process specific info + * @param pid process identifier + * @param coroAddr Coroutine start address + * @param pParam Process specific info + * @param sizeParam Size of process specific info */ PROCESS *createProcess(uint32 pid, CORO_ADDR coroAddr, const void *pParam, int sizeParam); /** * Creates a new process with an auto-incrementing Process Id. * - * @param coroAddr Coroutine start address - * @param pParam Process specific info - * @param sizeParam Size of process specific info + * @param coroAddr Coroutine start address + * @param pParam Process specific info + * @param sizeParam Size of process specific info */ uint32 createProcess(CORO_ADDR coroAddr, const void *pParam, int sizeParam); /** * Creates a new process with an auto-incrementing Process Id, and a single pointer parameter. * - * @param coroAddr Coroutine start address - * @param pParam Process specific info + * @param coroAddr Coroutine start address + * @param pParam Process specific info */ uint32 createProcess(CORO_ADDR coroAddr, const void *pParam); /** * Kills the specified process. * - * @param pKillProc Which process to kill + * @param pKillProc Which process to kill */ void killProcess(PROCESS *pKillProc); @@ -490,9 +491,9 @@ public: * Kills any process matching the specified PID. The current * process cannot be killed. * - * @param pidKill Process identifier of process to kill - * @param pidMask Mask to apply to process identifiers before comparison - * @return The number of processes killed is returned. + * @param pidKill Process identifier of process to kill + * @param pidMask Mask to apply to process identifiers before comparison + * @return The number of processes killed is returned. */ int killMatchingProcess(uint32 pidKill, int pidMask = -1); @@ -503,7 +504,7 @@ public: * called by killProcess() to allow the resource allocator to free * resources allocated to the dying process. * - * @param pFunc Function to be called by killProcess() + * @param pFunc Function to be called by killProcess() */ void setResourceCallback(VFPTRPP pFunc); @@ -511,29 +512,29 @@ public: /** * Creates a new event (semaphore) object * - * @param bManualReset Events needs to be manually reset. Otherwise, + * @param bManualReset Events needs to be manually reset. Otherwise, * events will be automatically reset after a * process waits on the event finishes - * @param bInitialState Specifies whether the event is signalled or not + * @param bInitialState Specifies whether the event is signalled or not * initially */ uint32 createEvent(bool bManualReset, bool bInitialState); /** * Destroys the given event - * @param pidEvent Event Process Id + * @param pidEvent Event Process Id */ void closeEvent(uint32 pidEvent); /** * Sets the event - * @param pidEvent Event Process Id + * @param pidEvent Event Process Id */ void setEvent(uint32 pidEvent); /** * Resets the event - * @param pidEvent Event Process Id + * @param pidEvent Event Process Id */ void resetEvent(uint32 pidEvent); @@ -542,9 +543,9 @@ public: * processes,allowing any processes waiting on the event to be fired. It * then immediately resets the event again. * - * @param pidEvent Event Process Id + * @param pidEvent Event Process Id * - * @remarks Should not be run inside of another process + * @remarks Should not be run inside of another process */ void pulseEvent(uint32 pidEvent); }; @@ -553,4 +554,4 @@ public: } // end of namespace Common -#endif // COMMON_COROUTINES_H +#endif // COMMON_COROUTINES_H -- cgit v1.2.3 From 8e7f874db35395d100ca73d9433b25f2f7eae19d Mon Sep 17 00:00:00 2001 From: Johannes Schickel Date: Thu, 7 Jun 2012 18:11:38 +0200 Subject: COMMON: Make CoroutineScheduler's constructor and destructor private. CoroutineSchedule is a singleton, thus it should not be possible to create a custom instance of it. --- common/coroutines.h | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) (limited to 'common/coroutines.h') diff --git a/common/coroutines.h b/common/coroutines.h index 3b8b1a77f9..64eabbf8f4 100644 --- a/common/coroutines.h +++ b/common/coroutines.h @@ -328,6 +328,18 @@ public: typedef void (*VFPTRPP)(PROCESS *); private: + friend class Singleton; + + /** + * Constructor + */ + CoroutineScheduler(); + + /** + * Destructor + */ + ~CoroutineScheduler(); + /** list of all processes */ PROCESS *processList; @@ -368,16 +380,6 @@ private: PROCESS *getProcess(uint32 pid); EVENT *getEvent(uint32 pid); public: - /** - * Constructor - */ - CoroutineScheduler(); - - /** - * Destructor - */ - ~CoroutineScheduler(); - /** * Kills all processes and places them on the free list. */ -- cgit v1.2.3 From 269ea2f6be551f3159c1e508e28ebd2a609f5ab0 Mon Sep 17 00:00:00 2001 From: Paul Gilbert Date: Sat, 9 Jun 2012 17:14:21 +1000 Subject: COMMON: Change pulseEvent to better reflect how it works in Windows --- common/coroutines.h | 1 + 1 file changed, 1 insertion(+) (limited to 'common/coroutines.h') diff --git a/common/coroutines.h b/common/coroutines.h index 64eabbf8f4..834c67f6e4 100644 --- a/common/coroutines.h +++ b/common/coroutines.h @@ -316,6 +316,7 @@ struct EVENT { uint32 pid; bool manualReset; bool signalled; + bool pulsing; }; -- cgit v1.2.3