From 618562b6927377e2f2d34a609b1ada4d05a3196b Mon Sep 17 00:00:00 2001 From: fchn289 Date: Sun, 4 Aug 2024 16:54:48 +0800 Subject: [PATCH] comments --- src/domino/Domino.hpp | 16 ++++------------ src/thread/AsyncBack.hpp | 9 +++++++-- src/thread/ThPoolBack.hpp | 12 ++++++++---- ut/domino/DominoTest.cpp | 15 ++++++++------- 4 files changed, 27 insertions(+), 25 deletions(-) diff --git a/src/domino/Domino.hpp b/src/domino/Domino.hpp index 815138e..c59178c 100644 --- a/src/domino/Domino.hpp +++ b/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 diff --git a/src/thread/AsyncBack.hpp b/src/thread/AsyncBack.hpp index a8bd52d..746dddb 100644 --- a/src/thread/AsyncBack.hpp +++ b/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 diff --git a/src/thread/ThPoolBack.hpp b/src/thread/ThPoolBack.hpp index ceff5ac..506c3bf 100644 --- a/src/thread/ThPoolBack.hpp +++ b/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 diff --git a/ut/domino/DominoTest.cpp b/ut/domino/DominoTest.cpp index 755107f..274bf13 100644 --- a/ut/domino/DominoTest.cpp +++ b/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