Doxygen Base part 03

Author: WeiqunZhang

Src/Base/AMReX_BLassert.H

@@ -5,6 +5,25 @@
 
 #include <AMReX.H>
 
+/**
+ * \file AMReX_BLassert.H
+ * \brief Assertion macros used across AMReX for runtime consistency checks.
+ *
+ * In debug builds (or when `AMREX_USE_ASSERTION` is defined) the macros expand
+ * to runtime checks that call `amrex::Assert` if they fail. In release builds
+ * without assertion support, the non-\*_ALWAYS variants become no-ops.
+ *
+ * - `AMREX_ASSERT(expr)` evaluates \p expr and aborts on failure, emitting the
+ *   expression, file, and line number.
+ * - `AMREX_ASSERT_WITH_MESSAGE(expr,msg)` behaves the same but also forwards
+ *   the user-provided \p msg to `amrex::Assert`, allowing custom diagnostics.
+ * - The `_ALWAYS_` variants (`AMREX_ALWAYS_ASSERT`, etc.) remain active even in
+ *   non-debug builds.
+ * - `AMREX_GPU_ASSERT` provides the same semantics inside GPU code paths when
+ *   `AMREX_USE_GPU` is defined and either `AMREX_DEBUG` or `AMREX_USE_ASSERTION`
+ *   is enabled; otherwise it is a no-op.
+ */
+
 #ifdef AMREX_ASSERT
 #undef AMREX_ASSERT
 #endif
@@ -15,25 +34,6 @@
 
 #if !defined(AMREX_DEBUG) && !defined(AMREX_USE_ASSERTION)
 
-/*
-  The macro AMREX_ASSERT(EX) is a debugging macro, used to test the
-  internal consistency of AMReX, that may also be useful in user
-  code.  The argument EX is a C++ expression that you expect to
-  always evaluate to true.
-
-  When code is compiled with the DEBUG macro set to TRUE, the
-  AMREX_ASSERT(EX) macro expands to a boolean test of the expression EX.
-  If that expression evaluates to true, nothing happens, but if the
-  expression evaluates to false, a message is output detailing the
-  file and line number of the AMREX_ASSERT(EX) statement, as well as the
-  literal expression EX itself, and then exits via abort() using
-  amrex::Assert().  The idea is that if the assertion fails, something
-  has gone terribly wrong somewhere.
-
-  If the DEBUG macro is not set to TRUE, the AMREX_ASSERT(EX) call becomes
-  a null statement in the code, which will be eliminated by the code
-  optimizer.
-*/
 #define AMREX_ASSERT_WITH_MESSAGE(EX,MSG) ((void)0)
 #define AMREX_ASSERT(EX) ((void)0)
 #define    BL_ASSERT(EX) ((void)0)
@@ -56,4 +56,4 @@
 #define AMREX_GPU_ASSERT(EX) (EX)?((void)0):amrex::Assert( # EX , __FILE__, __LINE__)
 #endif
 
-#endif /*BL_BL_ASSERT_H*/
+#endif /* AMREX_BLASSERT_H_ */

Src/Base/AMReX_BackgroundThread.H

@@ -10,22 +10,48 @@
 #include <queue>
 #include <thread>
 
+/**
+ * \file AMReX_BackgroundThread.H
+ * \brief Simple job queue serviced by a dedicated background std::thread.
+ */
+
 namespace amrex {
 
+/**
+ * \class amrex::BackgroundThread
+ * \brief Utility class running deferred work on a single background thread.
+ * \ingroup amrex_utilities
+ */
 class BackgroundThread
 {
 public:
+    /**
+     * \brief Launch the worker thread and initialize synchronization primitives.
+     */
     BackgroundThread ();
+    /**
+     * \brief Stop the worker thread and drain any queued work.
+     */
     ~BackgroundThread ();
     BackgroundThread (BackgroundThread const&) = delete;
     BackgroundThread (BackgroundThread &&) = delete;
     BackgroundThread& operator= (BackgroundThread const&) = delete;
     BackgroundThread& operator= (BackgroundThread &&) = delete;
 
+    /**
+     * \brief Enqueue a job that will run asynchronously on the worker thread.
+     * \param a_f Functor representing the work to execute.
+     */
     void Submit (std::function<void()>&& a_f);
+    /**
+     * \overload
+     */
     void Submit (std::function<void()> const& a_f);
 
-    void Finish (); // Not required. Call this if you want all jobs to finish.
+    /**
+     * \brief Block the caller until all queued jobs have completed.
+     */
+    void Finish ();
 
 private:
     void do_job ();