include/simgrid/kernel/ProfileBuilder.hpp

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