Minor refactoring and docs

docs/doxyfile

@@ -1935,7 +1935,7 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             =
+PREDEFINED             = anki_internal=private
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The
@@ -1944,7 +1944,7 @@ PREDEFINED             =
 # definition found in the source code.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-EXPAND_AS_DEFINED      =
+EXPAND_AS_DEFINED      = anki_internal=private
 
 # If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will
 # remove all refrences to function-like macros that are alone on a line, have an

include/anki/util/Rtti.h

@@ -43,7 +43,7 @@ struct ExtractType<T*>
 };
 /// @}
 
-/// @addtogroup util_misc
+/// @addtogroup util_other
 /// @{
 
 /// Check if a class is of certain type.

include/anki/util/Thread.h

@@ -79,7 +79,7 @@ private:
 #endif
 };
 
-/// Mutex
+/// Mutual exclusion primitive.
 class Mutex : public NonCopyable
 {
 	friend class ConditionVariable;
@@ -103,7 +103,7 @@ private:
 	void* m_impl = nullptr; ///< The system native type
 };
 
-/// Condition variable
+/// Condition variable.
 class ConditionVariable : public NonCopyable
 {
 public:
@@ -125,8 +125,8 @@ private:
 	void* m_impl = nullptr; ///< The system native type
 };
 
-/// Spin lock. Good if the critical section will be executed in a short period
-/// of time
+/// Mutual exclusion primitive. Like Mutex. It's better than Mutex only if the 
+/// critical section will be executed in a very short period of time.
 class SpinLock : public NonCopyable
 {
 public:
@@ -150,6 +150,7 @@ private:
 
 /// Lock guard. When constructed it locks a TMutex and unlocks it when it gets
 /// destroyed.
+/// @tparam TMutex Can be Mutex or SpinLock.
 template<typename TMutex>
 class LockGuard
 {
@@ -169,7 +170,7 @@ private:
 	TMutex* m_mtx;
 };
 
-/// A barrier for thread synchronization. It works almost like boost::barrier
+/// A barrier for thread synchronization. It works almost like boost::barrier.
 class Barrier : public NonCopyable
 {
 public:

include/anki/util/ThreadHive.h

@@ -19,11 +19,16 @@ class ThreadHiveThread;
 /// @addtogroup util_thread
 /// @{
 
+/// Opaque handle that defines a ThreadHive depedency.
+/// @memberof ThreadHive
 using ThreadHiveDependencyHandle = U16;
 
+/// The callback that defines a ThreadHibe task.
+/// @memberof ThreadHive
 using ThreadHiveTaskCallback = void (*)(void*, U32 threadId, ThreadHive& hive);
 
 /// Task for the ThreadHive.
+/// @memberof ThreadHive
 class ThreadHiveTask
 {
 public:
@@ -41,8 +46,9 @@ public:
 	ThreadHiveDependencyHandle m_outDependency;
 };
 
-/// A scheduler of small tasks. It takes tasks to be executed and schedules them
-/// in one of the threads.
+/// A scheduler of small tasks. It takes a number of tasks and schedules them in 
+/// one of the threads. The tasks can depend on previously submitted tasks or be
+/// completely independent.
 class ThreadHive : public NonCopyable
 {
 	friend class ThreadHiveThread;
@@ -104,16 +110,16 @@ private:
 	U32 m_pendingTasks = 0;
 	U32 m_allocatedTasks = 0;
 
-	Mutex m_mtx; ///< Protect the queue
+	Mutex m_mtx;
 	ConditionVariable m_cvar;
 
-	void run(U threadId);
+	void threadRun(U threadId);
 
-	Bool waitForWork(
-		U threadId, Task*& task, ThreadHiveTaskCallback& cb, void*& arg);
+	/// Wait for more tasks.
+	Bool waitForWork(U threadId, Task*& task);
 
 	/// Get new work from the queue.
-	Task* getNewTask(ThreadHiveTaskCallback& cb, void*& arg);
+	Task* getNewTask();
 
 	/// Complete a task.
 	void completeTask(U taskId);

include/anki/util/ThreadPool.h

@@ -20,6 +20,7 @@ class ThreadPoolThread;
 /// @{
 
 /// A task assignment for a ThreadPool
+/// @memberof ThreadPool
 class ThreadPoolTask
 {
 public:

src/util/ThreadHive.cpp

@@ -46,7 +46,7 @@ private:
 		ThreadHiveThread& self =
 			*reinterpret_cast<ThreadHiveThread*>(info.m_userData);
 
-		self.m_hive->run(self.m_id);
+		self.m_hive->threadRun(self.m_id);
 		return ErrorCode::NONE;
 	}
 };
@@ -169,16 +169,15 @@ void ThreadHive::submitTasks(ThreadHiveTask* tasks, U taskCount)
 }
 
 //==============================================================================
-void ThreadHive::run(U threadId)
+void ThreadHive::threadRun(U threadId)
 {
 	Task* task = nullptr;
-	ThreadHiveTaskCallback cb = nullptr;
-	void* arg = nullptr;
 
-	while(!waitForWork(threadId, task, cb, arg))
+	while(!waitForWork(threadId, task))
 	{
 		// Run the task
-		cb(arg, threadId, *this);
+		ANKI_ASSERT(task && task->m_cb);
+		task->m_cb(task->m_arg, threadId, *this);
 		ANKI_HIVE_DEBUG_PRINT("tid: %lu executed\n", threadId);
 	}
 
@@ -186,12 +185,8 @@ void ThreadHive::run(U threadId)
 }
 
 //==============================================================================
-Bool ThreadHive::waitForWork(
-	U threadId, Task*& task, ThreadHiveTaskCallback& cb, void*& arg)
+Bool ThreadHive::waitForWork(U threadId, Task*& task)
 {
-	cb = nullptr;
-	arg = nullptr;
-
 	LockGuard<Mutex> lock(m_mtx);
 
 	ANKI_HIVE_DEBUG_PRINT("tid: %lu locking\n", threadId);
@@ -210,7 +205,7 @@ Bool ThreadHive::waitForWork(
 		}
 	}
 
-	while(!m_quit && (task = getNewTask(cb, arg)) == nullptr)
+	while(!m_quit && (task = getNewTask()) == nullptr)
 	{
 		ANKI_HIVE_DEBUG_PRINT("tid: %lu waiting\n", threadId);
 
@@ -222,10 +217,8 @@ Bool ThreadHive::waitForWork(
 }
 
 //==============================================================================
-ThreadHive::Task* ThreadHive::getNewTask(ThreadHiveTaskCallback& cb, void*& arg)
+ThreadHive::Task* ThreadHive::getNewTask()
 {
-	cb = nullptr;
-
 	Task* prevTask = nullptr;
 	Task* task = m_head;
 	while(task)
@@ -250,9 +243,6 @@ ThreadHive::Task* ThreadHive::getNewTask(ThreadHiveTaskCallback& cb, void*& arg)
 			if(allDepsCompleted)
 			{
 				// Found something, pop it
-				cb = task->m_cb;
-				arg = task->m_arg;
-
 				if(prevTask)
 				{
 					prevTask->m_next = task->m_next;
@@ -267,6 +257,10 @@ ThreadHive::Task* ThreadHive::getNewTask(ThreadHiveTaskCallback& cb, void*& arg)
 				{
 					m_tail = prevTask;
 				}
+
+#if ANKI_DEBUG
+				task->m_next = nullptr;
+#endif
 				break;
 			}
 		}