Document the purpose and mechanics behind JOLTing

smocore/include/componentThread.h

@@ -82,6 +82,13 @@ public:
 	void exitThreadReq(std::function<void()> callback = nullptr);
 	void pauseThreadReq(std::function<void()> callback = nullptr);
 	void resumeThreadReq(std::function<void()> callback = nullptr);
+	/**
+	 * JOLTs this thread to begin processing after global initialization.
+	 *
+	 * JOLTing is the mechanism that allows threads to enter their main
+	 * event loops and set up TLS vars after all global constructors have
+	 * completed. This prevents race conditions during system startup.
+	 */
 	void joltThreadReq(std::function<void()> callback = nullptr);
 
 	// Convenience wrappers
@@ -122,7 +129,25 @@ public:
 	boost::asio::io_service::work pause_work;
 	std::atomic<bool> keepLooping;
 	int pinnedCpuId;
-    // Indicates whether all mind threads have been JOLTed at least once
+    /**
+     * Indicates whether all mind threads have been JOLTed at least once.
+     *
+     * JOLTing serves two critical purposes:
+     *
+     * 1. **Global Constructor Sequencing**: Since pthreads begin executing while
+     *    global constructors are still being executed, globally defined pthreads
+     *    cannot depend on global objects having been constructed. JOLTing is done
+     *    by the CRT's main thread within main(), which provides a sequencing
+     *    guarantee that global constructors have been called.
+     *
+     * 2. **shared_from_this Safety**: shared_from_this() requires a prior
+     *    shared_ptr handle to be established. The global list of
+     *    shared_ptr<ComponentThread> guarantees that at least one shared_ptr to
+     *    each ComponentThread has been initialized before JOLTing occurs.
+     *
+     * This atomic flag ensures that JOLTing happens exactly once and provides
+     * a synchronization point for the entire system initialization.
+     */
     static std::atomic<bool> threadsHaveBeenJolted;
 
     /* Always ensure that this is last so that the thread is spawned after