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