include/simgrid/kernel/ProfileBuilder.hpp

   1 /* Copyright (c) 2004-2022. The SimGrid Team. All rights reserved.          */
   2
   3 /* This program is free software; you can redistribute it and/or modify it
   4  * under the terms of the license (GNU LGPL) which comes with this package. */
   5
   6 #ifndef SIMGRID_KERNEL_PROFILEBUILDER_HPP
   7 #define SIMGRID_KERNEL_PROFILEBUILDER_HPP
   8
   9 #include <simgrid/forward.h>
  10 #include <functional>
  11
  12 namespace simgrid {
  13 namespace kernel {
  14 namespace profile {
  15
  16
  17 /** @brief Modeling of the availability profile (due to an external load) or the churn
  18  *
  19  * There is 4 main concepts in this module:
  20  * - #simgrid::kernel::profile::DatedValue: a pair <timestamp, value> (both are of type double)
  21  * - #simgrid::kernel::profile::Profile: a list of dated values
  22  * - #simgrid::kernel::profile::Event: links a given trace to a given SimGrid resource.
  23  *   A Cpu for example has 2 kinds of events: state (ie, is it ON/OFF) and speed,
  24  *   while a link has 3 iterators: state, bandwidth and latency.
  25  * - #simgrid::kernel::profile::FutureEvtSet: makes it easy to find the next occurring event of all profiles
  26  */
  27 class XBT_PUBLIC DatedValue {
  28 public:
  29   double date_          = 0;
  30   double value_         = 0;
  31   explicit DatedValue() = default;
  32   explicit DatedValue(double d, double v) : date_(d), value_(v) {}
  33   bool operator==(DatedValue const& e2) const;
  34   bool operator!=(DatedValue const& e2) const { return not(*this == e2); }
  35 };
  36
  37 std::ostream& operator << (std::ostream& out, const DatedValue& dv);
  38 /**
  39  * @brief Simple builder for Profile classes.
  40  *
  41  * It can be used to create profiles for links, hosts or disks.
  42  */
  43 class XBT_PUBLIC ProfileBuilder {
  44 public:
  45   /** @brief A function called to populate the set of timed-values of a profile.
  46    *
  47    * When the profile is repeating, the callback is called only once upon Profile construction.
  48    * Then the timed values are repeated after a fixed repeat_delay.
  49    *
  50    * When the profile is not repeating, the callback is called each time the profile data has been exhausted.
  51    * More precisely, each time an FutureEvtSet reached the end of the vector of timed values of the profile.
  52    *
  53    * Note that the callback is only supposed to append values to the values vector, not modify or remove existing ones,
  54    * because other FutureEvtSet may still need previous values.
  55    *
  56    * @param values The vector of the profile values, where new data can be appended.
  57    *
  58    */
  59   using UpdateCb = void(std::vector<DatedValue>& values);
  60
  61   static Profile* from_file(const std::string& path);
  62   static Profile* from_string(const std::string& name, const std::string& input, double periodicity);
  63
  64   static Profile* from_void();
  65
  66   /** Create a profile from a callback
  67    *
  68    * @param name: The *unique* name of the profile
  69    * @param cb: A callback object/function to populate the profile
  70    * @param repeat_delay: Ignored if strictly negative. Otherwise, profile is repeating and repeat_delay is inserted
  71    * between two iterations.
  72    *
  73    * @return the newly created profile
  74    */
  75   static Profile* from_callback(const std::string& name, const std::function<UpdateCb>& cb, double repeat_delay);
  76 };
  77
  78 } // namespace profile
  79 } // namespace kernel
  80 } // namespace simgrid
  81
  82 #endif /* SIMGRID_KERNEL_PROFILEBUILDER_HPP */