include/simgrid/s4u/Actor.hpp

   1 /* Copyright (c) 2006-2021. 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_S4U_ACTOR_HPP
   7 #define SIMGRID_S4U_ACTOR_HPP
   8
   9 #include <simgrid/forward.h>
  10
  11 #include <simgrid/chrono.hpp>
  12 #include <xbt/Extendable.hpp>
  13 #include <xbt/signal.hpp>
  14 #include <xbt/string.hpp>
  15
  16 #include <functional>
  17 #include <unordered_map>
  18
  19 namespace simgrid {
  20
  21 extern template class XBT_PUBLIC xbt::Extendable<s4u::Actor>;
  22
  23 namespace s4u {
  24
  25 /** An actor is an independent stream of execution in your distributed application.
  26  *
  27  * @beginrst
  28  * It is located on a (simulated) :cpp:class:`host <simgrid::s4u::Host>`, but can interact
  29  * with the whole simulated platform.
  30  *
  31  * You can think of an actor as a process in your distributed application, or as a thread in a multithreaded program.
  32  * This is the only component in SimGrid that actually does something on its own, executing its own code.
  33  * A resource will not get used if you don't schedule activities on them. This is the code of Actors that create and
  34  * schedule these activities. **Please refer to the** :ref:`examples <s4u_ex_actors>` **for more information.**
  35  *
  36  * This API is strongly inspired from the C++11 threads.
  37  * The `documentation of this standard <http://en.cppreference.com/w/cpp/thread>`_
  38  * may help to understand the philosophy of the SimGrid actors.
  39  *
  40  * @endrst
  41  */
  42 class XBT_PUBLIC Actor : public xbt::Extendable<Actor> {
  43 #ifndef DOXYGEN
  44   friend Exec;
  45   friend Mailbox;
  46   friend kernel::actor::ActorImpl;
  47   friend kernel::activity::MailboxImpl;
  48
  49   kernel::actor::ActorImpl* const pimpl_;
  50 #endif
  51
  52   explicit Actor(kernel::actor::ActorImpl* pimpl) : pimpl_(pimpl) {}
  53
  54 public:
  55 #ifndef DOXYGEN
  56   // ***** No copy *****
  57   Actor(Actor const&) = delete;
  58   Actor& operator=(Actor const&) = delete;
  59
  60   // ***** Reference count *****
  61   friend XBT_PUBLIC void intrusive_ptr_add_ref(const Actor* actor);
  62   friend XBT_PUBLIC void intrusive_ptr_release(const Actor* actor);
  63 #endif
  64   /** Retrieve the amount of references on that object. Useful to debug the automatic refcounting */
  65   int get_refcount() const;
  66
  67   // ***** Actor creation *****
  68   /** Retrieve a reference to myself */
  69   static Actor* self();
  70
  71 #ifndef DOXYGEN
  72   static xbt::signal<void(Actor&)> on_creation;
  73   static xbt::signal<void(Actor const&)> on_suspend;
  74   static xbt::signal<void(Actor const&)> on_resume;
  75   static xbt::signal<void(Actor const&)> on_sleep;
  76   static xbt::signal<void(Actor const&)> on_wake_up;
  77   static xbt::signal<void(const Actor&, const Host& previous_location)> on_host_change;
  78   static xbt::signal<void(Actor const&)> on_termination;
  79   static xbt::signal<void(Actor const&)> on_destruction;
  80 #endif
  81
  82 public:
  83   /** Add a callback fired when a new actor has been created **/
  84   static void on_creation_cb(const std::function<void(Actor&)>& cb) { on_creation.connect(cb); }
  85   /** Add a callback fired when an actor has been suspended**/
  86   static void on_suspend_cb(const std::function<void(Actor const&)> cb) { on_suspend.connect(cb); }
  87   /** Add a callback fired when an actor has been resumed **/
  88   static void on_resume_cb(const std::function<void(Actor const&)>& cb) { on_resume.connect(cb); }
  89   /** Add a callback fired when an actor starts sleeping **/
  90   static void on_sleep_cb(const std::function<void(Actor const&)>& cb) { on_sleep.connect(cb); }
  91   /** Add a callback fired when an actor wakes up from a sleep **/
  92   static void on_wake_up_cb(const std::function<void(Actor const&)>& cb) { on_wake_up.connect(cb); }
  93   /** Add a callback fired when an actor is has been migrated to another host **/
  94   static void on_host_change_cb(const std::function<void(const Actor&, const Host& previous_location)>& cb)
  95   {
  96     on_host_change.connect(cb);
  97   }
  98
  99   /** Add a callback fired when an actor terminates its code.
 100    *  @beginrst
 101    *  The actor may continue to exist if it is still referenced in the simulation, but it's not active anymore.
 102    *  If you want to free extra data when the actor's destructor is called, use :cpp:var:`Actor::on_destruction`.
 103    *  If you want to register to the termination of a given actor, use :cpp:func:`this_actor::on_exit()` instead.
 104    *  @endrst
 105    */
 106   static void on_termination_cb(const std::function<void(Actor const&)>& cb) { on_termination.connect(cb); }
 107   /** Add a callback fired when an actor is about to disappear (its destructor was called).
 108    *  This signal is fired for any destructed actor, which is mostly useful when designing plugins and extensions.
 109    *  If you want to react to the end of the actor's code, use Actor::on_termination instead.
 110    *  If you want to register to the termination of a given actor, use this_actor::on_exit() instead.*/
 111   static void on_destruction_cb(const std::function<void(Actor const&)>& cb) { on_destruction.connect(cb); }
 112
 113   /** Create an actor from a std::function<void()>.
 114    *  If the actor is restarted, it gets a fresh copy of the function. */
 115   static ActorPtr create(const std::string& name, s4u::Host* host, const std::function<void()>& code);
 116   /** Create an actor, but don't start it yet.
 117    *
 118    * This is useful to set some properties or extension before actually starting it */
 119   static ActorPtr init(const std::string& name, s4u::Host* host);
 120   ActorPtr set_stacksize(unsigned stacksize);
 121   /** Start a previously initialized actor */
 122   ActorPtr start(const std::function<void()>& code);
 123
 124   template <class F> ActorPtr start(F code) { return start(std::function<void()>(std::move(code))); }
 125
 126   template <class F, class... Args,
 127   // This constructor is enabled only if the call code(args...) is valid:
 128 #ifndef DOXYGEN /* breathe seem to choke on function signatures in template parameter, see breathe#611 */
 129             typename = typename std::result_of_t<F(Args...)>
 130 #endif
 131             >
 132   ActorPtr start(F code, Args... args)
 133   {
 134     return start(std::bind(std::move(code), std::move(args)...));
 135   }
 136
 137   ActorPtr start(const std::function<void()>& code, std::vector<std::string> args);
 138
 139   /** Create an actor from a callable thing. */
 140   template <class F> static ActorPtr create(const std::string& name, s4u::Host* host, F code)
 141   {
 142     return create(name, host, std::function<void()>(std::move(code)));
 143   }
 144
 145   /** Create an actor using a callable thing and its arguments.
 146    *
 147    * Note that the arguments will be copied, so move-only parameters are forbidden */
 148
 149   template <class F, class... Args,
 150             // This constructor is enabled only if the call code(args...) is valid:
 151 #ifndef DOXYGEN /* breathe seem to choke on function signatures in template parameter, see breathe#611 */
 152             typename = typename std::result_of_t<F(Args...)>
 153 #endif
 154             >
 155   static ActorPtr create(const std::string& name, s4u::Host* host, F code, Args... args)
 156   {
 157     return create(name, host, std::bind(std::move(code), std::move(args)...));
 158   }
 159
 160   /** Create actor from function name and a vector of strings as arguments. */
 161   static ActorPtr create(const std::string& name, s4u::Host* host, const std::string& function,
 162                          std::vector<std::string> args);
 163
 164   // ***** Methods *****
 165   /** This actor will be automatically terminated when the last non-daemon actor finishes **/
 166   void daemonize();
 167
 168   /** Returns whether or not this actor has been daemonized or not **/
 169   bool is_daemon() const;
 170   static bool is_maestro();
 171
 172   /** Retrieves the name of that actor as a C++ string */
 173   const simgrid::xbt::string& get_name() const;
 174   /** Retrieves the name of that actor as a C string */
 175   const char* get_cname() const;
 176   /** Retrieves the host on which that actor is running */
 177   Host* get_host() const;
 178   /** Retrieves the actor ID of that actor */
 179   aid_t get_pid() const;
 180   /** Retrieves the actor ID of that actor's creator */
 181   aid_t get_ppid() const;
 182
 183   /** Suspend an actor, that is blocked until resumeed by another actor */
 184   void suspend();
 185
 186   /** Resume an actor that was previously suspended */
 187   void resume();
 188
 189   /** Returns true if the actor is suspended. */
 190   bool is_suspended() const;
 191
 192   /** If set to true, the actor will automatically restart when its host reboots */
 193   void set_auto_restart(bool autorestart);
 194
 195   /** Add a function to the list of "on_exit" functions for the current actor. The on_exit functions are the functions
 196    * executed when your actor is killed. You should use them to free the data used by your actor.
 197    *
 198    * Please note that functions registered in this signal cannot do any simcall themselves. It means that they cannot
 199    * send or receive messages, acquire or release mutexes, nor even modify a host property or something. Not only are
 200    * blocking functions forbidden in this setting, but also modifications to the global state.
 201    *
 202    * The parameter of on_exit's callbacks denotes whether or not the actor's execution failed.
 203    * It will be set to true if the actor was killed or failed because of an exception,
 204    * while it will remain to false if the actor terminated gracefully.
 205    */
 206   void on_exit(const std::function<void(bool /*failed*/)>& fun) const;
 207
 208   /** Sets the time at which that actor should be killed */
 209   void set_kill_time(double time);
 210   /** Retrieves the time at which that actor will be killed (or -1 if not set) */
 211   double get_kill_time() const;
 212
 213   /** @brief Moves the actor to another host
 214    *
 215    * If the actor is currently blocked on an execution activity, the activity is also
 216    * migrated to the new host. If it's blocked on another kind of activity, an error is
 217    * raised as the mandated code is not written yet. Please report that bug if you need it.
 218    *
 219    * Asynchronous activities started by the actor are not migrated automatically, so you have
 220    * to take care of this yourself (only you knows which ones should be migrated).
 221    */
 222   void set_host(Host* new_host);
 223
 224   /** Ask the actor to die.
 225    *
 226    * Any blocking activity will be canceled, and it will be rescheduled to free its memory.
 227    * Being killed is not something that actors can defer or avoid.
 228    */
 229   void kill();
 230
 231   /** Retrieves the actor that have the given PID (or nullptr if not existing) */
 232   static ActorPtr by_pid(aid_t pid);
 233
 234   /** Wait for the actor to finish.
 235    *
 236    * Blocks the calling actor until the joined actor is terminated. If actor alice executes bob.join(), then alice is
 237    * blocked until bob terminates.
 238    */
 239   void join() const;
 240
 241   /** Wait for the actor to finish, or for the timeout to elapse.
 242    *
 243    * Blocks the calling actor until the joined actor is terminated. If actor alice executes bob.join(), then alice is
 244    * blocked until bob terminates.
 245    */
 246   void join(double timeout) const;
 247   /** Kill that actor and restart it from start. */
 248   Actor* restart();
 249
 250   /** Kill all actors (but the issuer). Being killed is not something that actors can delay or avoid. */
 251   static void kill_all();
 252
 253   /** Returns the internal implementation of this actor */
 254   kernel::actor::ActorImpl* get_impl() const { return pimpl_; }
 255
 256   /** Retrieve the list of properties for that actor */
 257   const std::unordered_map<std::string, std::string>*
 258   get_properties() const; // FIXME: do not export the map, but only the keys or something
 259
 260   /** Retrieve the property value (or nullptr if not set) */
 261   const char* get_property(const std::string& key) const;
 262
 263   /** Set a property (old values will be overwritten) */
 264   void set_property(const std::string& key, const std::string& value);
 265 };
 266
 267 /** @ingroup s4u_api
 268  *  @brief Static methods working on the current actor (see @ref s4u::Actor) */
 269 namespace this_actor {
 270
 271 XBT_PUBLIC bool is_maestro();
 272
 273 /** Block the current actor sleeping for that amount of seconds */
 274 XBT_PUBLIC void sleep_for(double duration);
 275 /** Block the current actor sleeping until the specified timestamp */
 276 XBT_PUBLIC void sleep_until(double wakeup_time);
 277
 278 template <class Rep, class Period> inline void sleep_for(std::chrono::duration<Rep, Period> duration)
 279 {
 280   auto seconds = std::chrono::duration_cast<SimulationClockDuration>(duration);
 281   this_actor::sleep_for(seconds.count());
 282 }
 283
 284 template <class Duration> inline void sleep_until(const SimulationTimePoint<Duration>& wakeup_time)
 285 {
 286   auto timeout_native = std::chrono::time_point_cast<SimulationClockDuration>(wakeup_time);
 287   this_actor::sleep_until(timeout_native.time_since_epoch().count());
 288 }
 289
 290 /** Block the current actor, computing the given amount of flops */
 291 XBT_PUBLIC void execute(double flop);
 292
 293 /** Block the current actor, computing the given amount of flops at the given priority.
 294  *  An execution of priority 2 computes twice as fast as an execution at priority 1. */
 295 XBT_PUBLIC void execute(double flop, double priority);
 296
 297 /**
 298  * @example examples/cpp/exec-ptask/s4u-exec-ptask.cpp
 299  */
 300
 301 /** Block the current actor until the built parallel execution terminates
 302  *
 303  * @beginrst
 304  * .. _API_s4u_parallel_execute:
 305  *
 306  * **Example of use:** `examples/cpp/exec-ptask/s4u-exec-ptask.cpp
 307  * <https://framagit.org/simgrid/simgrid/tree/master/examples/cpp/exec-ptask/s4u-exec-ptask.cpp>`_
 308  *
 309  * Parallel executions convenient abstractions of parallel computational kernels that span over several machines,
 310  * such as a PDGEM and the other ScaLAPACK routines. If you are interested in the effects of such parallel kernel
 311  * on the platform (e.g. to schedule them wisely), there is no need to model them in all details of their internal
 312  * execution and communications. It is much more convenient to model them as a single execution activity that spans
 313  * over several hosts. This is exactly what s4u's Parallel Executions are.
 314  *
 315  * To build such an object, you need to provide a list of hosts that are involved in the parallel kernel (the
 316  * actor's own host may or may not be in this list) and specify the amount of computations that should be done by
 317  * each host, using a vector of flops amount. Then, you should specify the amount of data exchanged between each
 318  * hosts during the parallel kernel. For that, a matrix of values is expected.
 319  *
 320  * It is OK to build a parallel execution without any computation and/or without any communication.
 321  * Just pass an empty vector to the corresponding parameter.
 322  *
 323  * For example, if your list of hosts is ``[host0, host1]``, passing a vector ``[1000, 2000]`` as a `flops_amount`
 324  * vector means that `host0` should compute 1000 flops while `host1` will compute 2000 flops. A matrix of
 325  * communications' sizes of ``[0, 1, 2, 3]`` specifies the following data exchanges:
 326  *
 327  * - from host0: [ to host0:  0 bytes; to host1: 1 byte ]
 328  *
 329  * - from host1: [ to host0: 2 bytes; to host1: 3 bytes ]
 330  *
 331  * Or, in other words:
 332  *
 333  * - From host0 to host0: 0 bytes are exchanged
 334  *
 335  * - From host0 to host1: 1 byte is exchanged
 336  *
 337  * - From host1 to host0: 2 bytes are exchanged
 338  *
 339  * - From host1 to host1: 3 bytes are exchanged
 340  *
 341  * In a parallel execution, all parts (all executions on each hosts, all communications) progress exactly at the
 342  * same pace, so they all terminate at the exact same pace. If one part is slow because of a slow resource or
 343  * because of contention, this slows down the parallel execution as a whole.
 344  *
 345  * These objects are somewhat surprising from a modeling point of view. For example, the unit of their speed is
 346  * somewhere between flop/sec and byte/sec. Arbitrary parallel executions will simply not work with the usual platform
 347  * models, and you must :ref:`use the ptask_L07 host model <options_model_select>` for that. Note that you can mix
 348  * regular executions and communications with parallel executions, provided that the host model is ptask_L07.
 349  *
 350  * @endrst
 351  */
 352 /** Block the current actor until the built parallel execution completes */
 353 XBT_PUBLIC void parallel_execute(const std::vector<s4u::Host*>& hosts, const std::vector<double>& flops_amounts,
 354                                  const std::vector<double>& bytes_amounts);
 355
 356 /** Initialize a sequential execution that must then be started manually */
 357 XBT_PUBLIC ExecPtr exec_init(double flops_amounts);
 358 /** Initialize a parallel execution that must then be started manually */
 359 XBT_PUBLIC ExecPtr exec_init(const std::vector<s4u::Host*>& hosts, const std::vector<double>& flops_amounts,
 360                              const std::vector<double>& bytes_amounts);
 361
 362 XBT_PUBLIC ExecPtr exec_async(double flops_amounts);
 363
 364 /** @brief Returns the actor ID of the current actor. */
 365 XBT_PUBLIC aid_t get_pid();
 366
 367 /** @brief Returns the ancestor's actor ID of the current actor. */
 368 XBT_PUBLIC aid_t get_ppid();
 369
 370 /** @brief Returns the name of the current actor. */
 371 XBT_PUBLIC std::string get_name();
 372 /** @brief Returns the name of the current actor as a C string. */
 373 XBT_PUBLIC const char* get_cname();
 374
 375 /** @brief Returns the name of the host on which the current actor is running. */
 376 XBT_PUBLIC Host* get_host();
 377
 378 /** @brief Suspend the current actor, that is blocked until resume()ed by another actor. */
 379 XBT_PUBLIC void suspend();
 380
 381 /** @brief Yield the current actor. */
 382 XBT_PUBLIC void yield();
 383
 384 /** @brief kill the current actor. */
 385 XBT_ATTRIB_NORETURN XBT_PUBLIC void exit();
 386
 387 /** @brief Add a function to the list of "on_exit" functions of the current actor.
 388  *
 389  * The on_exit functions are the functions executed when your actor is killed. You should use them to free the data used
 390  * by your actor.
 391  *
 392  * Please note that functions registered in this signal cannot do any simcall themselves. It means that they cannot
 393  * send or receive messages, acquire or release mutexes, nor even modify a host property or something. Not only are
 394  * blocking functions forbidden in this setting, but also modifications to the global state.
 395  *
 396  * The parameter of on_exit's callbacks denotes whether or not the actor's execution failed.
 397  * It will be set to true if the actor was killed or failed because of an exception or if the simulation deadlocked,
 398  * while it will remain to false if the actor terminated gracefully.
 399  */
 400
 401 XBT_PUBLIC void on_exit(const std::function<void(bool)>& fun);
 402
 403 /** @brief Migrate the current actor to a new host. */
 404 XBT_PUBLIC void set_host(Host* new_host);
 405 }
 406
 407
 408 }} // namespace simgrid::s4u
 409
 410
 411 #endif /* SIMGRID_S4U_ACTOR_HPP */