SimGrid  3.16
Versatile Simulation of Distributed Systems
simgrid::s4u::Actor Class Reference

Detailed Description

An actor is an independent stream of execution in your distributed application.

You can think of an actor as a process in your distributed application, or as a thread in a multithreaded program. This is the only component in SimGrid that actually does something on its own, executing its own code. 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.

An actor is located on a (simulated) host, but it can interact with the whole simulated platform.

The s4u::Actor API is strongly inspired from the C++11 threads. The documentation of this standard may help to understand the philosophy of the S4U Actors.

Defining the skeleton of an Actor

As in the C++11 standard, you can declare the code of your actor either as a pure function or as an object. It is very simple with functions:

#include "s4u/actor.hpp"
// Declare the code of your worker
void worker() {
printf("Hello s4u");
simgrid::s4u::this_actor::execute(5*1024*1024); // Get the worker executing a task of 5 MFlops
};
// From your main or from another actor, create your actor on the host Jupiter
// The following line actually creates a new actor, even if there is no "new".
Actor("Alice", simgrid::s4u::Host::by_name("Jupiter"), worker);

But some people prefer to encapsulate their actors in classes and objects to save the actor state in a cleanly dedicated location. The syntax is slightly more complicated, but not much.

#include "s4u/actor.hpp"
// Declare the class representing your actors
class Worker {
public:
void operator()() { // Two pairs of () because this defines the method called ()
printf("Hello s4u");
simgrid::s4u::this_actor::execute(5*1024*1024); // Get the worker executing a task of 5 MFlops
}
};
// From your main or from another actor, create your actor. Note the () after Worker
Actor("Bob", simgrid::s4u::Host::by_name("Jupiter"), Worker());

Fleshing your actor

The body of your actor can use the functions of the simgrid::s4u::this_actor namespace to interact with the world. This namespace contains the methods to start new activities (executions, communications, etc), and to get informations about the currently running thread (its location, etc).

Please refer to the full API .

Using a deployment file

Warning
This is currently not working with S4U. Sorry about that.

The best practice is to use an external deployment file as follows, because it makes it easier to test your application in differing settings. Load this file with s4u::Engine::loadDeployment() before the simulation starts. Refer to the Deploy the simulation section for more information.

<?xml version='1.0'?>
<!DOCTYPE platform SYSTEM "http://simgrid.gforge.inria.fr/simgrid/simgrid.dtd">
<platform version="4">
<!-- Start a process called 'master' on the host called 'Tremblay' -->
<process host="Tremblay" function="master">
<!-- Here come the parameter that you want to feed to this instance of master -->
<argument value="20"/> <!-- argv[1] -->
<argument value="50000000"/> <!-- argv[2] -->
<argument value="1000000"/> <!-- argv[3] -->
<argument value="5"/> <!-- argv[4] -->
</process>
<!-- Start a process called 'worker' on the host called 'Jupiter' -->
<process host="Jupiter" function="worker"/> <!-- Don't provide any parameter ->>
</platform>

Simulation Agent

#include <Actor.hpp>

Inheritance diagram for simgrid::s4u::Actor:
simgrid::xbt::Extendable< Actor > simgrid::xbt::Extendable< Actor >

Public Member Functions

 Actor (Actor const &)=delete
 
Actoroperator= (Actor const &)=delete
 
const char * cname ()
 Retrieves the name of that actor as a C string. More...
 
simgrid::xbt::string name ()
 Retrieves the name of that actor as a C++ string. More...
 
s4u::Hosthost ()
 Retrieves the host on which that actor is running. More...
 
aid_t pid ()
 Retrieves the PID of that actor. More...
 
aid_t ppid ()
 Retrieves the PPID of that actor. More...
 
void suspend ()
 Suspend an actor by suspending the task on which it was waiting for the completion. More...
 
void resume ()
 Resume a suspended process by resuming the task on which it was waiting for the completion. More...
 
int isSuspended ()
 Returns true if the process is suspended. More...
 
void setAutoRestart (bool autorestart)
 If set to true, the actor will automatically restart when its host reboots. More...
 
void onExit (int_f_pvoid_pvoid_t fun, void *data)
 Add a function to the list of "on_exit" functions for the current actor. More...
 
void setKillTime (double time)
 Sets the time at which that actor should be killed. More...
 
double killTime ()
 Retrieves the time at which that actor will be killed (or -1 if not set) More...
 
void migrate (Host *new_host)
 
void kill ()
 Ask the actor to die. More...
 
void join ()
 Wait for the actor to finish. More...
 
simix::ActorImplgetImpl ()
 Returns the internal implementation of this actor. More...
 
const char * property (const char *key)
 Retrieve the property value (or nullptr if not set) More...
 
void setProperty (const char *key, const char *value)
 
 Actor (Actor const &)=delete
 
Actoroperator= (Actor const &)=delete
 
const char * cname ()
 Retrieves the name of that actor as a C string. More...
 
simgrid::xbt::string name ()
 Retrieves the name of that actor as a C++ string. More...
 
s4u::Hosthost ()
 Retrieves the host on which that actor is running. More...
 
aid_t pid ()
 Retrieves the PID of that actor. More...
 
aid_t ppid ()
 Retrieves the PPID of that actor. More...
 
void suspend ()
 Suspend an actor by suspending the task on which it was waiting for the completion. More...
 
void resume ()
 Resume a suspended process by resuming the task on which it was waiting for the completion. More...
 
int isSuspended ()
 Returns true if the process is suspended. More...
 
void setAutoRestart (bool autorestart)
 If set to true, the actor will automatically restart when its host reboots. More...
 
void onExit (int_f_pvoid_pvoid_t fun, void *data)
 Add a function to the list of "on_exit" functions for the current actor. More...
 
void setKillTime (double time)
 Sets the time at which that actor should be killed. More...
 
double killTime ()
 Retrieves the time at which that actor will be killed (or -1 if not set) More...
 
void migrate (Host *new_host)
 
void kill ()
 Ask the actor to die. More...
 
void join ()
 Wait for the actor to finish. More...
 
simix::ActorImplgetImpl ()
 Returns the internal implementation of this actor. More...
 
const char * property (const char *key)
 Retrieve the property value (or nullptr if not set) More...
 
void setProperty (const char *key, const char *value)
 
- Public Member Functions inherited from simgrid::xbt::Extendable< Actor >
 Extendable ()
 
 Extendable ()
 
 ~Extendable ()
 
 ~Extendable ()
 
voidextension (std::size_t rank)
 
U * extension (Extension< Actor, U > rank)
 
U * extension ()
 
voidextension (std::size_t rank)
 
U * extension (Extension< Actor, U > rank)
 
U * extension ()
 
void extension_set (std::size_t rank, void *value, bool use_dtor=true)
 
void extension_set (Extension< Actor, U > rank, U *value, bool use_dtor=true)
 
void extension_set (U *p)
 
void extension_set (std::size_t rank, void *value, bool use_dtor=true)
 
void extension_set (Extension< Actor, U > rank, U *value, bool use_dtor=true)
 
void extension_set (U *p)
 

Static Public Member Functions

static ActorPtr self ()
 Retrieve a reference to myself. More...
 
static ActorPtr createActor (const char *name, s4u::Host *host, std::function< void()> code)
 Create an actor using a function. More...
 
static ActorPtr createActor (const char *name, s4u::Host *host, std::function< void(std::vector< std::string > *)> code, std::vector< std::string > *args)
 
template<class F , class... Args, typename = typename std::result_of<F(Args...)>::type>
static ActorPtr createActor (const char *name, s4u::Host *host, F code, Args... args)
 Create an actor using code. More...
 
static ActorPtr createActor (const char *name, s4u::Host *host, const char *function, std::vector< std::string > args)
 
static void kill (aid_t pid)
 
static ActorPtr byPid (aid_t pid)
 Retrieves the actor that have the given PID (or nullptr if not existing) More...
 
static void killAll ()
 Ask kindly to all actors to die. More...
 
static void killAll (int resetPid)
 
static ActorPtr self ()
 Retrieve a reference to myself. More...
 
static ActorPtr createActor (const char *name, s4u::Host *host, std::function< void()> code)
 Create an actor using a function. More...
 
static ActorPtr createActor (const char *name, s4u::Host *host, std::function< void(std::vector< std::string > *)> code, std::vector< std::string > *args)
 
template<class F , class... Args, typename = typename std::result_of<F(Args...)>::type>
static ActorPtr createActor (const char *name, s4u::Host *host, F code, Args... args)
 Create an actor using code. More...
 
static ActorPtr createActor (const char *name, s4u::Host *host, const char *function, std::vector< std::string > args)
 
static void kill (aid_t pid)
 
static ActorPtr byPid (aid_t pid)
 Retrieves the actor that have the given PID (or nullptr if not existing) More...
 
static void killAll ()
 Ask kindly to all actors to die. More...
 
static void killAll (int resetPid)
 
- Static Public Member Functions inherited from simgrid::xbt::Extendable< Actor >
static size_t extension_create (void(*deleter)(void *))
 
static Extension< Actor, U > extension_create (void(*deleter)(void *))
 
static Extension< Actor, U > extension_create ()
 
static size_t extension_create (void(*deleter)(void *))
 
static Extension< Actor, U > extension_create (void(*deleter)(void *))
 
static Extension< Actor, U > extension_create ()
 

Friends

void intrusive_ptr_add_ref (Actor *actor)
 
void intrusive_ptr_release (Actor *actor)
 
void intrusive_ptr_add_ref (Actor *actor)
 
void intrusive_ptr_release (Actor *actor)
 

Additional Inherited Members

- Protected Attributes inherited from simgrid::xbt::Extendable< Actor >
std::vector< void *> extensions_
 

Constructor & Destructor Documentation

◆ Actor() [1/2]

simgrid::s4u::Actor::Actor ( Actor const &  )
delete

◆ Actor() [2/2]

simgrid::s4u::Actor::Actor ( Actor const &  )
delete

Member Function Documentation

◆ operator=() [1/2]

Actor& simgrid::s4u::Actor::operator= ( Actor const &  )
delete

◆ self() [1/2]

ActorPtr simgrid::s4u::Actor::self ( )
static

Retrieve a reference to myself.

Examples:
examples/s4u/actor-migration/s4u_actor-migration.cpp.

◆ createActor() [1/8]

ActorPtr simgrid::s4u::Actor::createActor ( const char *  name,
s4u::Host host,
std::function< void()>  code 
)
static

◆ createActor() [2/8]

static ActorPtr simgrid::s4u::Actor::createActor ( const char *  name,
s4u::Host host,
std::function< void(std::vector< std::string > *)>  code,
std::vector< std::string > *  args 
)
inlinestatic

◆ createActor() [3/8]

template<class F , class... Args, typename = typename std::result_of<F(Args...)>::type>
static ActorPtr simgrid::s4u::Actor::createActor ( const char *  name,
s4u::Host host,
code,
Args...  args 
)
inlinestatic

Create an actor using code.

Using this constructor, move-only type can be used. The consequence is that we cannot copy the value and restart the process in its initial state. In order to use auto-restart, an explicit function must be passed instead.

◆ createActor() [4/8]

ActorPtr simgrid::s4u::Actor::createActor ( const char *  name,
s4u::Host host,
const char *  function,
std::vector< std::string args 
)
static

◆ cname() [1/2]

const char * simgrid::s4u::Actor::cname ( )

Retrieves the name of that actor as a C string.

◆ name() [1/2]

simgrid::xbt::string simgrid::s4u::Actor::name ( )

Retrieves the name of that actor as a C++ string.

◆ host() [1/2]

s4u::Host * simgrid::s4u::Actor::host ( )

Retrieves the host on which that actor is running.

◆ pid() [1/2]

aid_t simgrid::s4u::Actor::pid ( )

Retrieves the PID of that actor.

actor_id_t is an alias for unsigned long

◆ ppid() [1/2]

aid_t simgrid::s4u::Actor::ppid ( )

Retrieves the PPID of that actor.

actor_id_t is an alias for unsigned long

◆ suspend() [1/2]

void simgrid::s4u::Actor::suspend ( )

Suspend an actor by suspending the task on which it was waiting for the completion.

◆ resume() [1/2]

void simgrid::s4u::Actor::resume ( )

Resume a suspended process by resuming the task on which it was waiting for the completion.

◆ isSuspended() [1/2]

int simgrid::s4u::Actor::isSuspended ( )

Returns true if the process is suspended.

◆ setAutoRestart() [1/2]

void simgrid::s4u::Actor::setAutoRestart ( bool  autorestart)

If set to true, the actor will automatically restart when its host reboots.

◆ onExit() [1/2]

void simgrid::s4u::Actor::onExit ( int_f_pvoid_pvoid_t  fun,
void data 
)

Add a function to the list of "on_exit" functions for the current actor.

The on_exit functions are the functions executed when your actor is killed. You should use them to free the data used by your process.

◆ setKillTime() [1/2]

void simgrid::s4u::Actor::setKillTime ( double  time)

Sets the time at which that actor should be killed.

◆ killTime() [1/2]

double simgrid::s4u::Actor::killTime ( )

Retrieves the time at which that actor will be killed (or -1 if not set)

◆ migrate() [1/2]

void simgrid::s4u::Actor::migrate ( Host new_host)

◆ kill() [1/4]

void simgrid::s4u::Actor::kill ( )

Ask the actor to die.

Any blocking activity will be canceled, and it will be rescheduled to free its memory. Being killed is not something that actors can defer or avoid.

SimGrid still have sometimes issues when you kill actors that are currently communicating and such. Still. Please report any bug that you may encounter with a minimal working example.

◆ kill() [2/4]

void simgrid::s4u::Actor::kill ( aid_t  pid)
static

◆ byPid() [1/2]

ActorPtr simgrid::s4u::Actor::byPid ( aid_t  pid)
static

Retrieves the actor that have the given PID (or nullptr if not existing)

◆ join() [1/2]

void simgrid::s4u::Actor::join ( )

Wait for the actor to finish.

This blocks the calling actor until the actor on which we call join() is terminated

◆ killAll() [1/4]

void simgrid::s4u::Actor::killAll ( )
static

Ask kindly to all actors to die.

Only the issuer will survive.

◆ killAll() [2/4]

void simgrid::s4u::Actor::killAll ( int  resetPid)
static

◆ getImpl() [1/2]

smx_actor_t simgrid::s4u::Actor::getImpl ( )

Returns the internal implementation of this actor.

◆ property() [1/2]

const char * simgrid::s4u::Actor::property ( const char *  key)

Retrieve the property value (or nullptr if not set)

◆ setProperty() [1/2]

void simgrid::s4u::Actor::setProperty ( const char *  key,
const char *  value 
)

◆ operator=() [2/2]

Actor& simgrid::s4u::Actor::operator= ( Actor const &  )
delete

◆ self() [2/2]

static ActorPtr simgrid::s4u::Actor::self ( )
static

Retrieve a reference to myself.

◆ createActor() [5/8]

static ActorPtr simgrid::s4u::Actor::createActor ( const char *  name,
s4u::Host host,
std::function< void()>  code 
)
static

Create an actor using a function.

If the actor is restarted, the actor has a fresh copy of the function.

◆ createActor() [6/8]

static ActorPtr simgrid::s4u::Actor::createActor ( const char *  name,
s4u::Host host,
std::function< void(std::vector< std::string > *)>  code,
std::vector< std::string > *  args 
)
inlinestatic

◆ createActor() [7/8]

template<class F , class... Args, typename = typename std::result_of<F(Args...)>::type>
static ActorPtr simgrid::s4u::Actor::createActor ( const char *  name,
s4u::Host host,
code,
Args...  args 
)
inlinestatic

Create an actor using code.

Using this constructor, move-only type can be used. The consequence is that we cannot copy the value and restart the process in its initial state. In order to use auto-restart, an explicit function must be passed instead.

◆ createActor() [8/8]

static ActorPtr simgrid::s4u::Actor::createActor ( const char *  name,
s4u::Host host,
const char *  function,
std::vector< std::string args 
)
static

◆ cname() [2/2]

const char* simgrid::s4u::Actor::cname ( )

Retrieves the name of that actor as a C string.

◆ name() [2/2]

simgrid::xbt::string simgrid::s4u::Actor::name ( )

Retrieves the name of that actor as a C++ string.

◆ host() [2/2]

s4u::Host* simgrid::s4u::Actor::host ( )

Retrieves the host on which that actor is running.

◆ pid() [2/2]

aid_t simgrid::s4u::Actor::pid ( )

Retrieves the PID of that actor.

actor_id_t is an alias for unsigned long

◆ ppid() [2/2]

aid_t simgrid::s4u::Actor::ppid ( )

Retrieves the PPID of that actor.

actor_id_t is an alias for unsigned long

◆ suspend() [2/2]

void simgrid::s4u::Actor::suspend ( )

Suspend an actor by suspending the task on which it was waiting for the completion.

◆ resume() [2/2]

void simgrid::s4u::Actor::resume ( )

Resume a suspended process by resuming the task on which it was waiting for the completion.

◆ isSuspended() [2/2]

int simgrid::s4u::Actor::isSuspended ( )

Returns true if the process is suspended.

◆ setAutoRestart() [2/2]

void simgrid::s4u::Actor::setAutoRestart ( bool  autorestart)

If set to true, the actor will automatically restart when its host reboots.

◆ onExit() [2/2]

void simgrid::s4u::Actor::onExit ( int_f_pvoid_pvoid_t  fun,
void data 
)

Add a function to the list of "on_exit" functions for the current actor.

The on_exit functions are the functions executed when your actor is killed. You should use them to free the data used by your process.

◆ setKillTime() [2/2]

void simgrid::s4u::Actor::setKillTime ( double  time)

Sets the time at which that actor should be killed.

◆ killTime() [2/2]

double simgrid::s4u::Actor::killTime ( )

Retrieves the time at which that actor will be killed (or -1 if not set)

◆ migrate() [2/2]

void simgrid::s4u::Actor::migrate ( Host new_host)

◆ kill() [3/4]

void simgrid::s4u::Actor::kill ( )

Ask the actor to die.

Any blocking activity will be canceled, and it will be rescheduled to free its memory. Being killed is not something that actors can defer or avoid.

SimGrid still have sometimes issues when you kill actors that are currently communicating and such. Still. Please report any bug that you may encounter with a minimal working example.

◆ kill() [4/4]

static void simgrid::s4u::Actor::kill ( aid_t  pid)
static

◆ byPid() [2/2]

static ActorPtr simgrid::s4u::Actor::byPid ( aid_t  pid)
static

Retrieves the actor that have the given PID (or nullptr if not existing)

◆ join() [2/2]

void simgrid::s4u::Actor::join ( )

Wait for the actor to finish.

This blocks the calling actor until the actor on which we call join() is terminated

◆ killAll() [3/4]

static void simgrid::s4u::Actor::killAll ( )
static

Ask kindly to all actors to die.

Only the issuer will survive.

◆ killAll() [4/4]

static void simgrid::s4u::Actor::killAll ( int  resetPid)
static

◆ getImpl() [2/2]

simix::ActorImpl* simgrid::s4u::Actor::getImpl ( )

Returns the internal implementation of this actor.

◆ property() [2/2]

const char* simgrid::s4u::Actor::property ( const char *  key)

Retrieve the property value (or nullptr if not set)

◆ setProperty() [2/2]

void simgrid::s4u::Actor::setProperty ( const char *  key,
const char *  value 
)

Friends And Related Function Documentation

◆ intrusive_ptr_add_ref [1/2]

void intrusive_ptr_add_ref ( Actor actor)
friend

◆ intrusive_ptr_release [1/2]

void intrusive_ptr_release ( Actor actor)
friend

◆ intrusive_ptr_add_ref [2/2]

void intrusive_ptr_add_ref ( Actor actor)
friend

◆ intrusive_ptr_release [2/2]

void intrusive_ptr_release ( Actor actor)
friend

The documentation for this class was generated from the following files: