include/simgrid/s4u/actor.hpp

   1 /* Copyright (c) 2006-2016. 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 <stdexcept>
  10 #include <xbt/base.h>
  11 #include <simgrid/simix.h>
  12 #include <simgrid/s4u/forward.hpp>
  13
  14 namespace simgrid {
  15 namespace s4u {
  16
  17 /** @defgroup  s4u_actor Actors: simulation agents
  18  *  @addtogroup S4U_API
  19  */
  20
  21 /** @addtogroup s4u_actor
  22  *
  23  * @tableofcontents
  24  *
  25  * An actor is an independent stream of execution in your distributed application.
  26  *
  27  * You can think of an actor as a process in your distributed application, or as a thread in a multithreaded program.
  28  * This is the only component in SimGrid that actually does something on its own, executing its own code.
  29  * A resource will not get used if you don't schedule activities on them. This is the code of Actors that create and schedule these activities.
  30  *
  31  * An actor is located on a (simulated) host, but it can interact
  32  * with the whole simulated platform.
  33  *
  34  * (back to the @ref s4u_api "S4U documentation")
  35  *
  36  * @section s4u_actor_def Defining an Actor
  37  *
  38  * The code of an actor (ie, the code that this actor will run when starting) the () operator.
  39  * In this code, your actor can use the functions of the simgrid::s4u::this_actor namespace to interact with the world.
  40  *
  41  * For example, a Worker actor should be declared as follows:
  42  *
  43  * \code{.cpp}
  44  * #include "s4u/actor.hpp"
  45  *
  46  * class Worker {
  47  *   void operator()() { // Two pairs of () because this defines the method called ()
  48  *     printf("Hello s4u");
  49  *     simgrid::s4u::this_actor::execute(5*1024*1024); // Get the worker executing a task of 5 MFlops
  50  *   }
  51  * };
  52  * \endcode
  53  *
  54  * @section s4u_actor_new Creating a new instance of your Actor
  55  *
  56  * // Then later in your main() function or so:
  57  *   ...
  58  *   new Actor("worker", host, Worker());
  59  *   ...
  60  *
  61  * You can start your actors with simple @c new, for example from the @c main function,
  62  * but this is usually considered as a bad habit as it makes it harder to test your application
  63  * in differing settings. Instead, you are advised to use an XML deployment file using
  64  * s4u::Engine::loadDeployment() to start your actors.
  65  *
  66  *  @{
  67  */
  68
  69 /** @brief Simulation Agent (see \ref s4u_actor)*/
  70 XBT_PUBLIC_CLASS Actor {
  71   explicit Actor(smx_process_t smx_proc);
  72 public:
  73   Actor(const char* name, s4u::Host *host, double killTime, std::function<void()> code);
  74   Actor(const char* name, s4u::Host *host, std::function<void()> code)
  75     : Actor(name, host, -1, std::move(code)) {};
  76   template<class C>
  77   Actor(const char* name, s4u::Host *host, C code)
  78     : Actor(name, host, -1, std::function<void()>(std::move(code))) {}
  79   ~Actor();
  80
  81   /** Retrieves the actor that have the given PID (or NULL if not existing) */
  82   //static Actor *byPid(int pid); not implemented
  83
  84   /** Retrieves the name of that actor */
  85   const char* getName();
  86   /** Retrieves the host on which that actor is running */
  87   s4u::Host *getHost();
  88   /** Retrieves the PID of that actor */
  89   int getPid();
  90
  91   /** If set to true, the actor will automatically restart when its host reboots */
  92   void setAutoRestart(bool autorestart);
  93   /** Sets the time at which that actor should be killed */
  94   void setKillTime(double time);
  95   /** Retrieves the time at which that actor will be killed (or -1 if not set) */
  96   double getKillTime();
  97
  98   /** Ask the actor to die.
  99    *
 100    * It will only notice your request when doing a simcall next time (a communication or similar).
 101    * SimGrid sometimes have issues when you kill actors that are currently communicating and such. We are working on it to fix the issues.
 102    */
 103   void kill();
 104
 105   static void kill(int pid);
 106
 107   /**
 108    * Wait for the actor to finish.
 109    */
 110   void join();
 111
 112   // Static methods on all actors:
 113
 114   /** Ask kindly to all actors to die. Only the issuer will survive. */
 115   static void killAll();
 116
 117 protected:
 118   smx_process_t getInferior() {return pimpl_;}
 119 private:
 120   smx_process_t pimpl_ = nullptr;
 121 };
 122
 123 /** @brief Static methods working on the current actor (see @ref s4u_actor) */
 124 namespace this_actor {
 125
 126   /** Block the actor sleeping for that amount of seconds (may throws hostFailure) */
 127   XBT_PUBLIC(void) sleep(double duration);
 128
 129   /** Block the actor, computing the given amount of flops */
 130   XBT_PUBLIC(e_smx_state_t) execute(double flop);
 131
 132   /** Block the actor until it gets a message from the given mailbox.
 133    *
 134    * See \ref Comm for the full communication API (including non blocking communications).
 135    */
 136   XBT_PUBLIC(void*) recv(Mailbox &chan);
 137
 138   /** Block the actor until it delivers a message of the given simulated size to the given mailbox
 139    *
 140    * See \ref Comm for the full communication API (including non blocking communications).
 141   */
 142   XBT_PUBLIC(void) send(Mailbox &chan, void*payload, size_t simulatedSize);
 143
 144 };
 145
 146 /** @} */
 147
 148 }} // namespace simgrid::s4u
 149
 150
 151 #endif /* SIMGRID_S4U_ACTOR_HPP */