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