Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
start including S4U in the doc
[simgrid.git] / 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 */