tests/lib/conds/utils.hpp

   1 /*
   2  * SPDX-License-Identifier: GPL-2.0-only
   3  *
   4  * Copyright (C) 2020 Philippe Proulx <pproulx@efficios.com>
   5  */
   6
   7 #ifndef TESTS_LIB_CONDS_UTILS_HPP
   8 #define TESTS_LIB_CONDS_UTILS_HPP
   9
  10 #include <functional>
  11 #include <memory>
  12 #include <string>
  13 #include <utility>
  14 #include <vector>
  15
  16 #include <babeltrace2/babeltrace.h>
  17
  18 #include "cpp-common/bt2c/c-string-view.hpp"
  19
  20 #include "../utils/run-in.hpp"
  21
  22 /*
  23  * Abstract condition trigger class.
  24  *
  25  * A derived class must provide operator()() which triggers a condition
  26  * of which the specific type (precondition or postcondition) and ID are
  27  * provided at construction time.
  28  */
  29 class CondTrigger
  30 {
  31 public:
  32     using UP = std::unique_ptr<CondTrigger>;
  33
  34     /*
  35      * Condition type.
  36      */
  37     enum class Type
  38     {
  39         PRE,
  40         POST,
  41     };
  42
  43 protected:
  44     /*
  45      * Builds a condition trigger having the type `type`, the condition
  46      * ID `condId` (_without_ any `pre:` or `post:` prefix), and the
  47      * optional name suffix `nameSuffix`.
  48      *
  49      * The concatenation of `condId` and, if it's set, `-` and
  50      * `*nameSuffix`, forms the name of the condition trigger. Get the
  51      * name of the created condition trigger with name().
  52      */
  53     explicit CondTrigger(Type type, const std::string& condId,
  54                          const bt2c::CStringView nameSuffix) noexcept;
  55
  56 public:
  57     virtual ~CondTrigger() = default;
  58     virtual void operator()() noexcept = 0;
  59
  60     Type type() const noexcept
  61     {
  62         return _mType;
  63     }
  64
  65     /*
  66      * Condition ID, including any `pre:` or `post:` prefix.
  67      */
  68     const std::string& condId() const noexcept
  69     {
  70         return _mCondId;
  71     }
  72
  73     const std::string& name() const noexcept
  74     {
  75         return _mName;
  76     }
  77
  78 private:
  79     Type _mType;
  80     std::string _mCondId;
  81     std::string _mName;
  82 };
  83
  84 /*
  85  * Simple condition trigger.
  86  *
  87  * Implements a condition trigger where a function provided at
  88  * construction time triggers a condition.
  89  */
  90 class SimpleCondTrigger : public CondTrigger
  91 {
  92 public:
  93     explicit SimpleCondTrigger(std::function<void()> func, Type type, const std::string& condId,
  94                                const bt2c::CStringView nameSuffix = {});
  95
  96     void operator()() noexcept override
  97     {
  98         _mFunc();
  99     }
 100
 101 private:
 102     std::function<void()> _mFunc;
 103 };
 104
 105 /*
 106  * Run-in condition trigger.
 107  *
 108  * Implements a condition trigger of which the triggering function
 109  * happens in a graph or component class query context using the
 110  * runIn() API.
 111  */
 112 template <typename RunInT>
 113 class RunInCondTrigger : public CondTrigger
 114 {
 115 public:
 116     explicit RunInCondTrigger(RunInT runIn, const Type type, const std::string& condId,
 117                               const bt2c::CStringView nameSuffix = {}) :
 118         CondTrigger {type, condId, nameSuffix},
 119         _mRunIn {std::move(runIn)}
 120     {
 121     }
 122
 123     explicit RunInCondTrigger(const Type type, const std::string& condId,
 124                               const bt2c::CStringView nameSuffix = {}) :
 125         RunInCondTrigger {RunInT {}, type, condId, nameSuffix}
 126     {
 127     }
 128
 129     void operator()() noexcept override
 130     {
 131         runIn(_mRunIn);
 132     }
 133
 134 private:
 135     RunInT _mRunIn;
 136 };
 137
 138 /*
 139  * List of condition triggers.
 140  */
 141 using CondTriggers = std::vector<CondTrigger::UP>;
 142
 143 /*
 144  * The entry point of a condition trigger program.
 145  *
 146  * Call this from your own main() with your list of condition triggers
 147  * `triggers`.
 148  *
 149  * Each condition trigger of `triggers` must have a unique name, as
 150  * returned by CondTrigger::name().
 151  *
 152  * This function uses `argc` and `argv` to respond to one of the
 153  * following commands:
 154  *
 155  * `list`:
 156  *     Prints a list of condition triggers as a JSON array of objects.
 157  *
 158  *     Each JSON object has:
 159  *
 160  *     `cond-id`:
 161  *         The condition ID of the trigger, as returned by
 162  *         CondTrigger:condId().
 163  *
 164  *     `name`:
 165  *         The condition ID name, as returned by CondTrigger::name().
 166  *
 167  * `run`:
 168  *     Runs the triggering function of the condition trigger at the
 169  *     index specified by the next command-line argument.
 170  *
 171  *     For example,
 172  *
 173  *         $ my-cond-trigger-program run 45
 174  *
 175  *     would run the function of the condition trigger `triggers[45]`.
 176  *
 177  *     The program is expected to abort through a libbabeltrace2
 178  *     condition failure.
 179  */
 180 void condMain(int argc, const char **argv, const CondTriggers& triggers) noexcept;
 181
 182 #endif /* TESTS_LIB_CONDS_UTILS_HPP */