Permalink
Browse files

COMMON: Cleaned up coroutine comments

  • Loading branch information...
1 parent 839527a commit a2b51174aad31f66280da91e9c7ec25babd045e6 @dreammaster dreammaster committed May 25, 2012
Showing with 38 additions and 24 deletions.
  1. +35 −23 common/coroutines.cpp
  2. +3 −1 common/coroutines.h
View
58 common/coroutines.cpp
@@ -37,18 +37,25 @@ DECLARE_SINGLETON(CoroutineScheduler);
#ifdef COROUTINE_DEBUG
namespace {
+/** Count of active coroutines */
static int s_coroCount = 0;
typedef Common::HashMap<Common::String, int> CoroHashMap;
static CoroHashMap *s_coroFuncs = 0;
+/**
+ * Change the current coroutine status
+ */
static void changeCoroStats(const char *func, int change) {
if (!s_coroFuncs)
s_coroFuncs = new CoroHashMap();
(*s_coroFuncs)[func] += change;
}
+/**
+ * Display the details of active coroutines
+ */
static void displayCoroStats() {
debug("%d active coros", s_coroCount);
@@ -65,6 +72,9 @@ static void displayCoroStats() {
}
#endif
+/**
+ * Creates a coroutine context
+ */
CoroBaseContext::CoroBaseContext(const char *func)
: _line(0), _sleep(0), _subctx(0) {
#ifdef COROUTINE_DEBUG
@@ -74,6 +84,9 @@ CoroBaseContext::CoroBaseContext(const char *func)
#endif
}
+/**
+ * Destructor for coroutine context
+ */
CoroBaseContext::~CoroBaseContext() {
#ifdef COROUTINE_DEBUG
s_coroCount--;
@@ -499,7 +512,7 @@ void CoroutineScheduler::waitForMultipleObjects(CORO_PARAM, int nCount, uint32 *
/**
* Make the active process sleep for the given duration in milliseconds
- * @param duration 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.
*/
@@ -530,9 +543,9 @@ void CoroutineScheduler::sleep(CORO_PARAM, uint32 duration) {
* Creates a new process.
*
* @param pid process identifier
- * @param CORO_ADDR coroutine start address
- * @param pParam process specific info
- * @param sizeParam size of process specific info
+ * @param CORO_ADDR Coroutine start address
+ * @param pParam Process specific info
+ * @param sizeParam Size of process specific info
*/
PROCESS *CoroutineScheduler::createProcess(uint32 pid, CORO_ADDR coroAddr, const void *pParam, int sizeParam) {
PROCESS *pProc;
@@ -601,9 +614,9 @@ PROCESS *CoroutineScheduler::createProcess(uint32 pid, CORO_ADDR coroAddr, const
/**
* Creates a new process with an auto-incrementing Process Id.
*
- * @param CORO_ADDR coroutine start address
- * @param pParam process specific info
- * @param sizeParam size of process specific info
+ * @param CORO_ADDR Coroutine start address
+ * @param pParam Process specific info
+ * @param sizeParam Size of process specific info
*/
uint32 CoroutineScheduler::createProcess(CORO_ADDR coroAddr, const void *pParam, int sizeParam) {
PROCESS *pProc = createProcess(++pidCounter, coroAddr, pParam, sizeParam);
@@ -613,9 +626,9 @@ uint32 CoroutineScheduler::createProcess(CORO_ADDR coroAddr, const void *pParam,
/**
* Creates a new process with an auto-incrementing Process Id, and a single pointer parameter.
*
- * @param CORO_ADDR coroutine start address
- * @param pParam process specific info
- * @param sizeParam size of process specific info
+ * @param CORO_ADDR Coroutine start address
+ * @param pParam Process specific info
+ * @param sizeParam Size of process specific info
*/
uint32 CoroutineScheduler::createProcess(CORO_ADDR coroAddr, const void *pParam) {
return createProcess(coroAddr, &pParam, sizeof(void *));
@@ -625,7 +638,7 @@ uint32 CoroutineScheduler::createProcess(CORO_ADDR coroAddr, const void *pParam)
/**
* Kills the specified process.
*
- * @param pKillProc which process to kill
+ * @param pKillProc Which process to kill
*/
void CoroutineScheduler::killProcess(PROCESS *pKillProc) {
// make sure a valid process pointer
@@ -674,7 +687,7 @@ PROCESS *CoroutineScheduler::getCurrentProcess() {
/**
* Returns the process identifier of the specified process.
*
- * @param pProc which process
+ * @param pProc Which process
*/
int CoroutineScheduler::getCurrentPID() const {
PROCESS *pProc = pCurrent;
@@ -690,9 +703,9 @@ int CoroutineScheduler::getCurrentPID() const {
* 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 CoroutineScheduler::killMatchingProcess(uint32 pidKill, int pidMask) {
int numKilled = 0;
@@ -750,7 +763,7 @@ int CoroutineScheduler::killMatchingProcess(uint32 pidKill, int pidMask) {
* 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 CoroutineScheduler::setResourceCallback(VFPTRPP pFunc) {
pRCfunction = pFunc;
@@ -778,9 +791,9 @@ EVENT *CoroutineScheduler::getEvent(uint32 pid) {
/**
* Creates a new event object
- * @param bManualReset Events needs to be manually reset. Otherwise, events
+ * @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
+ * @param bInitialState Specifies whether the event is signalled or not initially
*/
uint32 CoroutineScheduler::createEvent(bool bManualReset, bool bInitialState) {
EVENT *evt = new EVENT();
@@ -794,7 +807,7 @@ uint32 CoroutineScheduler::createEvent(bool bManualReset, bool bInitialState) {
/**
* Destroys the given event
- * @param pidEvent Event PID
+ * @param pidEvent Event Process Id
*/
void CoroutineScheduler::closeEvent(uint32 pidEvent) {
EVENT *evt = getEvent(pidEvent);
@@ -806,7 +819,7 @@ void CoroutineScheduler::closeEvent(uint32 pidEvent) {
/**
* Sets the event
- * @param pidEvent Event PID
+ * @param pidEvent Event Process Id
*/
void CoroutineScheduler::setEvent(uint32 pidEvent) {
EVENT *evt = getEvent(pidEvent);
@@ -816,7 +829,7 @@ void CoroutineScheduler::setEvent(uint32 pidEvent) {
/**
* Resets the event
- * @param pidEvent Event PID
+ * @param pidEvent Event Process Id
*/
void CoroutineScheduler::resetEvent(uint32 pidEvent) {
EVENT *evt = getEvent(pidEvent);
@@ -827,7 +840,7 @@ void CoroutineScheduler::resetEvent(uint32 pidEvent) {
/**
* 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 PID
+ * @param pidEvent Event Process Id
*
* @remarks Should not be run inside of another process
*/
@@ -880,5 +893,4 @@ void CoroutineScheduler::pulseEvent(uint32 pidEvent) {
evt->signalled = false;
}
-
} // end of namespace Common
View
4 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 @@ class CoroContextHolder {
#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 */

0 comments on commit a2b5117

Please sign in to comment.