From fd082d89bfec2ee1da9778bdf300c28b0a6a0a31 Mon Sep 17 00:00:00 2001
From: JaySon-Huang <tshent@qq.com>
Date: Thu, 17 Sep 2020 14:27:01 +0800
Subject: [PATCH] Add some comments

Signed-off-by: JaySon-Huang <tshent@qq.com>
---
 dbms/src/Common/FailPoint.cpp     | 32 ++++++++++++++-----------------
 dbms/src/Common/FailPoint.h       |  5 +++--
 dbms/src/Debug/dbgFuncFailPoint.h |  8 ++++++--
 3 files changed, 23 insertions(+), 22 deletions(-)

diff --git a/dbms/src/Common/FailPoint.cpp b/dbms/src/Common/FailPoint.cpp
index 8ba4423b5cb..ffafcb032bc 100644
--- a/dbms/src/Common/FailPoint.cpp
+++ b/dbms/src/Common/FailPoint.cpp
@@ -1,4 +1,5 @@
 #include <Common/FailPoint.h>
+
 #include <boost/core/noncopyable.hpp>
 #include <condition_variable>
 #include <mutex>
@@ -31,13 +32,6 @@ APPLY_FOR_FAILPOINTS_WITH_CHANNEL(M)
 #undef M
 } // namespace FailPoints
 
-#define FAIL_POINT_ENABLE_WITH_CHANNEL(trigger, name)                                                 \
-    else if (trigger == FailPoints::name)                                                             \
-    {                                                                                                 \
-        fiu_enable(name, 1, nullptr, FIU_ONETIME);                                                    \
-        fail_point_wait_channels.try_emplace(FailPoints::name, std::make_shared<FailPointChannel>()); \
-    }
-
 class FailPointChannel : private boost::noncopyable
 {
 public:
@@ -57,22 +51,24 @@ class FailPointChannel : private boost::noncopyable
 
 void FailPointHelper::enableFailPoint(const String & fail_point_name)
 {
-#define M(NAME)                                                \
-    if (fail_point_name == FailPoints::NAME)                   \
-    {                                                          \
-        fiu_enable(FailPoints::NAME, 1, nullptr, FIU_ONETIME); \
-        return;                                                \
+#define M(NAME)                                                                                             \
+    if (fail_point_name == FailPoints::NAME)                                                                \
+    {                                                                                                       \
+        /* FIU_ONETIME -- Only fail once; the point of failure will be automatically disabled afterwards.*/ \
+        fiu_enable(FailPoints::NAME, 1, nullptr, FIU_ONETIME);                                              \
+        return;                                                                                             \
     }
 
     APPLY_FOR_FAILPOINTS(M)
 #undef M
 
-#define M(NAME)                                                                                       \
-    if (fail_point_name == FailPoints::NAME)                                                          \
-    {                                                                                                 \
-        fiu_enable(FailPoints::NAME, 1, nullptr, FIU_ONETIME);                                        \
-        fail_point_wait_channels.try_emplace(FailPoints::NAME, std::make_shared<FailPointChannel>()); \
-        return;                                                                                       \
+#define M(NAME)                                                                                             \
+    if (fail_point_name == FailPoints::NAME)                                                                \
+    {                                                                                                       \
+        /* FIU_ONETIME -- Only fail once; the point of failure will be automatically disabled afterwards.*/ \
+        fiu_enable(FailPoints::NAME, 1, nullptr, FIU_ONETIME);                                              \
+        fail_point_wait_channels.try_emplace(FailPoints::NAME, std::make_shared<FailPointChannel>());       \
+        return;                                                                                             \
     }
 
     APPLY_FOR_FAILPOINTS_WITH_CHANNEL(M)
diff --git a/dbms/src/Common/FailPoint.h b/dbms/src/Common/FailPoint.h
index bfe9843ecac..516575f15d8 100644
--- a/dbms/src/Common/FailPoint.h
+++ b/dbms/src/Common/FailPoint.h
@@ -15,11 +15,12 @@ namespace ErrorCodes
 extern const int FAIL_POINT_ERROR;
 };
 
-// Macros to set failpoint
+/// Macros to set failpoints.
+// When `fail_point` is enabled, throw an exception
 #define FAIL_POINT_TRIGGER_EXCEPTION(fail_point) \
     fiu_do_on(fail_point, throw Exception("Fail point " #fail_point " is triggered.", ErrorCodes::FAIL_POINT_ERROR);)
+// When `fail_point` is enabled, wait till it is disabled
 #define FAIL_POINT_PAUSE(fail_point) fiu_do_on(fail_point, FailPointHelper::wait(fail_point);)
-// #define FAIL_POINT_TRIGGER_REGION_EXCEPTION(fail_point) fiu_do_on(fail_point, throw RegionException(); )
 
 
 class FailPointChannel;
diff --git a/dbms/src/Debug/dbgFuncFailPoint.h b/dbms/src/Debug/dbgFuncFailPoint.h
index fb07c611147..52e5b7c1009 100644
--- a/dbms/src/Debug/dbgFuncFailPoint.h
+++ b/dbms/src/Debug/dbgFuncFailPoint.h
@@ -8,10 +8,14 @@ namespace DB
 struct DbgFailPointFunc
 {
 
-    static void dbgEnableFailPoint(Context & context, const ASTs & args, DBGInvoker::Printer output);
-
+    // Init fail point. must be called if you want to enable / disable failpoints
+    //    DBGInvoke init_fail_point()
     static void dbgInitFailPoint(Context & context, const ASTs & args, DBGInvoker::Printer output);
 
+    // Enable fail point.
+    //    DBGInvoke enable_fail_point(name)
+    static void dbgEnableFailPoint(Context & context, const ASTs & args, DBGInvoker::Printer output);
+
     // Disable fail point.
     // Usage:
     //   ./stoage-client.sh "DBGInvoke disable_fail_point(name)"