SERVER-43317 merge failpoint headers. Rewrite docs.

iterate docs

1 files changed, 205 insertions, 61 deletions

diff --git a/src/mongo/util/fail_point.h b/src/mongo/util/fail_point.h
index daf39bcba49..c5c12e62c23 100644
--- a/src/mongo/util/fail_point.h
+++ b/src/mongo/util/fail_point.h
@@ -30,48 +30,78 @@
 #pragma once
 
 #include <functional>
+#include <string>
 
+#include "mongo/base/status.h"
 #include "mongo/base/status_with.h"
 #include "mongo/db/jsobj.h"
 #include "mongo/db/operation_context.h"
 #include "mongo/platform/atomic_word.h"
 #include "mongo/platform/mutex.h"
+#include "mongo/stdx/unordered_map.h"
 
 namespace mongo {
 
 /**
- * A simple thread-safe fail point implementation that can be activated and
- * deactivated, as well as embed temporary data into it.
  *
- * The fail point has a static instance, which is represented by a FailPoint
- * object, and dynamic instance, represented by FailPoint::Scoped handles.
+ * A FailPoint is a hook mechanism allowing testing behavior to occur at prearranged
+ * execution points in the server code. They can be activated and deactivated, and
+ * configured to hold data.
+ *
+ * A FailPoint is usually defined by the MONGO_FAIL_POINT_DEFINE(name) macro,
+ * which arranges for it to be added to the global failpoint registry.
  *
  * Sample use:
- * // Declared somewhere:
- * FailPoint makeBadThingsHappen;
  *
- * // Somewhere in the code
- * return false || MONGO_unlikely(makeBadThingsHappen.shouldFail());
+ * // Defined somewhere:
+ * MONGO_FAIL_POINT_DEFINE(failPoint);
+ *
+ * bool somewhereInTheCode() {
+ *   ... do some stuff ...
+ *   // The failpoint artificially changes the return value of this function when active.
+ *   if (MONGO_unlikely(failPoint.shouldFail()))
+ *       return false;
+ *   return true;
+ * }
  *
- * or
+ * - or to implement more complex scenarios, use execute/executeIf -
  *
- * // Somewhere in the code
- * makeBadThingsHappen.execute([&](const BSONObj& data) {
- *     // Do something
- * });
+ * bool somewhereInTheCode() {
+ *     failPoint.execute([&](const BSONObj& data) {
+ *         // The bad things happen here, and can read the injected 'data'.
+ *     });
+ *     return true;
+ * }
  *
- * // Another way to do it, where lambda isn't suitable, e.g. to cause an early return
- * // of the enclosing function.
- * if (auto sfp = makeBadThingsHappen.scoped(); MONGO_unlikely(sfp.isActive())) {
- *     const BSONObj& data = sfp.getData();
- *     // Do something, including break, continue, return, etc...
+ * // scoped() is another way to do it, where lambda isn't suitable, e.g. to cause
+ * // a return/continue/break to control the enclosing function.
+ * for (auto& user : users) {
+ *     // The failpoint can be activated and given a user name, to skip that user.
+ *     if (auto sfp = failPoint.scoped(); MONGO_unlikely(sfp.isActive())) {
+ *         if (sfp.getData()["user"] == user.name()) {
+ *             continue;
+ *         }
+ *     }
+ *     processOneUser(user);
  * }
  *
- * Invariants:
+ * // Rendered compactly with scopedIf where the data serves as an activation filter.
+ * for (auto& user : users) {
+ *     if (MONGO_unlikely(failPoint.scopedIf([&](auto&& o) {
+ *         return o["user"] == user.name();
+ *     }).isActive())) {
+ *         continue;
+ *     }
+ *     processOneUser(user);
+ * }
+ *
+ *  The `scopedIf` and `executeIf` members have an advantage over `scoped` and `execute`. They
+ *  only affect the `FailPoint` activation counters (relevant to the `nTimes` and `skip` modes)
+ *  if the predicate is true.
+ *
+ * A FailPoint can be configured remotely by a database command.
+ * See `src/mongo/db/commands/fail_point_cmd.cpp`.
  *
- * 1. Always refer to _fpInfo first to check if failPoint is active or not before
- *    entering fail point or modifying fail point.
- * 2. Client visible fail point states are read-only when active.
  */
 class FailPoint {
 private:
@@ -88,11 +118,18 @@ public:
     };
 
     /**
-     * Helper class for making sure that FailPoint#shouldFailCloseBlock is called when
-     * FailPoint#shouldFailOpenBlock was called.
-     *
+     * An object representing an active FailPoint's interaction with the code it is
+     * instrumenting. It holds reference to its associated FailPoint, ensuring
+     * that FailPoint's state doesn't change while a Scoped is attached to it.
+     * If `isActive()`, then `getData()` may be called to retrieve injected data.
      * Users don't create these. They are only used within the execute and executeIf
      * functions and returned by the scoped() and scopedIf() functions.
+     *
+     * Ex:
+     *     if (auto scoped = failPoint.scoped(); scoped.isActive()) {
+     *         const BSONObj& data = scoped.getData();
+     *         //  failPoint injects some behavior, informed by `data`.
+     *     }
      */
     class Scoped {
     public:
@@ -103,7 +140,7 @@ public:
 
         ~Scoped() {
             if (_holdsRef) {
-                _failPoint->shouldFailCloseBlock();
+                _failPoint->_shouldFailCloseBlock();
             }
         }
 
@@ -125,7 +162,7 @@ public:
         const BSONObj& getData() const {
             // Assert when attempting to get data without holding a ref.
             fassert(16445, _holdsRef);
-            return _failPoint->getData();
+            return _failPoint->_getData();
         }
 
     private:
@@ -141,7 +178,18 @@ public:
     static void setThreadPRNGSeed(int32_t seed);
 
     /**
-     * Parses the {Mode, ValType, BSONObj} from the BSON.
+     * Parses the {mode, val, extra} from the BSON.
+     * obj = {
+     *   mode: modeElem // required
+     *   data: extra    // optional payload to inject into the FailPoint intercept site.
+     * }
+     * where `modeElem` is one of:
+     *       "off"
+     *       "alwaysOn"
+     *       {"times" : val}   // active for the next val calls
+     *       {"skip" : val}    // skip calls, activate on and after call number (val+1).
+     *       {"activationProbability" : val}  // val is in interval [0.0, 1.0]
+     *   }
      */
     static StatusWith<ModeOptions> parseBSON(const BSONObj& obj);
 
@@ -151,22 +199,25 @@ public:
     FailPoint& operator=(const FailPoint&) = delete;
 
     /**
-     * Note: This is not side-effect free - it can change the state to OFF after calling.
-     * Note: see `executeIf` for information on `pred`.
+     * Returns true if fail point is active.
+     *
+     * Calls to `shouldFail` can have side effects. For example they affect the counters
+     * kept to manage the `skip` or `nTimes` modes (See `setMode`).
      *
-     * Calls to shouldFail should be placed inside MONGO_unlikely for performance.
+     * See `executeIf` for information on `pred`.
      *
-     * @return true if fail point is active.
+     * Calls to `shouldFail` should be placed inside MONGO_unlikely for performance.
+     *    if (MONGO_unlikely(failpoint.shouldFail())) ...
      */
     template <typename Pred>
     bool shouldFail(Pred&& pred) {
-        RetCode ret = shouldFailOpenBlock(std::forward<Pred>(pred));
+        RetCode ret = _shouldFailOpenBlock(std::forward<Pred>(pred));
 
         if (MONGO_likely(ret == fastOff)) {
             return false;
         }
 
-        shouldFailCloseBlock();
+        _shouldFailCloseBlock();
         return ret == slowOn;
     }
 
@@ -175,22 +226,20 @@ public:
     }
 
     /**
-     * Changes the settings of this fail point. This will turn off the fail point
-     * and waits for all dynamic instances referencing this fail point to go away before
-     * actually modifying the settings.
+     * Changes the settings of this fail point. This will turn off the FailPoint and
+     * wait for all references on this FailPoint to go away before modifying it.
      *
-     * @param mode the new mode for this fail point.
-     * @param val the value that can have different usage depending on the mode:
+     * @param mode  new mode
+     * @param val   unsigned having different interpretations depending on the mode:
      *
      *     - off, alwaysOn: ignored
      *     - random: static_cast<int32_t>(std::numeric_limits<int32_t>::max() * p), where
      *           where p is the probability that any given evaluation of the failpoint should
      *           activate.
      *     - nTimes: the number of times this fail point will be active when
-     *         #shouldFail or #shouldFailOpenBlock is called.
-     *     - skip: the number of times this failpoint will be inactive when
-     *         #shouldFail or #shouldFailOpenBlock is called. After this number is reached, the
-     *         failpoint will always be active.
+     *         #shouldFail/#execute/#scoped are called.
+     *     - skip: will become active and remain active after
+     *         #shouldFail/#execute/#scoped are called this number of times.
      *
      * @param extra arbitrary BSON object that can be stored to this fail point
      *     that can be referenced afterwards with #getData. Defaults to an empty
@@ -208,18 +257,24 @@ public:
 
     /**
      * Create a Scoped from this FailPoint.
-     * Use the Scoped object to access failpoint data.
+     * The returned Scoped object will be active if the failpoint is active.
+     * If it's active, the returned object can be used to access FailPoint data.
      */
     Scoped scoped() {
         return scopedIf(nullptr);
     }
     /**
-     * Create a Scoped from this FailPoint, only active when `pred(payload)` is true.
-     * See `executeIf`. Use the Scoped object to access failpoint data.
+     * Create a Scoped from this FailPoint.
+     * If `pred(payload)` is true, then the returned Scoped object is active and the
+     * FailPoint's activation count is altered (relevant to e.g. the `nTimes` mode). If the
+     * predicate is false, an inactive Scoped is returned and this FailPoint's mode is not
+     * modified at all.
+     * If it's active, the returned object can be used to access FailPoint data.
+     * The `pred` should be callable like a `bool pred(const BSONObj&)`.
      */
     template <typename Pred>
     Scoped scopedIf(Pred&& pred) {
-        return Scoped(this, shouldFailOpenBlock(std::forward<Pred>(pred)));
+        return Scoped(this, _shouldFailOpenBlock(std::forward<Pred>(pred)));
     }
 
     template <typename F>
@@ -228,9 +283,11 @@ public:
     }
 
     /**
-     * The predicate `pred` should behave like a `bool pred(const BSONObj& payload)`.
-     * If `pred(payload)`, then `f(payload)` is executed. Otherwise, `f` is not
-     * executed and this FailPoint's mode is not altered (e.g. `nTimes` isn't consumed).
+     * If `pred(payload)` is true, then `f(payload)` is executed and the FailPoint's
+     * activation count is altered (relevant to e.g. the `nTimes` mode). Otherwise, `f`
+     * is not executed and this FailPoint's mode is not altered (e.g. `nTimes` isn't
+     * consumed).
+     * The `pred` should be callable like a `bool pred(const BSONObj&)`.
      */
     template <typename F, typename Pred>
     void executeIf(F&& f, Pred&& pred) {
@@ -240,12 +297,21 @@ public:
         }
     }
 
+    /**
+     * Take 100msec pauses for as long as the FailPoint is active.
+     * This uses `shouldFail()` and therefore affects FailPoint counters.
+     */
     void pauseWhileSet() {
         while (MONGO_unlikely(shouldFail())) {
             sleepmillis(100);
         }
     }
 
+    /**
+     * Like `pauseWhileSet`, but interruptible via the `opCtx->sleepFor` mechanism.  See
+     * `mongo::Interruptible::sleepFor` (Interruptible is a base class of
+     * OperationContext).
+     */
     void pauseWhileSet(OperationContext* opCtx) {
         while (MONGO_unlikely(shouldFail())) {
             opCtx->sleepFor(Milliseconds(100));
@@ -253,8 +319,8 @@ public:
     }
 
 private:
-    void enable();
-    void disable();
+    void _enable();
+    void _disable();
 
     /**
      * Checks whether fail point is active and increments the reference counter without
@@ -269,37 +335,37 @@ private:
      *         fastOff if its disabled and doesn't need to be closed
      */
     template <typename Pred>
-    RetCode shouldFailOpenBlock(Pred&& pred) {
+    RetCode _shouldFailOpenBlock(Pred&& pred) {
         if (MONGO_likely((_fpInfo.loadRelaxed() & kActiveBit) == 0)) {
             return fastOff;
         }
 
-        return slowShouldFailOpenBlock(std::forward<Pred>(pred));
+        return _slowShouldFailOpenBlock(std::forward<Pred>(pred));
     }
 
-    RetCode shouldFailOpenBlock() {
-        return shouldFailOpenBlock(nullptr);
+    RetCode _shouldFailOpenBlock() {
+        return _shouldFailOpenBlock(nullptr);
     }
 
     /**
      * Decrements the reference counter.
-     * @see #shouldFailOpenBlock
+     * @see #_shouldFailOpenBlock
      */
-    void shouldFailCloseBlock();
+    void _shouldFailCloseBlock();
 
     /**
-     * slow path for #shouldFailOpenBlock
+     * slow path for #_shouldFailOpenBlock
      *
      * If a callable is passed, and returns false, this will return userIgnored and avoid altering
      * the mode in any way.  The argument is the fail point payload.
      */
-    RetCode slowShouldFailOpenBlock(std::function<bool(const BSONObj&)> cb) noexcept;
+    RetCode _slowShouldFailOpenBlock(std::function<bool(const BSONObj&)> cb) noexcept;
 
     /**
      * @return the stored BSONObj in this fail point. Note that this cannot be safely
      *      read if this fail point is off.
      */
-    const BSONObj& getData() const;
+    const BSONObj& _getData() const;
 
     static const ValType kActiveBit = 1 << 31;
 
@@ -317,4 +383,82 @@ private:
     mutable Mutex _modMutex = MONGO_MAKE_LATCH("FailPoint::_modMutex");
 };
 
+class FailPointRegistry {
+public:
+    FailPointRegistry();
+
+    /**
+     * Adds a new fail point to this registry. Duplicate names are not allowed.
+     *
+     * @return the status code under these circumstances:
+     *     OK - if successful.
+     *     51006 - if the given name already exists in this registry.
+     *     CannotMutateObject - if this registry is already frozen.
+     */
+    Status add(const std::string& name, FailPoint* failPoint);
+
+    /**
+     * @return a registered FailPoint, or nullptr if it was not registered.
+     */
+    FailPoint* find(const std::string& name) const;
+
+    /**
+     * Freezes this registry from being modified.
+     */
+    void freeze();
+
+    /**
+     * Creates a new FailPointServerParameter for each failpoint in the registry. This allows the
+     * failpoint to be set on the command line via --setParameter, but is only allowed when
+     * running with '--setParameter enableTestCommands=1'.
+     */
+    void registerAllFailPointsAsServerParameters();
+
+private:
+    bool _frozen;
+    stdx::unordered_map<std::string, FailPoint*> _fpMap;
+};
+
+/**
+ * A scope guard that enables a named FailPoint on construction and disables it on destruction.
+ */
+class FailPointEnableBlock {
+public:
+    explicit FailPointEnableBlock(std::string failPointName);
+    FailPointEnableBlock(std::string failPointName, BSONObj cmdObj);
+    ~FailPointEnableBlock();
+
+private:
+    std::string _failPointName;
+    FailPoint* _failPoint;
+};
+
+/**
+ * Set a fail point in the global registry to a given value via BSON
+ * @throw DBException corresponding to ErrorCodes::FailPointSetFailed if no failpoint
+ * called failPointName exists.
+ */
+void setGlobalFailPoint(const std::string& failPointName, const BSONObj& cmdObj);
+
+/**
+ * Registration object for FailPoint. Its static-initializer registers FailPoint `fp`
+ * into the `globalFailPointRegistry()` under the specified `name`.
+ */
+class FailPointRegisterer {
+public:
+    FailPointRegisterer(const std::string& name, FailPoint* fp);
+};
+
+FailPointRegistry& globalFailPointRegistry();
+
+/**
+ * Convenience macro for defining a fail point and registering it.
+ * Must be used at namespace scope, not at local (inside a function) or class scope.
+ * Never use in header files, only .cpp files.
+ */
+#define MONGO_FAIL_POINT_DEFINE(fp) \
+    ::mongo::FailPoint fp;          \
+    ::mongo::FailPointRegisterer fp##failPointRegisterer(#fp, &fp);
+
+
 }  // namespace mongo