Move and rename ThreadData::FreeThread() to ThreadEngine::Stop() and document what it does

5 files changed, 29 insertions, 6 deletions

diff --git a/include/threadengines/threadengine_pthread.h b/include/threadengines/threadengine_pthread.h
index 5756926fd..9304536f1 100644
--- a/include/threadengines/threadengine_pthread.h
+++ b/include/threadengines/threadengine_pthread.h
@@ -43,13 +43,24 @@ class CoreExport ThreadEngine
 	 * derived object.
 	 */
 	void Start(Thread* thread_to_init);
+
+	/** Stop a thread gracefully.
+	 * First, this function asks the thread to terminate by calling Thread::SetExitFlag().
+	 * Next, it waits until the thread terminates (on the operating system level). Finally,
+	 * all OS-level resources associated with the thread are released. The Thread instance
+	 * passed to the function is NOT freed.
+	 * When this function returns, the thread is stopped and you can destroy it or restart it
+	 * at a later point.
+	 * Stopping a thread that is not running is a bug.
+	 * @param thread The thread to stop.
+	 */
+	void Stop(Thread* thread);
 };
 
 class CoreExport ThreadData
 {
  public:
 	pthread_t pthread_id;
-	void FreeThread(Thread* toFree);
 };
 
 /** The Mutex class represents a mutex, which can be used to keep threads
diff --git a/include/threadengines/threadengine_win32.h b/include/threadengines/threadengine_win32.h
index 18b6e798c..1cebb50fe 100644
--- a/include/threadengines/threadengine_win32.h
+++ b/include/threadengines/threadengine_win32.h
@@ -47,13 +47,24 @@ class CoreExport ThreadEngine
 	  * derived object.
 	  */
 	void Start(Thread* thread_to_init);
+
+	/** Stop a thread gracefully.
+	 * First, this function asks the thread to terminate by calling Thread::SetExitFlag().
+	 * Next, it waits until the thread terminates (on the operating system level). Finally,
+	 * all OS-level resources associated with the thread are released. The Thread instance
+	 * passed to the function is NOT freed.
+	 * When this function returns, the thread is stopped and you can destroy it or restart it
+	 * at a later point.
+	 * Stopping a thread that is not running is a bug.
+	 * @param thread The thread to stop.
+	 */
+	void Stop(Thread* thread);
 };
 
 class CoreExport ThreadData
 {
  public:
 	HANDLE handle;
-	void FreeThread(Thread* toFree);
 };
 
 /** The Mutex class represents a mutex, which can be used to keep threads
diff --git a/src/threadengine.cpp b/src/threadengine.cpp
index 82aa78a36..bb686f084 100644
--- a/src/threadengine.cpp
+++ b/src/threadengine.cpp
@@ -26,7 +26,7 @@ void Thread::SetExitFlag()
 
 void Thread::join()
 {
-	state.FreeThread(this);
+	ServerInstance->Threads.Stop(this);
 }
 
 /** If this thread has a Creator set, call it to
diff --git a/src/threadengines/threadengine_pthread.cpp b/src/threadengines/threadengine_pthread.cpp
index 7900e66bc..fcb4db444 100644
--- a/src/threadengines/threadengine_pthread.cpp
+++ b/src/threadengines/threadengine_pthread.cpp
@@ -43,10 +43,10 @@ void ThreadEngine::Start(Thread* thread)
 		throw CoreException("Unable to create new thread: " + std::string(strerror(errno)));
 }
 
-void ThreadData::FreeThread(Thread* thread)
+void ThreadEngine::Stop(Thread* thread)
 {
 	thread->SetExitFlag();
-	pthread_join(pthread_id, NULL);
+	pthread_join(thread->state.pthread_id, NULL);
 }
 
 #ifdef HAS_EVENTFD
diff --git a/src/threadengines/threadengine_win32.cpp b/src/threadengines/threadengine_win32.cpp
index 3376f937a..33eb707e4 100644
--- a/src/threadengines/threadengine_win32.cpp
+++ b/src/threadengines/threadengine_win32.cpp
@@ -42,9 +42,10 @@ DWORD WINAPI ThreadEngine::Entry(void* parameter)
 	return 0;
 }
 
-void ThreadData::FreeThread(Thread* thread)
+void ThreadEngine::Stop(Thread* thread)
 {
 	thread->SetExitFlag();
+	HANDLE handle = thread->state.handle;
 	WaitForSingleObject(handle,INFINITE);
 	CloseHandle(handle);
 }