Documenting the threading/* classes.

Also switching from semaphores to mutexes as the former don't seem to
be fully supported on MacOS.

src/threading/BasicThread.h

@@ -14,50 +14,133 @@ namespace threading {
 
 class Manager;
 
+/**
+ * Base class for all threads.
+ *
+ * This class encapsulates all the OS-level thread handling. All thread
+ * instances are automatically added to the threading::Manager for management. The
+ * manager also takes care of deleting them (which must not be done
+ * manually).
+ */
 class BasicThread
 {
 public:
+	/**
+	 * Creates a new thread object. Instantiating the object does however
+	 * not yet start the actual OS thread, that requires calling Start().
+	 *
+	 * Only Bro's main thread may create new thread instances.
+	 *
+	 * @param name A descriptive name for thread the thread. This may
+	 * show up in messages to the user.
+	 */
 	BasicThread(const string& name); // Managed by manager, must not delete otherwise.
-	virtual ~BasicThread();
 
+	/**
+	 * Returns a descriptive name for the thread. This is the name passed
+	 * into the constructor.
+	 *
+	 * This method is safe to call from any thread.
+	 */
 	const string& Name() const { return name; }
 
-	void Start(); // Spawns the thread and enters Run().
-	void Stop();  // Signals the thread to terminate.
+	/**
+	 * Starts the thread. Calling this methods will spawn a new OS thread
+	 * executing Run(). Note that one can't restart a thread after a
+	 * Stop(), doing so will be ignored.
+	 *
+	 * Only Bro's main thread must call this method.
+	 */
+	void Start();
 
+	/**
+	 * Signals the thread to stop. The method lets Terminating() now
+	 * return true. It does however not force the thread to terminate.
+	 * It's up to the Run() method to to query Terminating() and exit
+	 * eventually.
+	 *
+	 * Calling this method has no effect if Start() hasn't been executed
+	 * yet.
+	 *
+	 * Only Bro's main thread must call this method.
+	 */
+	void Stop();
+
+	/**
+	 * Returns true if Terminate() has been called.
+	 *
+	 * This method is safe to call from any thread.
+	 */
 	bool Terminating()  const { return terminating; }
 
-	// A thread-safe version of fmt().
+	/**
+	 * A version of fmt() that the thread can safely use.
+	 *
+	 * This is safe to call from Run() but must not be used from any
+	 * other thread than the current one.
+	 */
 	const char* Fmt(const char* format, ...);
 
 protected:
-	virtual void Run() = 0;
-
-	virtual void OnStart()	{}
-	virtual void OnStop()	{}
-
-private:
 	friend class Manager;
 
+	/**
+	 * Entry point for the thread. This must be overridden by derived
+	 * classes and will execute in a separate thread once Start() is
+	 * called. The thread will not terminate before this method finishes.
+	 * An implementation should regularly check Terminating() to see if
+	 * exiting has been requested.
+	 */
+	virtual void Run() = 0;
+
+	/**
+	 * Executed with Start(). This is a hook into starting the thread. It
+	 * will be called from Bro's main thread after the OS thread has been
+	 * started.
+	 */
+	virtual void OnStart()	{}
+
+	/**
+	 * Executed with Stop(). This is a hook into stopping the thread. It
+	 * will be called from Bro's main thread after the thread has been
+	 * signaled to stop.
+	 */
+	virtual void OnStop()	{}
+
+	/**
+	 * Destructor. This will be called by the manager.
+	 *
+	 * Only Bro's main thread may delete thread instances.
+	 *
+	 */
+	virtual ~BasicThread();
+
+	/**
+	 * Waits until the thread's Run() method has finished and then joins
+	 * it. This is called from the threading::Manager.
+	 */
+	void Join();
+
+private:
+	// pthread entry function.
 	static void* launcher(void *arg);
 
-	// Used from the ThreadMgr.
-	void Join();	// Waits until the thread has terminated and then joins it.
-
+	string name;
+	pthread_t pthread;
 	bool started; 		// Set to to true once running.
 	bool terminating;	// Set to to true to signal termination.
-	string name;
 
-	pthread_t pthread;
-	sem_t terminate;
+	// Used as a semaphore to tell the pthread thread when it may
+	// terminate.
+	pthread_mutex_t terminate;
 
 	// For implementing Fmt().
 	char* buf;
 	unsigned int buf_len;
+
+	static uint64_t thread_counter;
 };
 
 }
 
-extern threading::Manager* thread_mgr;
-
 #endif