diff options
Diffstat (limited to 'common/coroutines.h')
| -rw-r--r-- | common/coroutines.h | 161 |
1 files changed, 143 insertions, 18 deletions
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); }; |