comments

src/domino/Domino.hpp

@@ -30,18 +30,10 @@
 //   . n-go domino
 //
 // - MT safe: no
-// - class safe: yes (all-safe include mem-safe, no-ev-link-loop, no exception, etc, exclude MT safe)
-//   . no use-up mem which is impossible in most cases
-//   . user shall not loop link ev - hard, expensive & unreasonable
-//   . ev-link-loop:
-//     . REQ:
-//       . no-loop to ensure safe
-//         . runtime forbid (rather than offline/afterward check which is not safe)
-//         . so fail setPrev() to prevent loop
-//       . reasonable cost-benefit
-//         . so little impact runtime (debug can be HID_CODE)
-//         . next-loop can be prevented simply
-//         . true-false-loop can NOT (refer UT strange_loop)
+// - use-safe: yes with conditions:
+//   . no too many events/.. that use-up mem (impossible in most cases)
+//   . user shall not loop ev-link (impossible unless deliberate)
+//     . domino prevent is not 100%, see UT for details
 // ***********************************************************************************************
 #pragma once
 

src/thread/AsyncBack.hpp

@@ -35,16 +35,21 @@
 //   * AsyncBack is for normal/most scenario, may NOK for huge threads, high throughput, etc
 //   * ONLY call AsyncBack in main-thread
 //
-// - class safe: yes
+//
+// - MT safe: NO
 //   * all AsyncBack func (include ThreadBack) must run in 1 thread (best in main thread)
 //     . AsyncBack can call inMyMainTH() to ensure this
 //     . but can all rlib func call inMyMainTH()? little benefit so giveup
 //       * common sense/principle: rlib (include AsyncBack) not call inMyMainTH()
 //       . inMyMainTH() for user debug - any main-thread func shall ret T if call inMyMainTH()
-//     * same for exception - assume no exception from any hdlr provided to rlib
+// - Exception-safe: NO
+//   * assume no exception from any hdlr provided to rlib
 //   . no duty to any unsafe behavior of MT_TaskEntryFN & TaskBackFN (eg throw exception)
 //     . MT_TaskEntryFN & TaskBackFN shall NOT throw exception
 //     . they can try-catch all exception & leave rlib simple/focus
+// - Use-safe: LTD
+//   . not support too many threads (used-up thread resource; impossible in most/normal cases)
+//   . lower performance than eg thread pool (but simpler impl than thread pool)
 //
 // - support multi-thread
 //   . MT_/mt_ prefix: yes

src/thread/ThPoolBack.hpp

@@ -4,10 +4,14 @@
  * SPDX-License-Identifier: BSD-3-Clause
  */
 // ***********************************************************************************************
-// - Why:
-//   . alt AsyncBack by limit thread# (limited resource) but may wait more time for free thread
-//   . avoid create/destroy thread, 10~100 faster than AsyncBack
-//   . code more complex than AsyncBack
+// Why:
+// - alt AsyncBack by limit thread# (limited resource) but may wait more time for free thread
+// - avoid create/destroy thread, 10~100 faster than AsyncBack
+// - code more complex than AsyncBack
+//
+// MT safe: NO (can be used in main thread only)
+// Exception-safe: NO
+// Use-safe: yes
 // ***********************************************************************************************
 #pragma once
 

ut/domino/DominoTest.cpp

@@ -167,17 +167,18 @@ TYPED_TEST_P(DominoTest, strangeLoop_prevBothTrueAndFalse)
     EXPECT_EQ("e44==false", PARA_DOM->whyFalse(e40)) << "inc cov: e40=T via e41, then =F via e42";
 
     // - this kind of loop can be very long & complex (much more than above examples)
-    //   . when occur, the end-event can't be satisfied forever (user's fault, not Domino)
+    //   . when occur, the end-event can't be satisfied forever
     // - not find a simple way (reasonable cost-benefit) to prevent it
     //   . whyFalse() is simple to detect it (but not prevent so not perfect)
     //   . TODO: need partial forbid simple t/f-loop? avoid complex/risk impl
     // - so is setPrev() safe?
-    //   . Domino will not dead-loop; end-event always false, it's not Domino's fault
-    //   . so yes, setPrev() is safe (& risky)
-    // - how to define safe? if calling a class' interface,
-    //   . no crash, no mem-leak, no dead loop, etc under normal/required scenaria
-    //   . and it does what's expected reasonably
-    //   . then it's safe (as LTD company)
+    //   . mostly & normally yes
+    //     . next-loop can be prevented simply
+    //     . true-false-loop can NOT (see above ut)
+    //   . as if LTD company (benefit-cost shall be reasonable)
+    // - how to define loop-safe:
+    //   . runtime forbid (rather than offline/afterward check which is not safe)
+    //   . so shall fail setPrev() to prevent loop
 }
 
 #define WHY_FALSE