From edc198dd00b0a0ff222caa68e8e1db3260f5bde3 Mon Sep 17 00:00:00 2001 From: Hayodea Hakol Date: Fri, 15 Aug 2025 13:16:23 -0400 Subject: [PATCH] Document the purpose and mechanics behind JOLTing --- smocore/include/componentThread.h | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/smocore/include/componentThread.h b/smocore/include/componentThread.h index 5522e85..d46f6ca 100644 --- a/smocore/include/componentThread.h +++ b/smocore/include/componentThread.h @@ -82,6 +82,13 @@ public: void exitThreadReq(std::function callback = nullptr); void pauseThreadReq(std::function callback = nullptr); void resumeThreadReq(std::function 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 callback = nullptr); // Convenience wrappers @@ -122,7 +129,25 @@ public: boost::asio::io_service::work pause_work; std::atomic 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 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 threadsHaveBeenJolted; /* Always ensure that this is last so that the thread is spawned after