[Fixup] Restore upstream comment formatting and fflush(stdout) in LlvmRuntimeExecutor::synchronize

Author: duburcqa

quadrants/program/program.h

@@ -201,8 +201,10 @@ class QD_DLL_EXPORT Program {
     return snode_rw_accessors_bank_;
   }
 
-  // Resolve an `SNode *` from its global `SNode::id`. Lazy `snode_id_cache_` lookup; the cache is wiped by
-  // `add_snode_tree` and `destroy_snode_tree`.
+  // Look up an `SNode` in this `Program`'s snode trees by its global `SNode::id`. Used by the host-side adstack
+  // size-expression evaluator to rehydrate an `SNode *` from a `snode_id` that survived the offline cache. Linear
+  // over all snode trees; called at most once per adstack leaf per kernel launch so the cost is negligible in
+  // practice.
   SNode *get_snode_by_id(int snode_id);
 
   // Adstack-specific caching: per-task adstack-sizer metadata caches (SPIR-V + LLVM-GPU), encoded SPIR-V bytecode

quadrants/program/program_impl.h

@@ -143,8 +143,9 @@ class ProgramImpl {
   virtual void finalize() {
   }
 
-  // Invoked by `Program::finalize()` before any teardown sync, so the backend can flip state that
-  // silences user-visible asserts during destructor unwinding.
+  // Hook invoked by `Program::finalize()` before any teardown sync. Lets backends flip state (e.g. the LLVM
+  // `finalizing_` flag used to suppress adstack-overflow polling) so the two `Program::synchronize()` calls that
+  // precede `finalize()` do not throw into the Program destructor path.
   virtual void pre_finalize() {
   }
 

quadrants/runtime/llvm/llvm_runtime_executor.cpp

@@ -212,6 +212,7 @@ void LlvmRuntimeExecutor::synchronize() {
     QD_ERROR("No AMDGPU support");
 #endif
   }
+  fflush(stdout);
 }
 
 uint64 LlvmRuntimeExecutor::fetch_result_uint64(int i, uint64 *result_buffer) {

quadrants/runtime/program_impls/llvm/llvm_program.h

@@ -1,7 +1,6 @@
 #pragma once
 
 #include <cstddef>
-#include <cstdio>
 #include <memory>
 
 #include "quadrants/runtime/llvm/llvm_offline_cache.h"
@@ -100,8 +99,11 @@ class LlvmProgramImpl : public ProgramImpl {
     return runtime_exec_->fetch_result<T>(i, result_buffer);
   }
 
-  // Mark the impl as shutting down so `synchronize_and_assert()` skips the overflow poll, preventing a
-  // `qd.sync()` racing with destruction from throwing inside `~Program()` unwinding.
+  // Skip the adstack-overflow poll from this point on: `Program::finalize()` invokes `pre_finalize()` before the
+  // two teardown `synchronize()` calls, and we do not want `check_adstack_overflow()` to throw into a
+  // `~Program()` unwinding path - that would terminate the process with a bare `QuadrantsAssertionError` instead
+  // of letting the user handle it at their own `qd.sync()` site. The flag only affects the internal poll; the
+  // user can still call `qd.sync()` explicitly before finalize to observe the raise.
   void pre_finalize() override {
     finalizing_ = true;
   }
@@ -165,8 +167,6 @@ class LlvmProgramImpl : public ProgramImpl {
     if (!finalizing_) {
       runtime_exec_->check_adstack_overflow();
     }
-    // Flush JIT-generated `qd.print()` output at every user-visible sync.
-    fflush(stdout);
   }
 
   LLVMRuntime *get_llvm_runtime() {
@@ -267,8 +267,11 @@ class LlvmProgramImpl : public ProgramImpl {
   std::size_t num_snode_trees_processed_{0};
   std::unique_ptr<LlvmRuntimeExecutor> runtime_exec_;
   std::unique_ptr<LlvmOfflineCache> cache_data_;
-  // Set by `pre_finalize()` / `finalize()` so `synchronize_and_assert()` skips the overflow poll while
-  // teardown is in progress.
+  // Flipped on by `pre_finalize()` (with a defensive re-assignment in `finalize()`) so the `synchronize()`
+  // override stops polling the adstack-overflow flag during teardown. `Program::finalize()` invokes
+  // `pre_finalize()` before its two teardown syncs, so the flag is already true when those syncs run; moving
+  // the assignment back into `finalize()` alone would silently re-introduce the `std::terminate()` teardown bug
+  // this field was introduced to fix.
   bool finalizing_{false};
 };