The S4U Interface
The S4U interface (SimGrid for you) mixes the full power of SimGrid with the full power of C++. This is the preferred interface to describe abstract algorithms in the domains of Cloud, P2P, HPC, IoT, and similar settings.
Since v3.33 (Spring 2023), S4U is the main interface of SimGrid for algorithms. It is feature complete, but may still evolve slightly in future releases. When this happens, compiling your code will produce deprecation warnings for 4 releases (one year) before the removal of the old symbols.
Main Concepts
A typical SimGrid simulation is composed of several Actors, that execute user-provided functions. The actors have to explicitly use the S4U interface to express their computation, communication, disk usage, and other Activities, so that they get reflected within the simulator. These activities take place on resources such as Hosts, Links, and Disks. SimGrid predicts the time taken by each activity and orchestrates the actors accordingly, waiting for the completion of these activities.
When communicating, data is not directly sent to other actors but posted onto a Mailbox that serves as a rendezvous point between communicating actors. This means that you don’t need to know who you are talking to, you just put your communication Put request in a mailbox, and it will be matched with a complementary Get request. Alternatively, actors can interact through classical synchronization mechanisms such as Barrier, Semaphore, Mutex, and ConditionVariable.
Each actor is located on a simulated Host. Each host is located in a NetZone, that knows the networking path between one resource to another. Each NetZone is included in another one, forming a tree of NetZones which root zone contains the whole platform. The actors can also be located on a VirtualMachines that may restrict the activities it contains to a limited amount of cores. Virtual machines can also be migrated between hosts.
The simgrid::s4u::this_actor namespace provides many helper functions to simplify the code of actors.
Simulation Elements
class Actor: Active entities executing your application.
class Engine: Simulation engine (singleton).
class Mailbox: Communication rendezvous, with which actors meet each other.
Resources
class Disk: Resource on which actors can write and read data.
class Host: Actor location, providing computational power.
class Link: Interconnecting hosts.
class NetZone: Sub-region of the platform, containing resources (Hosts, Links, etc).
class VirtualMachine: Execution containers that can be moved between Hosts.
Activities (class Activity): The things that actors can do on resources.
class Comm: Communication activity, started on Mailboxes and consuming links.
class Exec: Computation activity, started on Host and consuming CPU resources.
class Io: I/O activity, started on and consuming disks.
class ActivtySet: Bag of activities, to wait for any of the set, or all of them.
Synchronization Objects: Classical IPC that actors can use
Activities
Activities represent the actions that consume a resource, such as a Comm that consumes the transmitting power of Link resources, or an Exec that consumes the computing power of Host resources. See also the full API below.
Asynchronous Activities
Every activity can be either blocking or asynchronous. For
example, s4u::Mailbox::put()
and s4u::Mailbox::get()
create blocking communications: the actor is blocked until the
completion of that communication. Asynchronous communications do not
block the actor during their execution but progress on their own.
Once your asynchronous activity is started, you can test for its
completion using s4u::Activity::test().
This function returns true if the activity is completed already.
You can also use s4u::Activity::wait()
to block until the completion of the activity. To wait for at most a given amount of time,
use s4u::Activity::wait_for().
Finally, to wait at most until a specified time limit, use
s4u::Activity::wait_until().
Every kind of activity can be asynchronous.
s4u::CommPtr are created with s4u::Mailbox::put_async() and
s4u::Mailbox::get_async();
s4u::IoPtr are created with s4u::Disk::read_async() and
s4u::Disk::write_async(); and
s4u::ExecPtr are created with
s4u::Host::exec_async().
In the future, it will become possible to have asynchronous IPC such as asynchronous mutex lock requests (it is already possible
internally, but the interface is not exposed in S4U yet).
If you want for the completion of any activity in a given set, to react to the earlier occuring completion, then you need an activity set. Please refer to the relevant examples for more information.
Activities Life Cycle
Sometimes, you want to change the setting of an activity before it even starts.
Todo
write this section
Repeatable Activities
In order to simulate the execution of Dataflow applications, we introduced the concept of Tasks, that can be seen as repeatable activities. A Dataflow is defined as a graph of Tasks, where each Tasks has a set of successors and predecessors. When a Tasks ends it sends a token to each of its successors. Each Tasks has to receive a token from each of its predecessor to start. Tokens can carry any user-defined data.
Tasks are composed of several instances: a dispatcher, a collector, and instance_0 to instance_n. The dispatcher rely on a load balancing function to select the next instance to fire. Once this instance finishes it fires the collector.
Each instance of an |API_s4u_ExecTask| can be placed on a different host. |API_s4u_Comm| activities are automatically created when an instance triggers another instance on a different host. Each instance has its own parallelism degree to scale horizontally on several cores.
To initiate the execution of a Dataflow, it is possible to some make
Tasks fire one or more activities without waiting for any token with the
s4u::Task::enqueue_firings()
function.
The parameters of Tasks can be redefined at runtime by attaching
callbacks to the
s4u::Task::on_this_start
and
s4u::Task::on_this_completion
signals. The former is triggered by instances others than the dispatcher and the collector,
and the latter is triggered by the collector.
Mailboxes
Please also refer to the API reference for s4u::Mailbox.
What are Mailboxes?
Mailboxes are rendezvous points for network communications, similar to URLs on which you could post and retrieve data. Actually, the mailboxes are not involved in the communication once it starts, but only to find the contact with which you want to communicate.
They are similar to many common things: The phone number, which allows
the caller to find the receiver. The Twitter hashtag, which helps
senders and receivers to find each other. In TCP, the pair
{host name, host port} to which you can connect to find your peer.
In HTTP, URLs through which the clients can connect to the servers.
In ZeroMQ, the queues are used to match senders and receivers.
One big difference with most of these systems is that no actor is the exclusive owner of a mailbox, neither in sending nor in receiving. Many actors can send into and/or receive from the same mailbox. TCP socket ports for example are shared on the sender side but exclusive on the receiver side (only one process can receive from a given socket at a given point of time).
A big difference with TCP sockets or MPI communications is that
communications do not start right away after a
Mailbox::put(), but wait
for the corresponding Mailbox::get().
You can change this by declaring a receiving actor.
A big difference with Twitter hashtags is that SimGrid does not offer easy support to broadcast a given message to many receivers. So that would be like a Twitter tag where each message is consumed by the first receiver.
A big difference with the ZeroMQ queues is that you cannot filter
on the data you want to get from the mailbox. To model such settings
in SimGrid, you’d have one mailbox per potential topic, and subscribe
to each topic individually with a
get_async() on each mailbox.
Then, use an class ActivtySet to get the first
message on any of the mailboxes you are subscribed to.
The mailboxes are not located on the network, and you can access them without any latency. The network delays are only related to the location of the sender and receiver once the match between them is done on the mailbox. This is just like the phone number that you can use locally, and the geographical distance only comes into play once you start the communication by dialing this number.
How to use Mailboxes?
You can retrieve any existing mailbox from its name (which is a unique string, just like a Twitter tag). This results in a versatile tool that can be used to build many different situations.
To model classical socket communications, use “hostname:port” as mailbox names, and make sure that only one actor reads into a given mailbox. This does not make it easy to build a perfectly realistic model of the TCP sockets, but in most cases, this system is too cumbersome for your simulations anyway. You probably want something simpler, that turns out to be easy to build with the mailboxes.
Many SimGrid examples use a sort of yellow page system where the mailbox names are the name of the service (such as “worker”, “master”, or “reducer”). That way, you don’t have to know where your peer is located to contact it. You don’t even need its name. Its function is enough for that. This also gives you some sort of load balancing for free if more than one actor pulls from the mailbox: the first actor that can deal with the request will handle it.
How are put() and get() requests matched?
The matching algorithm simple: first come, first serve. When a new send arrives, it matches the oldest enqueued receive. If no receive is currently enqueued, then the incoming send is enqueued. As you can see, the mailbox cannot contain both send and receive requests: all enqueued requests must be of the same sort.
Declaring a Receiving Actor
The last twist is that by default in the simulator, the data starts
to be exchanged only when both the sender and the receiver are
announced (it waits until both put()
and get() are posted).
In TCP, since you establish connections beforehand, the data starts to
flow as soon as the sender posts it, even if the receiver did not post
its put() yet.
To model this in SimGrid, you can declare a specific receiver to a
given mailbox (with the function
set_receiver()).
That way, any put()
posted to that mailbox will start as soon as possible, and the data
will already be there on the receiver host when the receiver actor
posts its get()
Note that being permanent receivers of a mailbox prevents actors to be
garbage-collected. If your simulation creates many short-lived actors
that are marked as permanent receiver, you should call
mailbox->set_receiver(nullptr) by the end of the actors so that their
memory gets properly reclaimed. This call should be at the end of the
actor’s function, not in an on_exit callback.
Communicating without Mailboxes
Sometimes you don’t want to simulate communications between actors as allowed by mailboxes, but you want to create a direct communication between two arbitrary hosts. This can arise when you write a high-level model of a centralized scheduler, or when you model direct communications such as one-sided communications in MPI or remote memory direct access in PGAS.
For that, Comm::sendto()
simulates a direct communication between the two specified hosts. No
mailbox is used, and there is no rendezvous between actors. You can
freely mix such direct communications and rendezvous-based
communications. Alternatively, Comm::sendto_init() and
Comm::sendto_async()
create asynchronous direct communications.
Memory Management
For sake of simplicity, we use RAII for many classes in S4U. This is an idiom where resources are automatically managed through the context. Provided that you never manipulate objects of type Foo directly but always FooPtr references (which are defined as boost::intrusive_ptr <Foo>), you will never have to explicitly release the resource that you use nor to free the memory of unused objects. Here is a little example:
void myFunc()
{
simgrid::s4u::MutexPtr mutex = simgrid::s4u::Mutex::create(); // Too bad we cannot use `new`
mutex->lock(); // use the mutex as a simple reference
// bla bla
mutex->unlock();
} // The mutex gets automatically freed because the only existing reference gets out of scope
Note that Mailboxes, Hosts, and Links are not handled through smart
pointers (yet?). This means that it is currently impossible to destroy a
mailbox or a link. You can still destroy a host (but probably
shouldn’t), using simgrid::s4u::Host::destroy().
API Reference
Simulation objects
class Actor
-
class Actor : public xbt::Extendable<Actor>
An actor is an independent stream of execution in your distributed application.
It is located on a (simulated)
host, but can interact with the whole simulated platform.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. Please refer to the examples for more information.
This API is strongly inspired from the C++11 threads. The documentation of this standard may help to understand the philosophy of the SimGrid actors.
-
typedef long aid_t
Actor’s ID, just like the classical processes’ have PID in UNIX
- class simgrid.Actor
An actor is an independent stream of execution in your distributed application. See the C++ documentation for details.
Basic management
#include <simgrid/s4u/Actor.hpp>
from simgrid import Actor
#include <simgrid/actor.h>
-
typedef s4u_Actor *sg_actor_t
Pointer to an actor object
-
typedef const s4u_Actor *const_sg_actor_t
Pointer to a constant actor object
-
void sg_actor_ref(const_sg_actor_t actor)
Take an extra reference on that actor to prevent it to be garbage-collected.
-
void sg_actor_unref(const_sg_actor_t actor)
Release a reference on that actor so that it can get be garbage-collected.
Creating actors
See also the relevant example.
-
static ActorPtr simgrid::s4u::Actor::create(const std::string &name, s4u::Host *host, const std::function<void()> &code)
Create an actor from a
std::function<void()>. If the actor is restarted, it gets a fresh copy of the function. See the example.
-
template<class F>
static inline ActorPtr simgrid::s4u::Actor::create(const std::string &name, s4u::Host *host, F code) Create an actor from a callable thing. See the example.
-
template<class F, class ...Args>
static inline ActorPtr simgrid::s4u::Actor::create(const std::string &name, s4u::Host *host, F code, Args... args) Create an actor using a callable thing and its arguments.
Note that the arguments will be copied, so move-only parameters are forbidden. See the example.
-
static ActorPtr simgrid::s4u::Actor::create(const std::string &name, s4u::Host *host, const std::string &function, std::vector<std::string> args)
Create actor from function name and a vector of strings as arguments. See the example.
-
static ActorPtr simgrid::s4u::Actor::init(const std::string &name, s4u::Host *host)
Create an actor, but don’t start it yet.
This is useful to set some properties or extension before actually starting it
- Actor.create(self: str, arg0: simgrid.Host, arg1: object, *args) simgrid.Actor
Create an actor from a function or an object. See the example.
-
typedef void (*xbt_main_func_t)(int argc, char *argv[])
Prototype of an actor’s main function
The only difference with a classical main() in C is that the return type is void
-
static inline sg_actor_t sg_actor_create(const char *name, sg_host_t host, xbt_main_func_t code, int argc, char *const *argv)
-
sg_actor_t sg_actor_init(const char *name, sg_host_t host)
-
static inline void sg_actor_start(sg_actor_t actor, xbt_main_func_t code, int argc, char *const *argv)
Start the previously initialized actor.
Note that argv is copied over, so you should free your own copy once the actor is started.
-
void sg_actor_start_voidp(sg_actor_t actor, void_f_pvoid_t code, void *param)
Start the previously initialized actor using a pthread-like API.
-
void sg_actor_set_stacksize(sg_actor_t actor, unsigned size)
-
sg_actor_t sg_actor_attach(const char *name, void *data, sg_host_t host, xbt_dict_t properties)
-
void sg_actor_detach()
See also Changing maestro’s thread for an example of use of sg_actor_attach() and sg_actor_detach().
Retrieving actors
- static Actor.by_pid(pid: int) simgrid.Actor
Retrieve an actor by its PID
- Actor.self() simgrid.Actor
Retrieves the current actor.
-
sg_actor_t sg_actor_by_pid(aid_t pid)
Return a sg_actor_t given its PID.
This function search in the list of all the created sg_actor_t for a sg_actor_t whose PID is equal to PID. If none is found,
nullptris returned. Note that the PID are unique in the whole simulation, not only on a given host.
-
sg_actor_t sg_actor_self()
-
sg_actor_t *sg_actor_list()
Querying info
-
const std::string &simgrid::s4u::Actor::get_name() const
Retrieves the name of that actor as a C++ string
-
const std::unordered_map<std::string, std::string> *simgrid::s4u::Actor::get_properties() const
Retrieve the list of properties for that actor
-
const char *simgrid::s4u::Actor::get_property(const std::string &key) const
Retrieve the property value (or nullptr if not set)
-
void simgrid::s4u::Actor::set_property(const std::string &key, const std::string &value)
Set a property (old values will be overwritten)
-
void simgrid::s4u::Actor::set_host(Host *new_host)
Moves the actor to another host.
If the actor is currently blocked on an execution activity, the activity is also migrated to the new host. If it’s blocked on another kind of activity, an error is raised as the mandated code is not written yet. Please report that bug if you need it.
Asynchronous activities started by the actor are not migrated automatically, so you have to take care of this yourself (only you knows which ones should be migrated).
- Actor.name
The name of this actor (read-only property).
- Actor.host
The host on which this actor is located. Changing this value migrates the actor.
If the actor is currently blocked on an execution activity, the activity is also migrated to the new host. If it’s blocked on another kind of activity, an error is raised as the mandated code is not written yet. Please report that bug if you need it.
Asynchronous activities started by the actor are not migrated automatically, so you have to take care of this yourself (only you knows which ones should be migrated).
- Actor.pid
The PID (unique identifier) of this actor (read-only property).
- Actor.ppid
The PID (unique identifier) of the actor that created this one (read-only property).
-
const char *sg_actor_get_name(const_sg_actor_t actor)
Return the name of an actor.
-
aid_t sg_actor_get_pid(const_sg_actor_t actor)
Returns the process ID of actor.
This function checks whether actor is a valid pointer and return its PID (or 0 in case of problem).
-
aid_t sg_actor_get_ppid(const_sg_actor_t actor)
Returns the process ID of the parent of actor.
This function checks whether actor is a valid pointer and return its parent’s PID. Returns -1 if the actor has not been created by any other actor.
-
xbt_dict_t sg_actor_get_properties(const_sg_actor_t actor)
Return the list of properties.
This function returns all the parameters associated with an actor
-
const char *sg_actor_get_property_value(const_sg_actor_t actor, const char *name)
Returns the value of a given actor property.
- Parameters:
actor – an actor
name – a property name
- Returns:
value of a property (or nullptr if the property is not set)
-
sg_host_t sg_actor_get_host(const_sg_actor_t actor)
-
void sg_actor_set_host(sg_actor_t actor, sg_host_t host)
Migrates an actor to another location.
This function changes the value of the sg_host_t on which actor is running.
-
void *sg_actor_get_data(const_sg_actor_t actor)
Return the user data of a sg_actor_t.
-
void sg_actor_set_data(sg_actor_t actor, void *userdata)
Set the user data of a sg_actor_t.
Suspending and resuming actors
- Actor.resume(self: simgrid.Actor) None
Resume that actor, that was previously suspend()ed.
- Actor.suspend(self: simgrid.Actor) None
Suspend that actor, that is blocked until resume()ed by another actor.
- Actor.is_suspended(self: simgrid.Actor) bool
Returns True if that actor is currently suspended.
-
void sg_actor_suspend(sg_actor_t actor)
Suspend the actor.
This function suspends the actor by suspending the task on which it was waiting for the completion.
-
void sg_actor_resume(sg_actor_t actor)
Resume a suspended actor.
This function resumes a suspended actor by resuming the task on which it was waiting for the completion.
-
int sg_actor_is_suspended(const_sg_actor_t actor)
Returns true if the actor is suspended .
This checks whether an actor is suspended or not by inspecting the task on which it was waiting for the completion.
Specifying when actors should terminate
-
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.
-
static void simgrid::s4u::Actor::kill_all()
Kill all actors (but the issuer). Being killed is not something that actors can delay or avoid.
-
void simgrid::s4u::Actor::set_kill_time(double time)
Sets the time at which that actor should be killed
-
double simgrid::s4u::Actor::get_kill_time() const
Get the kill time of an actor(or 0 if unset).
Retrieves the time at which that actor will be killed (or -1 if not set)
-
Actor *simgrid::s4u::Actor::daemonize()
This actor will be automatically terminated when the last non-daemon actor finishes.
Daemons are killed as soon as the last regular actor disappears. If another regular actor gets restarted later on by a timer or when its host reboots, the daemons do not get restarted.
- Actor.kill(self: simgrid.Actor) None
Kill that actor
- static Actor.kill_all() None
Kill all actors but the caller.
- Actor.daemonize(self: simgrid.Actor) simgrid.Actor
This actor will be automatically terminated when the last non-daemon actor finishes (more info in the C++ documentation).
- Actor.is_daemon(self: simgrid.Actor) bool
Returns True if that actor is a daemon and will be terminated automatically when the last non-daemon actor terminates.
-
void sg_actor_kill(sg_actor_t actor)
-
void sg_actor_kill_all()
-
void sg_actor_set_kill_time(sg_actor_t actor, double kill_time)
Set the kill time of an actor.
- Parameters:
actor – an actor
kill_time – the time when the actor is killed.
-
sg_actor_t sg_actor_restart(sg_actor_t actor)
Restarts an actor from the beginning.
-
void sg_actor_daemonize(sg_actor_t actor)
This actor will be terminated automatically when the last non-daemon actor finishes.
-
int sg_actor_is_daemon(const_sg_actor_t actor)
Returns whether or not this actor has been daemonized or not
Reacting to the end of actors
-
void simgrid::s4u::Actor::on_exit(const std::function<void(bool)> &fun) const
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 actor.
Please note that functions registered in this signal cannot do any simcall themselves. It means that they cannot send or receive messages, acquire or release mutexes, nor even modify a host property or something. Not only are blocking functions forbidden in this setting, but also modifications to the global state.
The parameter of on_exit’s callbacks denotes whether or not the actor’s execution failed. It will be set to true if the actor was killed or failed because of an exception, while it will remain to false if the actor terminated gracefully.
-
void simgrid::s4u::Actor::join() const
Wait for the actor to finish.
Blocks the calling actor until the joined actor is terminated. If actor alice executes bob.join(), then alice is blocked until bob terminates.
-
void simgrid::s4u::Actor::join(double timeout) const
Wait for the actor to finish, or for the timeout to elapse.
Blocks the calling actor until the joined actor is terminated. If actor alice executes bob.join(), then alice is blocked until bob terminates.
-
Actor *simgrid::s4u::Actor::set_auto_restart(bool autorestart = true)
If set to true, the actor will automatically restart when its host reboots.
Some elements of the actor are remembered over reboots: name, host, properties, the on_exit functions, whether it is daemonized and whether it should automatically restart when its host reboots. Note that the state after reboot is the one when set_auto_restart() is called.
If you daemonize your actor after marking it auto_restart, then the new actor after rebooot will not be a daemon.
The on_exit functions are the one defined when the actor dies, not the ones given when it was marked auto_restart (sorry for the inconsistency — speak to us if it’s too hard to bear).
- Actor.join(self: simgrid.Actor, timeout: float = -1) None
Wait for the actor to finish (more info in the C++ documentation).
-
void sg_actor_on_exit(void_f_int_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 actor.
-
void sg_actor_join(const_sg_actor_t actor, double timeout)
Wait for the completion of a sg_actor_t.
- Parameters:
actor – the actor to wait for
timeout – wait until the actor is over, or the timeout expires
-
void sg_actor_set_auto_restart(sg_actor_t actor, int auto_restart)
Sets the “auto-restart” flag of the actor. If the flag is set to 1, the actor will be automatically restarted when its host comes back up.
Signals
-
static inline void simgrid::s4u::Actor::on_creation_cb(const std::function<void(Actor&)> &cb)
Add a callback fired when a new actor has been created
-
static inline void simgrid::s4u::Actor::on_suspend_cb(const std::function<void(Actor const&)> &cb)
Add a callback fired when any actor is suspended (right before the suspend)
-
inline void simgrid::s4u::Actor::on_this_suspend_cb(const std::function<void(Actor const&)> &cb)
Add a callback fired when this specific actor is suspended (right before the suspend)
-
static inline void simgrid::s4u::Actor::on_host_change_cb(const std::function<void(const Actor&, const Host &previous_location)> &cb)
Add a callback fired when any actor is has been migrated to another host
-
inline void simgrid::s4u::Actor::on_this_host_change_cb(const std::function<void(const Actor&, const Host &previous_location)> &cb)
Add a callback fired when this specific actor is has been migrated to another host
-
static inline void simgrid::s4u::Actor::on_resume_cb(const std::function<void(Actor const&)> &cb)
Add a callback fired when any actor is resumed (right before the resume)
-
inline void simgrid::s4u::Actor::on_this_resume_cb(const std::function<void(Actor const&)> &cb)
Add a callback fired when this specific actor is resumed (right before the resume)
-
static inline void simgrid::s4u::Actor::on_sleep_cb(const std::function<void(Actor const&)> &cb)
Add a callback fired when any actor starts sleeping
-
inline void simgrid::s4u::Actor::on_this_sleep_cb(const std::function<void(Actor const&)> &cb)
Add a callback fired when this specific actor starts sleeping
-
static inline void simgrid::s4u::Actor::on_wake_up_cb(const std::function<void(Actor const&)> &cb)
Add a callback fired when any actor wakes up from a sleep
-
inline void simgrid::s4u::Actor::on_this_wake_up_cb(const std::function<void(Actor const&)> &cb)
Add a callback fired when this specific actor wakes up from a sleep
-
static inline void simgrid::s4u::Actor::on_termination_cb(const std::function<void(Actor const&)> &cb)
Add a callback fired when any actor terminates its code.
The actor may continue to exist if it is still referenced in the simulation, but it’s not active anymore. If you want to free extra data when the actor’s destructor is called, use
Actor::on_destruction_cb(). If you want to register to the termination of a given actor, usethis_actor::on_exit()instead.
-
inline void simgrid::s4u::Actor::on_this_termination_cb(const std::function<void(Actor const&)> &cb)
Add a callback fired when this specific actor terminates its code.
The actor may continue to exist if it is still referenced in the simulation, but it’s not active anymore. If you want to free extra data when the actor’s destructor is called, use
Actor::on_this_destruction_cb().
The current actor
These functions can be used in your user code to interact with the actor
currently running (the one retrieved with simgrid::s4u::Actor::self()).
Using these functions can greatly improve the code readability.
Querying info
-
const char *simgrid::s4u::this_actor::get_cname()
Returns the name of the current actor as a C string.
-
std::string simgrid::s4u::this_actor::get_name()
Returns the name of the current actor.
-
bool simgrid::s4u::this_actor::is_maestro()
Returns true if run from the kernel mode, and false if run from a real actor
Everything that is run out of any actor (simulation setup before the engine is run, computing the model evolutions as a result to the actors’ action, etc) is run in kernel mode, just as in any operating systems.
In SimGrid, the actor in charge of doing the stuff in kernel mode is called Maestro, because it is the one scheduling when the others should move or wait.
- simgrid.this_actor.get_host() simgrid::s4u::Host
Retrieves host on which the current actor is located
- simgrid.this_actor.set_host(dest: simgrid::s4u::Host) None
Moves the current actor to another host.
- simgrid.this_actor.get_pid() int
Retrieves PID of the current actor
- simgrid.this_actor.get_ppid() int
Retrieves PPID of the current actor (i.e., the PID of its parent).
Suspending and resuming
-
void simgrid::s4u::this_actor::suspend()
Suspend the current actor, that is blocked until resume()ed by another actor.
-
void simgrid::s4u::this_actor::yield()
Yield the current actor.
- simgrid.this_actor.suspend() None
Suspend the current actor, that is blocked until resume()ed by another actor.
- simgrid.this_actor.yield_() None
Yield the actor
-
void sg_actor_yield()
Yield the current actor; let the other actors execute first
Logging messages
Please refer to the relevant documentation.
- simgrid.this_actor.debug(arg0: str) None
Display a logging message of ‘debug’ priority.
- simgrid.this_actor.info(arg0: str) None
Display a logging message of ‘info’ priority.
- simgrid.this_actor.warning(arg0: str) None
Display a logging message of ‘warning’ priority.
- simgrid.this_actor.error(arg0: str) None
Display a logging message of ‘error’ priority.
Sleeping
-
void simgrid::s4u::this_actor::sleep_for(double duration)
Block the current actor sleeping for that amount of seconds
-
template<class Rep, class Period>
inline void simgrid::s4u::this_actor::sleep_for(std::chrono::duration<Rep, Period> duration)
-
template<class Duration>
inline void simgrid::s4u::this_actor::sleep_until(const SimulationTimePoint<Duration> &wakeup_time)
-
void simgrid::s4u::this_actor::sleep_until(double wakeup_time)
Block the current actor sleeping until the specified timestamp
- simgrid.this_actor.sleep_for(duration: float) None
Block the actor sleeping for that amount of seconds.
- simgrid.this_actor.sleep_until(duration: float) None
Block the actor sleeping until the specified timestamp.
-
void sg_actor_sleep_for(double duration)
Simulating executions
Simulate the execution of some code on this actor. You can either simulate parallel or sequential code and you can either block upon the termination of the execution, or start an asynchronous activity.
-
ExecPtr simgrid::s4u::this_actor::exec_init(const std::vector<s4u::Host*> &hosts, const std::vector<double> &flops_amounts, const std::vector<double> &bytes_amounts)
Initialize a parallel execution that must then be started manually
-
ExecPtr simgrid::s4u::this_actor::exec_init(double flops_amounts)
Initialize a sequential execution that must then be started manually
-
void simgrid::s4u::this_actor::execute(double flop)
Block the current actor, computing the given amount of flops
-
void simgrid::s4u::this_actor::execute(double flop, double priority)
Block the current actor, computing the given amount of flops at the given priority. An execution of priority 2 computes twice as fast as an execution at priority 1.
-
void simgrid::s4u::this_actor::parallel_execute(const std::vector<s4u::Host*> &hosts, const std::vector<double> &flops_amounts, const std::vector<double> &bytes_amounts)
Block the current actor until the built parallel execution terminates
Example of use: examples/cpp/exec-ptask/s4u-exec-ptask.cpp
Parallel executions convenient abstractions of parallel computational kernels that span over several machines, such as a PDGEM and the other ScaLAPACK routines. If you are interested in the effects of such parallel kernel on the platform (e.g. to schedule them wisely), there is no need to model them in all details of their internal execution and communications. It is much more convenient to model them as a single execution activity that spans over several hosts. This is exactly what s4u’s Parallel Executions are.
To build such an object, you need to provide a list of hosts that are involved in the parallel kernel (the actor’s own host may or may not be in this list) and specify the amount of computations that should be done by each host, using a vector of flops amount. Then, you should specify the amount of data exchanged between each hosts during the parallel kernel. For that, a matrix of values is expected.
It is OK to build a parallel execution without any computation and/or without any communication. Just pass an empty vector to the corresponding parameter.
For example, if your list of hosts is
[host0, host1], passing a vector[1000, 2000]as a flops_amount vector means that host0 should compute 1000 flops while host1 will compute 2000 flops. A matrix of communications’ sizes of[0, 1, 2, 3]specifies the following data exchanges:from host0: [ to host0: 0 bytes; to host1: 1 byte ]
from host1: [ to host0: 2 bytes; to host1: 3 bytes ]
Or, in other words:
From host0 to host0: 0 bytes are exchanged
From host0 to host1: 1 byte is exchanged
From host1 to host0: 2 bytes are exchanged
From host1 to host1: 3 bytes are exchanged
In a parallel execution, all parts (all executions on each hosts, all communications) progress exactly at the same pace, so they all terminate at the exact same pace. If one part is slow because of a slow resource or because of contention, this slows down the parallel execution as a whole.
These objects are somewhat surprising from a modeling point of view. For example, the unit of their speed is somewhere between flop/sec and byte/sec. Arbitrary parallel executions will simply not work with the usual platform models, and you must use the ptask_L07 host model for that. Note that you can mix regular executions and communications with parallel executions, provided that the host model is ptask_L07.
Block the current actor until the built parallel execution completes.
- simgrid.this_actor.exec_async(arg0: float) simgrid::s4u::Exec
- simgrid.this_actor.exec_init(*args, **kwargs)
Overloaded function.
exec_init(arg0: float) -> simgrid::s4u::Exec
exec_init(arg0: List[simgrid::s4u::Host], arg1: List[float], arg2: List[float]) -> simgrid::s4u::Exec
Initiate a parallel task (requires the ‘ptask_L07’ model)
- simgrid.this_actor.execute(flops: float, priority: float = 1) None
Block the current actor, computing the given amount of flops at the given priority.
Exiting
-
void simgrid::s4u::this_actor::exit()
kill the current actor.
-
void simgrid::s4u::this_actor::on_exit(const std::function<void(bool)> &fun)
Add a function to the list of “on_exit” functions of 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 actor.
Please note that functions registered in this signal cannot do any simcall themselves. It means that they cannot send or receive messages, acquire or release mutexes, nor even modify a host property or something. Not only are blocking functions forbidden in this setting, but also modifications to the global state.
The parameter of on_exit’s callbacks denotes whether or not the actor’s execution failed. It will be set to true if the actor was killed or failed because of an exception or if the simulation deadlocked, while it will remain to false if the actor terminated gracefully.
- simgrid.this_actor.exit() None
kill the current actor
- simgrid.this_actor.on_exit(arg0: object) None
Define a lambda to be called when the actor ends. It takes a bool parameter indicating whether the actor was killed. If False, the actor finished peacefully.
See also sg_actor_on_exit().
-
void sg_actor_exit()
Simulation Engine
-
class Engine
Simulation engine.
This is a singleton containing all the main functions of the simulation.
- class simgrid.Engine
Simulation Engine
Engin initialization
-
explicit simgrid::s4u::Engine::Engine(int *argc, char **argv)
Constructor, taking the command line parameters of your main function
- Engine.__init__(self: simgrid.Engine, arg0: List[str]) None
The constructor should take the parameters from the command line, as is
- Engine.instance = <simgrid.Engine object>
-
void simgrid_init(int *argc, char **argv)
Initialize the SimGrid engine, taking the command line parameters of your main function.
Simulation setup
-
static void simgrid::s4u::Engine::set_config(const std::string &str)
set a configuration variable
Do –help on any SimGrid binary to see the list of currently existing configuration variables (see also Configuring SimGrid).
Example: simgrid::s4u::Engine::set_config(“host/model:ptask_L07”);
-
void simgrid::s4u::Engine::load_deployment(const std::string &deploy) const
Load a deployment file. See:ref:deploy and the example.
-
void simgrid::s4u::Engine::load_platform(const std::string &platf) const
Creates a new platform, including hosts, links, and the routing table.
See also: Describing your Simulated Platform.
-
std::string simgrid::s4u::Engine::flatify_platform() const
Get a debug output of the platform.
It looks like a XML platform file, but it may be very different from the input platform file: All netzones are flatified into a unique zone. This representation is mostly useful to debug your platform configuration and ensure that your assumptions over your configuration hold. This enables you to verify the exact list of links traversed between any two hosts, and the characteristics of every host and link. But you should not use the resulting file as an input platform file: it is very verbose, and thus much less efficient (in parsing time and runtime performance) than a regular platform file with the sufficient amount of intermediary netzones. Even if you use one zone only, specialized zones (such as clusters) are more efficient than the one with fully explicit routing used here.
-
template<class F>
inline void simgrid::s4u::Engine::register_actor(const std::string &name) Bind an actor name that could be found in <actor> tag to a class name passed as a template parameter. See the example.
-
template<class F>
inline void simgrid::s4u::Engine::register_actor(const std::string &name, F code) Bind an actor name that could be found in <actor> tag to a function name passed as a parameter. See the example.
-
void simgrid::s4u::Engine::register_default(const std::function<void(int, char**)> &code)
Provide a default function to be used when the name used in a <actor> tag was not binded with
register_functionnorregister_actor.
-
void simgrid::s4u::Engine::register_function(const std::string &name, const std::function<void(int, char**)> &code)
Bind an actor name that could be found in <actor> tag to a function taking classical argc/argv parameters. See the example.
- Engine.load_deployment(self: simgrid.Engine, arg0: str) None
Load a deployment file and launch the actors that it contains
- Engine.load_platform(self: simgrid.Engine, arg0: str) None
Load a platform file describing the environment
- Engine.register_actor(self: simgrid.Engine, arg0: str, arg1: object) None
Registers the main function of an actor
-
void simgrid_load_deployment(const char *filename)
Load a deployment file and launch the actors that it contains
See also: Deploying your Application.
-
void simgrid_load_platform(const char *filename)
Creates a new platform, including hosts, links, and the routing table.
See also: Describing your Simulated Platform.
-
void simgrid_register_default(void (*code)(int, char**))
Registers a function as the default main function of actors
It will be used as fallback when the function requested from the deployment file was not registered. It is used for trace-based simulations (see examples/cpp/replay-comms and similar).
-
void simgrid_register_function(const char *name, void (*code)(int, char**))
Registers the main function of an actor that will be launched from the deployment file
Run the simulation
- Engine.clock = 0.0
- Engine.run(self: simgrid.Engine) None
Run the simulation until its end
- Engine.run_until(self: simgrid.Engine, max_date: float = -1) None
Run the simulation until the given date
Retrieving actors
-
size_t sg_actor_count()
Actor datatype.
An actor may be defined as a code, with some private data, executing in a location.
You should not access directly to the fields of the pointed structure, but always use the provided API to interact with actors.
Retrieving hosts
-
std::vector<Host*> simgrid::s4u::Engine::get_all_hosts() const
Returns a vector of all hosts found in the platform.
The order is generally different from the creation/declaration order in the XML platform because we use a hash table internally.
-
size_t simgrid::s4u::Engine::get_host_count() const
Returns the amount of hosts existing in the platform.
- Engine.all_hosts
Returns the list of all hosts found in the platform
- Engine.host_by_name(self: simgrid.Engine, arg0: str) simgrid::s4u::Host
Retrieve a host by its name, or None if it does not exist in the platform.
See also sg_host_list() and sg_host_count().
Retrieving links
Interacting with the routing
-
template<class T>
inline std::vector<T*> simgrid::s4u::Engine::get_filtered_netzones() const Retrieves all netzones of the type indicated by the template argument.
- Engine.all_netpoints
- Engine.netzone_root
Retrieve the root netzone, containing all others.
- Engine.netpoint_by_name(self: simgrid.Engine, arg0: str) simgrid::kernel::routing::NetPoint
- Engine.netzone_by_name(self: simgrid.Engine, arg0: str) simgrid::s4u::NetZone
Signals
-
static inline void simgrid::s4u::Engine::on_deadlock_cb(const std::function<void(void)> &cb)
Add a callback fired when the time cannot advance because of inter-actors deadlock. Note that the on_exit of each actor is also executed on deadlock.
-
static inline void simgrid::s4u::Engine::on_platform_created_cb(const std::function<void()> &cb)
Add a callback fired when the platform is created (ie, the xml file parsed), right before the actual simulation starts.
-
static inline void simgrid::s4u::Engine::on_platform_creation_cb(const std::function<void()> &cb)
Add a callback fired when the platform is about to be created (ie, after any configuration change and just before the resource creation)
-
static inline void simgrid::s4u::Engine::on_simulation_start_cb(const std::function<void()> &cb)
Add a callback fired when the main simulation loop starts, at the beginning of the first call to Engine::run()
-
static inline void simgrid::s4u::Engine::on_simulation_end_cb(const std::function<void()> &cb)
Add a callback fired when the main simulation loop ends, just before the end of Engine::run()
-
static inline void simgrid::s4u::Engine::on_time_advance_cb(const std::function<void(double)> &cb)
Add a callback fired when the time jumps into the future.
It is fired right after the time change (use get_clock() to get the new timestamp). The callback parameter is the time delta since previous timestamp.
class Mailbox
-
class Mailbox
Mailboxes: Network rendez-vous points.
- class simgrid.Mailbox
Mailbox. See the C++ documentation for details.
Please also refer to the full doc on s4u::Mailbox.
Basic management
#include <simgrid/s4u/Mailbox.hpp>
Note that there is no MailboxPtr type and that you cannot use the RAII idiom on mailboxes because they are internal objects to the simulation engine. Once created, there is no way to destroy a mailbox before the end of the simulation.
#include <simgrid/mailbox.h>
- static Mailbox.by_name(name: str) simgrid.Mailbox
Retrieve a Mailbox from its name
#include <simgrid/s4u/mailbox.h>
-
typedef s4u_Mailbox *sg_mailbox_t
-
typedef const s4u_Mailbox *const_sg_mailbox_t
-
sg_mailbox_t sg_mailbox_by_name(const char *alias)
Querying info
- Mailbox.name
The name of that mailbox (read-only property).
-
const char *sg_mailbox_get_name(const_sg_mailbox_t mailbox)
Sending data
-
void simgrid::s4u::Mailbox::put(void *payload, uint64_t simulated_size_in_bytes)
Blocking data transmission.
Please note that if you send a pointer to some data, you must ensure that your data remains live during the communication, or the receiver will get a pointer to a garbled memory area.
-
void simgrid::s4u::Mailbox::put(void *payload, uint64_t simulated_size_in_bytes, double timeout)
Blocking data transmission with timeout
-
CommPtr simgrid::s4u::Mailbox::put_async(void *data, uint64_t simulated_size_in_bytes)
Creates and start a data transmission to that mailbox.
Please note that if you send a pointer to some data, you must ensure that your data remains live during the communication, or the receiver will get a pointer to a garbled memory area.
-
CommPtr simgrid::s4u::Mailbox::put_init()
Creates (but don’t start) a data transmission to that mailbox
-
CommPtr simgrid::s4u::Mailbox::put_init(void *data, uint64_t simulated_size_in_bytes)
Creates (but don’t start) a data transmission to that mailbox.
Please note that if you send a pointer to some data, you must ensure that your data remains live during the communication, or the receiver will get a pointer to a garbled memory area.
- Mailbox.put(*args, **kwargs)
Overloaded function.
put(self: simgrid.Mailbox, arg0: object, arg1: int, arg2: float) -> None
Blocking data transmission with a timeout
put(self: simgrid.Mailbox, arg0: object, arg1: int) -> None
Blocking data transmission
- Mailbox.put_async(self: simgrid.Mailbox, arg0: object, arg1: int) simgrid::s4u::Comm
Non-blocking data transmission
- Mailbox.put_init(self: simgrid.Mailbox, arg0: object, arg1: int) simgrid::s4u::Comm
Creates (but don’t start) a data transmission to that mailbox.
-
void sg_mailbox_put(sg_mailbox_t mailbox, void *payload, long simulated_size_in_bytes)
-
sg_comm_t sg_mailbox_put_init(sg_mailbox_t mailbox, void *payload, long simulated_size_in_bytes)
-
sg_comm_t sg_mailbox_put_async(sg_mailbox_t mailbox, void *payload, long simulated_size_in_bytes)
Receiving data
-
bool simgrid::s4u::Mailbox::empty() const
Returns whether the mailbox contains queued communications
-
kernel::activity::CommImplPtr simgrid::s4u::Mailbox::front() const
Gets the first element in the queue (without dequeuing it), or nullptr if none is there
-
template<typename T>
T *simgrid::s4u::Mailbox::get(double timeout) Blocking data reception with timeout
-
template<typename T>
CommPtr simgrid::s4u::Mailbox::get_async(T **data) Creates and start an async data reception to that mailbox
-
CommPtr simgrid::s4u::Mailbox::get_init()
Creates (but don’t start) a data reception onto that mailbox. You probably want to use
simgrid::s4u::Comm::set_dst_data()and friends before* starting that activity.
Warning
doxygenfunction: Unable to resolve function “simgrid::s4u::Mailbox::iprobe” with arguments (int, const std::function<bool(void*, void*, kernel::activity::CommImpl*)>&, void*) in doxygen xml output for project “simgrid” from directory: ../build/xml. Potential matches:
- kernel::activity::ActivityImplPtr iprobe(IprobeKind kind, const std::function<bool(void*, void*, kernel::activity::CommImpl*)> &match_fun, void *data)
-
bool simgrid::s4u::Mailbox::listen() const
Check if there is a communication going on in a mailbox.
-
bool simgrid::s4u::Mailbox::ready() const
Check if there is a communication ready to be consumed from a mailbox.
See this example.
- Mailbox.get(self: simgrid.Mailbox) object
Blocking data reception
- Mailbox.get_async(self: simgrid.Mailbox) simgrid::s4u::Comm
Non-blocking data reception. Use data.get() to get the python object after the communication has finished
- Mailbox.ready
Check if there is a communication ready to be consumed from a mailbox.
-
void *sg_mailbox_get(sg_mailbox_t mailbox)
-
sg_comm_t sg_mailbox_get_async(sg_mailbox_t mailbox, void **data)
-
int sg_mailbox_listen(const char *alias)
Receiving actor
See Declaring a Receiving Actor.
-
ActorPtr simgrid::s4u::Mailbox::get_receiver() const
Return the actor declared as permanent receiver, or nullptr if none
-
void simgrid::s4u::Mailbox::set_receiver(ActorPtr actor)
Declare that the specified actor is a permanent receiver on that mailbox
It means that the communications sent to this mailbox will start flowing to its host even before it does a get(). This models the real behavior of TCP and MPI communications, amongst other. It will improve the accuracy of predictions, in particular if your application exhibits swarms of small messages.
SimGrid does not enforces any kind of ownership over the mailbox. Even if a receiver was declared, any other actors can still get() data from the mailbox. The timings will then probably be off tracks, so you should strive on your side to not get data from someone else’s mailbox.
Note that being permanent receivers of a mailbox prevents actors to be garbage-collected. If your simulation creates many short-lived actors that marked as permanent receiver, you should call mailbox->set_receiver(nullptr) by the end of the actors so that their memory gets properly reclaimed. This call should be at the end of the actor’s function, not in an on_exit callback.
-
void sg_mailbox_set_receiver(const char *alias)
Resources
class Disk
- class simgrid.Disk
Simulated disk. See the C++ documentation for details.
Basic management
#include <simgrid/s4u/Disk.hpp>
Note that there is no DiskPtr type and that you cannot use the RAII idiom on disks because SimGrid does not allow (yet) to create nor destroy resources once the simulation is started.
from simgrid import Disk
- Disk.seal(self: simgrid.Disk) simgrid.Disk
Seal this disk
Querying info
-
Disk *simgrid::s4u::Disk::set_sharing_policy(Operation op, SharingPolicy policy, const s4u::NonLinearResourceCb &cb = {})
Describes how the disk is shared between activities for each operation.
Disks have different bandwidths for read and write operations, that can have different policies:
Read: resource sharing for read operation
Write: resource sharing for write
ReadWrite: global sharing for read and write operations
Note that the NONLINEAR callback is in the critical path of the solver, so it should be fast.
- Parameters:
op – Operation type
policy – Sharing policy
cb – Callback for NONLINEAR policies
- Disk.name
The name of this disk (read-only property).
- Disk.set_sharing_policy(self: simgrid.Disk, op: simgrid::s4u::Disk::Operation, policy: simgrid::s4u::Disk::SharingPolicy, cb: Callable[[float, int], float] = None) simgrid.Disk
Set sharing policy for this disk
- class simgrid.Disk.Operation
Members:
READ
WRITE
READWRITE
- class simgrid.Disk.SharingPolicy
Members:
NONLINEAR
LINEAR
I/O operations
- Disk.read(self: simgrid.Disk, size: int, priority: float = 1) int
Read data from disk
- Disk.read_async(self: simgrid.Disk, arg0: int) simgrid::s4u::Io
Non-blocking read data from disk
- Disk.write(self: simgrid.Disk, size: int, priority: float = 1) int
Write data in disk
- Disk.write_async(self: simgrid.Disk, arg0: int) simgrid::s4u::Io
Non-blocking write data in disk
Signals
-
static inline void simgrid::s4u::Disk::on_creation_cb(const std::function<void(Disk&)> &cb)
Add a callback fired when a new Disk is created.
-
static inline void simgrid::s4u::Disk::on_destruction_cb(const std::function<void(Disk const&)> &cb)
Add a callback fired when any Disk is destroyed.
-
inline void simgrid::s4u::Disk::on_this_destruction_cb(const std::function<void(Disk const&)> &cb)
Add a callback fired when this specific Disk is destroyed.
class Host
-
class Host : public xbt::Extendable<Host>
Some physical resource with computing and networking capabilities on which Actors execute.
All hosts are automatically created during the call of the method
simgrid::s4u::Engine::load_platform(). You cannot create a host yourself.You can retrieve a particular host using
simgrid::s4u::Host::by_name()and actors can retrieve the host on which they run usingsimgrid::s4u::Host::current()orsimgrid::s4u::this_actor::get_host()Subclassed by simgrid::s4u::VirtualMachine
- class simgrid.Host
Simulated host. See the C++ documentation for details.
Basic management
#include <simgrid/s4u/Host.hpp>
Note that there is no HostPtr type, and that you cannot use the RAII idiom on hosts because SimGrid does not allow (yet) to create nor destroy resources once the simulation is started.
-
virtual void simgrid::s4u::Host::destroy()
Fire the required callbacks and destroy the object.
Don’t delete directly a host, call h->destroy() instead.
This is cumbersome but this is the simplest solution to ensure that the on_destruction() callback receives a valid object (because of the destructor order in a class hierarchy).
from simgrid import Host
- Host.seal(self: simgrid.Host) simgrid.Host
Seal this host
Retrieving hosts
See also simgrid::s4u::Engine::get_all_hosts().
-
static Host *simgrid::s4u::Host::by_name(const std::string &name)
Retrieve a host from its name, or die
See also simgrid.Engine.all_hosts.
- static Host.by_name(name: str) simgrid.Host
Retrieves a host from its name, or die
- static Host.current() simgrid.Host
Retrieves the host on which the running actor is located.
-
size_t sg_host_count()
Returns the amount of hosts existing in the platform.
Modifying characteristics
-
Host *simgrid::s4u::Host::set_sharing_policy(SharingPolicy policy, const s4u::NonLinearResourceCb &cb = {})
Describes how the CPU is shared between concurrent tasks.
Note that the NONLINEAR callback is in the critical path of the solver, so it should be fast.
- Parameters:
policy – Sharing policy
cb – Callback for NONLINEAR policies
- Host.core_count
Manage the number of cores in the CPU
- Host.set_coordinates(self: simgrid.Host, arg0: str) simgrid.Host
Set the coordinates of this host
- Host.set_sharing_policy(self: simgrid.Host, policy: simgrid::s4u::Host::SharingPolicy, cb: Callable[[float, int], float] = None) simgrid.Host
Describe how the CPU is shared
Querying info
-
std::string const &simgrid::s4u::Host::get_name() const
Retrieves the name of that host as a C++ string
-
double simgrid::s4u::Host::get_available_speed() const
Get the available speed ratio, between 0 and 1.
This accounts for external load (see
set_speed_profile()).
-
double simgrid::s4u::Host::get_load() const
Returns the current computation load (in flops per second)
The external load (coming from an availability trace) is not taken in account. You may also be interested in the load plugin.
-
double simgrid::s4u::Host::get_speed() const
Get the peak computing speed in flops/s at the current pstate, NOT taking the external load into account.
The amount of flops per second available for computing depends on several things:
The current pstate determines the maximal peak computing speed (use
get_pstate_speed()to retrieve the computing speed you would get at another pstate)If you declared an external load (with
set_speed_profile()), you must multiply the result ofget_speed()byget_available_speed()to retrieve what a new computation would get.
The remaining speed is then shared between the executions located on this host. You can retrieve the amount of tasks currently running on this host with
get_load().The host may have multiple cores, and your executions may be able to use more than a single core.
Finally, executions of priority 2 get twice the amount of flops than executions of priority 1.
- Host.name
The name of this host (read-only property).
- Host.core_count
Manage the number of cores in the CPU
- Host.load
Returns the current computation load (in flops per second), NOT taking the external load into account. This is the currently achieved speed (read-only property).
- Host.speed
The peak computing speed in flops/s at the current pstate, NOT taking the external load into account. This is the max potential speed (read-only property).
- Host.available_speed
Get the available speed ratio, between 0 and 1. This accounts for external load (see
set_speed_profile()) (read-only property).
-
int sg_host_core_count(const_sg_host_t host)
Return the number of cores.
- Parameters:
host – a host
- Returns:
the number of cores
-
const char *sg_host_get_name(const_sg_host_t host)
Return the name of the sg_host_t.
-
double sg_host_get_load(const_sg_host_t host)
Returns the current computation load (in flops per second).
- Parameters:
host – a host
-
double sg_host_get_speed(const_sg_host_t host)
Return the speed of the processor (in flop/s), regardless of the current load on the machine.
Return the speed of the processor (in flop/s), regardless of the current load on the machine.
User data and properties
-
const std::unordered_map<std::string, std::string> *simgrid::s4u::Host::get_properties() const
Get the properties assigned to a host
-
const char *simgrid::s4u::Host::get_property(const std::string &key) const
Retrieve the property value (or nullptr if not set)
-
void sg_host_set_property_value(sg_host_t host, const char *name, const char *value)
Change the value of a given host property.
- Parameters:
host – a host
name – a property name
value – what to change the property to
-
xbt_dict_t sg_host_get_properties(const_sg_host_t host)
Returns a xbt_dict_t consisting of the list of properties assigned to this host.
Returns a xbt_dict_t consisting of the list of properties assigned to this host.
- Parameters:
host – a host
- Returns:
a dict containing the properties
-
const char *sg_host_get_property_value(const_sg_host_t host, const char *name)
Returns the value of a given host property.
- Parameters:
host – a host
name – a property name
- Returns:
value of a property (or nullptr if property not set)
-
size_t sg_host_extension_create(void (*deleter)(void*))
-
void *sg_host_extension_get(const_sg_host_t host, size_t rank)
Retrieving components
-
size_t simgrid::s4u::Host::get_actor_count() const
Returns how many actors (daemonized or not) have been launched on this host.
- Host.get_disks(self: simgrid.Host) List[simgrid::s4u::Disk]
Retrieve the list of disks in this host
-
void sg_host_get_actor_list(const_sg_host_t host, xbt_dynar_t whereto)
Return the list of actors attached to a host.
- Parameters:
host – a host
whereto – a dynar in which we should push actors living on that host
On/Off
-
void simgrid::s4u::Host::turn_off()
Stop the host if it is on.
Turns that host off. All actors are forcefully stopped.
-
void simgrid::s4u::Host::turn_on()
Turns that host on if it was previously off
This call does nothing if the host is already on. If it was off, all actors which were marked ‘autorestart’ on that host will be restarted automatically (note that this may differ from the actors that were initially running on the host).
All other Host’s properties are left unchanged; in particular, the pstate is left unchanged and not reset to its initial value.
-
int sg_host_is_on(const_sg_host_t host)
Determine if a host is up and running.
See also sg_host_turn_on() and sg_host_turn_off() to switch the host ON and OFF and plugin_host_energy Plugin Host Energy for more info on DVFS.
- Parameters:
host – host to test
- Returns:
Returns true if the host is up and running, and false if it’s currently down
-
void sg_host_turn_off(sg_host_t host)
Stop the host if it is on.
See also sg_host_is_on() to test the current state of the host and plugin_host_energy Plugin Host Energy for more info on DVFS.
-
void sg_host_turn_on(sg_host_t host)
Start the host if it is off.
See also sg_host_is_on() to test the current state of the host and plugin_host_energy Plugin Host Energy for more info on DVFS.
DVFS
See also the relevant examples.
-
unsigned long simgrid::s4u::Host::get_pstate() const
Retrieve the pstate at which the host is currently running.
- Host.pstate
The current pstate (read/write property).
- Host.pstate_count
Retrieve the count of defined pstate levels
- Host.pstate_speed(self: simgrid.Host, arg0: int) float
Retrieve the maximal speed at the given pstate
-
double sg_host_get_available_speed(const_sg_host_t host)
-
unsigned long sg_host_get_nb_pstates(const_sg_host_t host)
Return the total count of pstates defined for a host.
See also Host Energy.
Return the total count of pstates defined for a host.
See also plugin_host_energy Plugin Host Energy.
- Parameters:
host – host to test
-
unsigned long sg_host_get_pstate(const_sg_host_t host)
Gets the pstate at which that host currently runs.
See also plugin_host_energy Plugin Host Energy.
-
double sg_host_get_pstate_speed(const_sg_host_t host, unsigned long pstate_index)
Return the speed of the processor (in flop/s) at a given pstate. See also plugin_host_energy Plugin Host Energy.
- Parameters:
host – host to test
pstate_index – pstate to test
- Returns:
Returns the processor speed associated with pstate_index
-
void sg_host_set_pstate(sg_host_t host, unsigned long pstate)
Sets the pstate at which that host should run.
See also plugin_host_energy Plugin Host Energy.
Dynamic profiles
-
Host *simgrid::s4u::Host::set_speed_profile(kernel::profile::Profile *p)
Specify a profile modeling the external load according to an exhaustive list or a stochastic law.
Each event of the profile represent a peak speed change that is due to external load. The values are given as a rate of the initial value. This means that the actual value is obtained by multiplying the initial value (the peek speed at this pstate level) by the rate coming from the profile.
- Host.set_speed_profile(self: simgrid.Host, arg0: str, arg1: float) None
Specify a profile modeling the external load according to an exhaustive list. Each line of the profile describes timed events as
date ratio. For example, the following content describes an host which computational speed is initially 1 (i.e, 100%) and then halved after 42 seconds:""" 0 1.0 42 0.5 """
Warning
Don’t get fooled: bandwidth and latency profiles of links contain absolute values, while speed profiles of hosts contain ratios.
The second function parameter is the periodicity: the time to wait after the last event to start again over the list. Set it to -1 to not loop over.
- Host.set_state_profile(self: simgrid.Host, arg0: str, arg1: float) None
Specify a profile modeling the churn. Each line of the profile describes timed events as
date boolean, where the boolean (0 or 1) tells whether the host is on. For example, the following content describes a link which turns off at t=1 and back on at t=2:""" 1.0 0 2.0 1 """
The second function parameter is the periodicity: the time to wait after the last event to start again over the list. Set it to -1 to not loop over.
Execution
Platform and routing
You can also start direct communications between two arbitrary hosts
using Comm::sendto().
-
NetZone *simgrid::s4u::Host::get_englobing_zone() const
Returns the networking zone englobing that host.
-
void simgrid::s4u::Host::route_to(const Host *dest, std::vector<Link*> &links, double *latency) const
Find a route toward another host.
walk through the routing components tree and find a route between hosts by calling each “get_route” function in each routing component.
- Parameters:
dest – [IN] where to
links – [OUT] where to store the list of links (must exist, cannot be nullptr).
latency – [OUT] where to store the latency experienced on the path (or nullptr if not interested) It is the caller responsibility to initialize latency to 0 (we add to provided route)
-
void simgrid::s4u::Host::route_to(const Host *dest, std::vector<kernel::resource::StandardLinkImpl*> &links, double *latency) const
Just like Host::routeTo, but filling an array of link implementations.
- Host.netpoint
Retrieve the netpoint associated to this zone
- Host.create_disk(*args, **kwargs)
Overloaded function.
create_disk(self: simgrid.Host, arg0: str, arg1: float, arg2: float) -> simgrid::s4u::Disk
Create a disk
create_disk(self: simgrid.Host, arg0: str, arg1: str, arg2: str) -> simgrid::s4u::Disk
Create a disk
- Host.route_to(self: simgrid.Host, arg0: simgrid.Host) Tuple[List[simgrid::s4u::Link], float]
Retrieves the list of links and the bandwidth between two hosts.
-
void sg_host_get_route(const_sg_host_t from, const_sg_host_t to, xbt_dynar_t links)
Find a route between two hosts.
- Parameters:
from – where from
to – where to
links – [OUT] where to store the list of links (must exist, cannot be nullptr).
-
double sg_host_get_route_bandwidth(const_sg_host_t from, const_sg_host_t to)
Find the bandwidth of the route between two hosts.
- Parameters:
from – where from
to – where to
-
double sg_host_get_route_latency(const_sg_host_t from, const_sg_host_t to)
Find the latency of the route between two hosts.
- Parameters:
from – where from
to – where to
Signals
-
static inline void simgrid::s4u::Host::on_creation_cb(const std::function<void(Host&)> &cb)
Add a callback fired on each newly created host
-
static inline void simgrid::s4u::Host::on_destruction_cb(const std::function<void(Host const&)> &cb)
Add a callback fired just before destructing any host
-
inline void simgrid::s4u::Host::on_this_destruction_cb(const std::function<void(Host const&)> &cb)
Add a callback fired just before destructing this specific host
-
static inline void simgrid::s4u::Host::on_speed_change_cb(const std::function<void(Host const&)> &cb)
Add a callback fired when the speed of any machine is changed (called AFTER the change) (either because of a pstate switch or because of an external load event coming from the profile)
-
inline void simgrid::s4u::Host::on_this_speed_change_cb(const std::function<void(Host const&)> &cb)
Add a callback fired when the speed of this specific machine is changed (called AFTER the change) (either because of a pstate switch or because of an external load event coming from the profile)
-
static inline void simgrid::s4u::Host::on_onoff_cb(const std::function<void(Host const&)> &cb)
Add a callback fired when any machine is turned on or off (called AFTER the change)
class Link
-
class Link : public xbt::Extendable<Link>
A Link represents the network facilities between
hosts.Subclassed by simgrid::s4u::SplitDuplexLink
-
class SplitDuplexLink : public simgrid::s4u::Link
A SplitDuplexLink encapsulates the
linkswhich compose a Split-Duplex link. Remember that a Split-Duplex link is nothing more than a pair of up/down links.
-
class LinkInRoute
Another encapsulation for using links in the
NetZone::add_route()When adding a route with split-duplex links, you need to specify the direction of the link so SimGrid can know exactly which physical link to insert in the route.
For shared/fat-pipe links, use the
Direction::NONEsince they don’t have the concept of UP/DOWN links.
- class simgrid.Link
Network link. See the C++ documentation for details.
Basic management
#include <simgrid/s4u/Link.hpp>
Note that there is no LinkPtr type and that you cannot use the RAII idiom on hosts because SimGrid does not allow (yet) to create nor destroy resources once the simulation is started.
from simgrid import Link
- Link.seal(self: simgrid.Link) simgrid.Link
Seal this link
Retrieving links
See also simgrid::s4u::Engine::get_all_links().
See also simgrid.Engine.all_links.
- static Link.by_name(arg0: str) simgrid.Link
Retrieves a Link from its name, or dies
- Link.name
The name of this link
Querying info
- Link.name
The name of this link
-
const char *sg_link_get_name(const_sg_link_t link)
Performance
-
double simgrid::s4u::Link::get_bandwidth() const
Get/Set the bandwidth of the current Link (in bytes per second)
-
double simgrid::s4u::Link::get_latency() const
Get/Set the latency of the current Link (in seconds)
- Link.bandwidth
The bandwidth (in bytes per second) (read-only property).
- Link.latency
The latency (in seconds) (read-only property).
- Link.set_bandwidth(self: simgrid.Link, arg0: float) simgrid.Link
Set the bandwidth (in byte per second).
- Link.set_latency(*args, **kwargs)
Overloaded function.
set_latency(self: simgrid.Link, arg0: str) -> simgrid.Link
Set the latency as a string. Accepts values with units, such as ‘1s’ or ‘7ms’. Full list of accepted units: w (week), d (day), h, s, ms, us, ns, ps.
set_latency(self: simgrid.Link, arg0: float) -> simgrid.Link
Set the latency as a float (in seconds).
-
double sg_link_get_bandwidth(const_sg_link_t link)
-
double sg_link_get_latency(const_sg_link_t link)
Model policy
-
enum class simgrid::s4u::Link::SharingPolicy
Specifies how a given link is shared between concurrent communications
Values:
-
enumerator NONLINEAR
This policy takes a callback that specifies the maximal capacity as a function of the number of usage. See the examples with ‘degradation’ in their name.
-
enumerator WIFI
Pseudo-sharing policy requesting wifi-specific sharing.
-
enumerator SPLITDUPLEX
Each link is split in 2, UP and DOWN, one per direction. These links are SHARED.
-
enumerator SHARED
The bandwidth is shared between all comms using that link, regardless of their direction.
-
enumerator FATPIPE
Each comm can use the link fully, with no sharing (only a maximum). This is intended to represent the backbone links that cannot be saturated by concurrent links, but have a maximal bandwidth.
-
enumerator NONLINEAR
-
SharingPolicy simgrid::s4u::Link::get_sharing_policy() const
-
Link *simgrid::s4u::Link::set_sharing_policy(SharingPolicy policy, const NonLinearResourceCb &cb = {})
Describes how the link is shared between flows.
Note that the NONLINEAR callback is in the critical path of the solver, so it should be fast.
- Link.set_concurrency_limit(self: simgrid.Link, arg0: int) simgrid.Link
Set concurrency limit for this link
- Link.set_sharing_policy(self: simgrid.Link, arg0: simgrid::s4u::Link::SharingPolicy, arg1: Callable[[float, int], float]) simgrid.Link
Set sharing policy for this link
User data and properties
On/Off
See also simgrid::s4u::Link::set_state_profile().
See also simgrid.Link.set_state_profile().
- Link.is_on(self: simgrid.Link) bool
Check whether the link is on.
- Link.turn_off(self: simgrid.Link) None
Turns the link off.
- Link.turn_on(self: simgrid.Link) None
Turns the link on.
Dynamic profiles
See Modeling churn (e.g., in P2P) for more details.
-
Link *simgrid::s4u::Link::set_bandwidth_profile(kernel::profile::Profile *profile)
Setup the profile with bandwidth events (peak speed changes due to external load). The profile must contain percentages (value between 0 and 1).
- Link.set_bandwidth_profile(self: simgrid.Link, arg0: str, arg1: float) None
Specify a profile modeling the external load according to an exhaustive list. Each line of the profile describes timed events as
date bandwidth(in bytes per second). For example, the following content describes a link which bandwidth changes to 40 Mb/s at t=4, and to 6 Mb/s at t=8:""" 4.0 40000000 8.0 60000000 """
Warning
Don’t get fooled: bandwidth and latency profiles of links contain absolute values, while speed profiles of hosts contain ratios.
The second function parameter is the periodicity: the time to wait after the last event to start again over the list. Set it to -1 to not loop over.
- Link.set_latency_profile(self: simgrid.Link, arg0: str, arg1: float) None
Specify a profile modeling the external load according to an exhaustive list. Each line of the profile describes timed events as
date latency(in seconds). For example, the following content describes a link which latency changes to 1ms (0.001s) at t=1, and to 2s at t=2:""" 1.0 0.001 2.0 2 """
Warning
Don’t get fooled: bandwidth and latency profiles of links contain absolute values, while speed profiles of hosts contain ratios.
The second function parameter is the periodicity: the time to wait after the last event to start again over the list. Set it to -1 to not loop over.
- Link.set_state_profile(self: simgrid.Link, arg0: str, arg1: float) None
Specify a profile modeling the churn. Each line of the profile describes timed events as
date boolean, where the boolean (0 or 1) tells whether the link is on. For example, the following content describes a link which turns off at t=1 and back on at t=2:""" 1.0 0 2.0 1 """
The second function parameter is the periodicity: the time to wait after the last event to start again over the list. Set it to -1 to not loop over.
WIFI links
-
void simgrid::s4u::Link::set_host_wifi_rate(const s4u::Host *host, int level) const
Set the level of communication speed of the given host on this wifi link.
The bandwidth of a wifi link for a given host depends on its SNR (signal to noise ratio), which ultimately depends on the distance between the host and the station and the material between them.
This is modeled in SimGrid by providing several bandwidths to wifi links, one per SNR level (just provide comma-separated values in the XML file). By default, the first level in the list is used, but you can use the current function to specify that a given host uses another level of bandwidth. This can be used to take the location of hosts into account, or even to model mobility in your SimGrid simulation.
Note that this function asserts that the link is actually a wifi link
warning: in the case where a 0Mbps data rate should be used, set that rate only once during the experiment, and don’t modify the bandwidth of that host later
- Link.set_host_wifi_rate(self: simgrid.Link, arg0: simgrid.Host, arg1: int) None
Set level of communication speed of given host on this Wi-Fi link
Signals
-
static inline void simgrid::s4u::Link::on_bandwidth_change_cb(const std::function<void(Link const&)> &cb)
Add a callback fired when the bandwidth of any Link changes.
-
inline void simgrid::s4u::Link::on_this_bandwidth_change_cb(const std::function<void(Link const&)> &cb)
Add a callback fired when the bandwidth of this specific Link changes.
-
static inline void simgrid::s4u::Link::on_communication_state_change_cb(const std::function<void(kernel::resource::NetworkAction&, kernel::resource::Action::State)> &cb)
Add a callback fired when a communication changes it state (ready/done/cancel)
-
static inline void simgrid::s4u::Link::on_creation_cb(const std::function<void(Link&)> &cb)
Add a callback fired when a new Link is created.
-
static inline void simgrid::s4u::Link::on_destruction_cb(const std::function<void(Link const&)> &cb)
Add a callback fired when any Link is destroyed.
-
inline void simgrid::s4u::Link::on_this_destruction_cb(const std::function<void(Link const&)> &cb)
Add a callback fired when this specific Link is destroyed.
class NetZone
-
class NetZone
Networking Zones.
A netzone is a network container, in charge of routing information between elements (hosts) and to the nearby netzones. In SimGrid, there is a hierarchy of netzones, with a unique root zone (that you can retrieve from the s4u::Engine).
- class simgrid.NetZone
Networking Zones. See the C++ documentation for details.
Basic management
#include <simgrid/s4u/NetZone.hpp>
Note that there is no NetZonePtr type and that you cannot use the RAII idiom on network zones because SimGrid does not allow (yet) to create nor destroy resources once the simulation is started.
from simgrid import NetZone
- NetZone.seal(self: simgrid.NetZone) simgrid.NetZone
Seal this NetZone
Retrieving zones
See simgrid::s4u::Engine::get_netzone_root(),
simgrid::s4u::Engine::netzone_by_name_or_null() and
simgrid::s4u::Engine::get_filtered_netzones().
-
sg_netzone_t sg_zone_get_by_name(const char *name)
-
sg_netzone_t sg_zone_get_root()
Querying info
-
const char *simgrid::s4u::NetZone::get_cname() const
Retrieves the name of that netzone as a C string.
- NetZone.name
The name of this network zone (read-only property).
- NetZone.netpoint
Retrieve the netpoint associated to this zone
-
const char *sg_zone_get_name(const_sg_netzone_t zone)
User data and properties
-
const std::unordered_map<std::string, std::string> *simgrid::s4u::NetZone::get_properties() const
Get the properties assigned to a netzone
- NetZone.set_property(self: simgrid.NetZone, arg0: str, arg1: str) None
Add a property to this zone
-
const char *sg_zone_get_property_value(const_sg_netzone_t as, const char *name)
-
void sg_zone_set_property_value(sg_netzone_t netzone, const char *name, const char *value)
Retrieving components
-
void sg_zone_get_hosts(const_sg_netzone_t zone, xbt_dynar_t whereto)
Routing data
-
void simgrid::s4u::NetZone::add_route(const Host *src, const Host *dst, const std::vector<LinkInRoute> &link_list, bool symmetrical = true)
Add a route between 2 hosts.
- Parameters:
src – Source host
dst – Destination host
link_list – List of links and their direction used in this communication
symmetrical – Bi-directional communication
-
void simgrid::s4u::NetZone::add_route(const Host *src, const Host *dst, const std::vector<const Link*> &links)
Add a route between 2 hosts.
- Parameters:
src – Source host
dst – Destination host
links – List of links. The UP direction will be used on src->dst and DOWN direction on dst->src
-
void simgrid::s4u::NetZone::add_route(const NetZone *src, const NetZone *dst, const std::vector<LinkInRoute> &link_list, bool symmetrical = true)
Add a route between 2 netzones, and same in other direction.
- Parameters:
src – Source netzone
dst – Destination netzone
link_list – List of links and their direction used in this communication
symmetrical – Bi-directional communication
- NetZone.add_route(*args, **kwargs)
Overloaded function.
add_route(self: simgrid.NetZone, arg0: simgrid::s4u::Host, arg1: simgrid::s4u::Host, arg2: List[simgrid::s4u::LinkInRoute], arg3: bool) -> None
Add a route between 2 hosts
add_route(self: simgrid.NetZone, arg0: simgrid::s4u::Host, arg1: simgrid::s4u::Host, arg2: List[simgrid::s4u::Link]) -> None
Add a route between 2 hosts
add_route(self: simgrid.NetZone, arg0: simgrid.NetZone, arg1: simgrid.NetZone, arg2: List[simgrid::s4u::LinkInRoute], arg3: bool) -> None
Add a route between 2 netzones. The gateway of each zone gets used.
add_route(self: simgrid.NetZone, arg0: simgrid.NetZone, arg1: simgrid.NetZone, arg2: List[simgrid::s4u::Link]) -> None
Add a route between 2 netzones. The gateway of each zone gets used.
- NetZone.set_parent(self: simgrid.NetZone, arg0: simgrid.NetZone) simgrid.NetZone
Set the parent of this zone
-
void sg_zone_get_sons(const_sg_netzone_t zone, xbt_dict_t whereto)
Signals
Creating resources
Zones
-
NetZone *simgrid::s4u::create_torus_zone(const std::string &name, const NetZone *parent, const std::vector<unsigned long> &dimensions, const ClusterCallbacks &set_callbacks, double bandwidth, double latency, Link::SharingPolicy sharing_policy)
Create a torus zone.
Torus clusters are characterized by:
dimensions, eg. {3,3,3} creates a torus with X = 3 elements, Y = 3 and Z = 3. In total, this cluster have 27 elements
inter-node communication: (bandwidth, latency, sharing_policy) the elements are connected through regular links with these characteristics More details in: Torus Cluster
Moreover, this method accepts 3 callbacks to populate the cluster: set_netpoint, set_loopback and set_limiter .
Note that the all elements in a Torus cluster must have (or not) the same elements (loopback and limiter)
- Parameters:
name – NetZone’s name
parent – Pointer to parent’s netzone (nullptr if root netzone). Needed to be able to create the resources inside the netzone
dimensions – List of positive integers (> 0) which determines the torus’ dimensions
set_callbacks – Callbacks to set properties from cluster elements (netpoint, loopback and limiter)
bandwidth – Characteristics of the inter-nodes link
latency – Characteristics of the inter-nodes link
sharing_policy – Characteristics of the inter-nodes link
- Returns:
Pointer to new netzone
-
NetZone *simgrid::s4u::create_fatTree_zone(const std::string &name, const NetZone *parent, const FatTreeParams ¶meters, const ClusterCallbacks &set_callbacks, double bandwidth, double latency, Link::SharingPolicy sharing_policy)
Create a Fat-Tree zone.
Fat-Tree clusters are characterized by:
levels: number of levels in the cluster, e.g. 2 (the final tree will have n+1 levels)
downlinks: for each level, how many connections between elements below them, e.g. 2, 3: level 1 nodes are connected to 2 nodes in level 2, which are connected to 3 nodes below. Determines the number total of leaves in the tree.
uplinks: for each level, how nodes are connected, e.g. 1, 2
link count: for each level, number of links connecting the nodes, e.g. 1, 1
The best way to understand it is looking to the doc available in: Fat Tree Cluster
Moreover, this method accepts 3 callbacks to populate the cluster: set_netpoint, set_loopback and set_limiter .
Note that the all elements in a Fat-Tree cluster must have (or not) the same elements (loopback and limiter)
- Parameters:
name – NetZone’s name
parent – Pointer to parent’s netzone (nullptr if root netzone). Needed to be able to create the resources inside the netzone
parameters – Characteristics of this Fat-Tree
set_callbacks – Callbacks to set properties from cluster elements (netpoint, loopback and limiter)
bandwidth – Characteristics of the inter-nodes link
latency – Characteristics of the inter-nodes link
sharing_policy – Characteristics of the inter-nodes link
- Returns:
Pointer to new netzone
-
NetZone *simgrid::s4u::create_dragonfly_zone(const std::string &name, const NetZone *parent, const DragonflyParams ¶meters, const ClusterCallbacks &set_callbacks, double bandwidth, double latency, Link::SharingPolicy sharing_policy)
Create a Dragonfly zone.
Dragonfly clusters are characterized by:
groups: number of groups and links between each group, e.g. 2,2.
chassis: number of chassis in each group and the number of links used to connect the chassis, e.g. 2,3
routers: number of routers in each chassis and their links, e.g. 3,1
nodes: number of nodes connected to each router using a single link, e.g. 2
In total, the cluster will have groups * chassis * routers * nodes elements/leaves.
The best way to understand it is looking to the doc available in: Dragonfly Cluster
Moreover, this method accepts 3 callbacks to populate the cluster: set_netpoint, set_loopback and set_limiter .
Note that the all elements in a Dragonfly cluster must have (or not) the same elements (loopback and limiter)
- Parameters:
name – NetZone’s name
parent – Pointer to parent’s netzone (nullptr if root netzone). Needed to be able to create the resources inside the netzone
parameters – Characteristics of this Dragonfly
set_callbacks – Callbacks to set properties from cluster elements (netpoint, loopback and limiter)
bandwidth – Characteristics of the inter-nodes link
latency – Characteristics of the inter-nodes link
sharing_policy – Characteristics of the inter-nodes link
- Returns:
Pointer to new netzone
- static NetZone.create_full_zone(arg0: str) simgrid.NetZone
Creates a zone of type FullZone
- static NetZone.create_empty_zone(arg0: str) simgrid.NetZone
Creates a zone of type Empty
- static NetZone.create_star_zone(arg0: str) simgrid.NetZone
Creates a zone of type Star
- static NetZone.create_dijkstra_zone(arg0: str) simgrid.NetZone
Creates a zone of type Dijkstra
- static NetZone.create_floyd_zone(arg0: str) simgrid.NetZone
Creates a zone of type Floyd
- static NetZone.create_vivaldi_zone(arg0: str) simgrid.NetZone
Creates a zone of type Vivaldi
- static NetZone.create_wifi_zone(arg0: str) simgrid.NetZone
Creates a zone of type Wi-Fi
- static NetZone.create_torus_zone(arg0: str, arg1: simgrid.NetZone, arg2: List[int], arg3: simgrid::s4u::ClusterCallbacks, arg4: float, arg5: float, arg6: simgrid::s4u::Link::SharingPolicy) simgrid.NetZone
Creates a cluster of type Torus
- static NetZone.create_fatTree_zone(arg0: str, arg1: simgrid.NetZone, arg2: simgrid::s4u::FatTreeParams, arg3: simgrid::s4u::ClusterCallbacks, arg4: float, arg5: float, arg6: simgrid::s4u::Link::SharingPolicy) simgrid.NetZone
Creates a cluster of type Fat-Tree
- static NetZone.create_dragonfly_zone(arg0: str, arg1: simgrid.NetZone, arg2: simgrid::s4u::DragonflyParams, arg3: simgrid::s4u::ClusterCallbacks, arg4: float, arg5: float, arg6: simgrid::s4u::Link::SharingPolicy) simgrid.NetZone
Creates a cluster of type Dragonfly
Hosts
-
s4u::Host *simgrid::s4u::NetZone::create_host(const std::string &name, const std::vector<double> &speed_per_pstate)
Create a host.
- Parameters:
name – Host name
speed_per_pstate – Vector of CPU’s speeds
-
s4u::Host *simgrid::s4u::NetZone::create_host(const std::string &name, const std::vector<std::string> &speed_per_pstate)
Create a Host (string version)
- Throws:
std::invalid_argument – if speed format is incorrect.
-
s4u::Host *simgrid::s4u::NetZone::create_host(const std::string &name, const std::vector<double> &speed_per_pstate)
Create a host.
- Parameters:
name – Host name
speed_per_pstate – Vector of CPU’s speeds
- NetZone.create_host(*args, **kwargs)
Overloaded function.
create_host(self: simgrid.NetZone, arg0: str, arg1: float) -> simgrid::s4u::Host
Creates a host
create_host(self: simgrid.NetZone, arg0: str, arg1: str) -> simgrid::s4u::Host
Creates a host
create_host(self: simgrid.NetZone, arg0: str, arg1: List[float]) -> simgrid::s4u::Host
Creates a host
create_host(self: simgrid.NetZone, arg0: str, arg1: List[str]) -> simgrid::s4u::Host
Creates a host
Links
-
s4u::Link *simgrid::s4u::NetZone::create_link(const std::string &name, const std::vector<double> &bandwidths)
Create a link.
- Parameters:
name – Link name
bandwidths – Link’s speed (vector for wifi links)
- Throws:
std::invalid_argument – if bandwidth format is incorrect.
-
s4u::Link *simgrid::s4u::NetZone::create_link(const std::string &name, const std::vector<std::string> &bandwidths)
Create a link (string version)
-
s4u::Link *simgrid::s4u::NetZone::create_link(const std::string &name, const std::string &bandwidth)
-
s4u::SplitDuplexLink *simgrid::s4u::NetZone::create_split_duplex_link(const std::string &name, const std::string &bandwidth)
Create a split-duplex link.
In SimGrid, split-duplex links are a composition of 2 regular (shared) links (up/down).
This function eases its utilization by creating the 2 links for you. We append a suffix “_UP” and “_DOWN” to your link name to identify each of them.
Both up/down links have exactly the same bandwidth
- Parameters:
name – Name of the link
bandwidth – Speed
-
s4u::SplitDuplexLink *simgrid::s4u::NetZone::create_split_duplex_link(const std::string &name, double bandwidth)
- NetZone.create_link(*args, **kwargs)
Overloaded function.
create_link(self: simgrid.NetZone, arg0: str, arg1: float) -> simgrid::s4u::Link
Creates a network link
create_link(self: simgrid.NetZone, arg0: str, arg1: str) -> simgrid::s4u::Link
Creates a network link
create_link(self: simgrid.NetZone, arg0: str, arg1: List[float]) -> simgrid::s4u::Link
Creates a network link
create_link(self: simgrid.NetZone, arg0: str, arg1: List[str]) -> simgrid::s4u::Link
Creates a network link
- NetZone.create_split_duplex_link(*args, **kwargs)
Overloaded function.
create_split_duplex_link(self: simgrid.NetZone, arg0: str, arg1: float) -> simgrid::s4u::SplitDuplexLink
Creates a split-duplex link
create_split_duplex_link(self: simgrid.NetZone, arg0: str, arg1: str) -> simgrid::s4u::SplitDuplexLink
Creates a split-duplex link
Router
- NetZone.create_router(self: simgrid.NetZone, arg0: str) simgrid::kernel::routing::NetPoint
Create a router
class VirtualMachine
-
class VirtualMachine : public simgrid::s4u::Host
A VM represents a virtual machine (or a container) that hosts actors. The total computing power that the contained actors can get is constrained to the virtual machine size.
Basic management
#include <simgrid/s4u/VirtualMachine.hpp>
Note that there is no VirtualMachinePtr type, and that you cannot use the RAII idiom on virtual machines. There is no good reason for that and should change in the future.
Creating VMs
-
VirtualMachine *simgrid::s4u::Host::create_vm(const std::string &name, int core_amount)
-
VirtualMachine *simgrid::s4u::Host::create_vm(const std::string &name, int core_amount, size_t ramsize)
-
virtual void simgrid::s4u::VirtualMachine::destroy() override
Fire the required callbacks and destroy the object.
Don’t delete directly a host, call h->destroy() instead.
This is cumbersome but this is the simplest solution to ensure that the on_destruction() callback receives a valid object (because of the destructor order in a class hierarchy).
Querying info
-
Host *simgrid::s4u::VirtualMachine::get_pm() const
-
size_t simgrid::s4u::VirtualMachine::get_ramsize() const
-
State simgrid::s4u::VirtualMachine::get_state() const
-
VirtualMachine *simgrid::s4u::VirtualMachine::set_bound(double bound)
-
VirtualMachine *simgrid::s4u::VirtualMachine::set_pm(Host *pm)
-
VirtualMachine *simgrid::s4u::VirtualMachine::set_ramsize(size_t ramsize)
-
size_t sg_vm_get_ramsize(const_sg_vm_t vm)
-
const char *sg_vm_get_name(const_sg_vm_t vm)
-
sg_host_t sg_vm_get_pm(const_sg_vm_t vm)
-
int sg_vm_is_created(const_sg_vm_t vm)
-
int sg_vm_is_running(const_sg_vm_t vm)
-
int sg_vm_is_suspended(const_sg_vm_t vm)
Life cycle
-
void simgrid::s4u::VirtualMachine::resume()
-
void simgrid::s4u::VirtualMachine::shutdown()
-
void simgrid::s4u::VirtualMachine::start()
-
void simgrid::s4u::VirtualMachine::suspend()
Signals
-
static inline void simgrid::s4u::VirtualMachine::on_creation_cb(const std::function<void(VirtualMachine&)> &cb)
Add a callback fired when any VM is created
-
static inline void simgrid::s4u::VirtualMachine::on_destruction_cb(const std::function<void(VirtualMachine const&)> &cb)
Add a callback fired when any VM is destroyed
-
inline void simgrid::s4u::VirtualMachine::on_this_destruction_cb(const std::function<void(VirtualMachine const&)> &cb)
Add a callback fired when this specific VM is destroyed
-
static inline void simgrid::s4u::VirtualMachine::on_migration_end_cb(const std::function<void(VirtualMachine const&)> &cb)
Add a callback fired when any VM ends a migration
-
inline void simgrid::s4u::VirtualMachine::on_this_migration_end_cb(const std::function<void(VirtualMachine const&)> &cb)
Add a callback fired when this specific VM ends a migration
-
static inline void simgrid::s4u::VirtualMachine::on_migration_start_cb(const std::function<void(VirtualMachine const&)> &cb)
Add a callback fired when any VM starts a migration
-
inline void simgrid::s4u::VirtualMachine::on_this_migration_start_cb(const std::function<void(VirtualMachine const&)> &cb)
Add a callback fired when this specific VM starts a migration
-
static inline void simgrid::s4u::VirtualMachine::on_resume_cb(const std::function<void(VirtualMachine const&)> &cb)
Add a callback fired when any VM is resumed
-
inline void simgrid::s4u::VirtualMachine::on_this_resume_cb(const std::function<void(VirtualMachine const&)> &cb)
Add a callback fired when this specific VM is resumed
-
static inline void simgrid::s4u::VirtualMachine::on_shutdown_cb(const std::function<void(VirtualMachine const&)> &cb)
Add a callback fired when any VM is shut down
-
inline void simgrid::s4u::VirtualMachine::on_this_shutdown_cb(const std::function<void(VirtualMachine const&)> &cb)
Add a callback fired when this specific VM is shut down
-
static inline void simgrid::s4u::VirtualMachine::on_start_cb(const std::function<void(VirtualMachine const&)> &cb)
Add a callback fired when any VM starts
-
inline void simgrid::s4u::VirtualMachine::on_this_start_cb(const std::function<void(VirtualMachine const&)> &cb)
Add a callback fired when this specific VM starts
-
static inline void simgrid::s4u::VirtualMachine::on_started_cb(const std::function<void(VirtualMachine const&)> &cb)
Add a callback fired when any VM is actually started
-
inline void simgrid::s4u::VirtualMachine::on_this_started_cb(const std::function<void(VirtualMachine const&)> &cb)
Add a callback fired when this specific VM is actually started
-
static inline void simgrid::s4u::VirtualMachine::on_suspend_cb(const std::function<void(VirtualMachine const&)> &cb)
Add a callback fired when any VM is suspended
-
inline void simgrid::s4u::VirtualMachine::on_this_suspend_cb(const std::function<void(VirtualMachine const&)> &cb)
Add a callback fired when this specific VM is suspended
Activities
class Activity
-
class Activity : public xbt::Extendable<Activity>
Activities.
This class is the ancestor of every activities that an actor can undertake. That is, activities are all the things that do take time to the actor in the simulated world.
Subclassed by simgrid::s4u::Activity_T< Comm >, simgrid::s4u::Activity_T< Exec >, simgrid::s4u::Activity_T< Io >, simgrid::s4u::Activity_T< Mess >, simgrid::s4u::Activity_T< AnyActivity >
Known subclasses: Communications (started on Mailboxes and consuming links), Executions (started on Host and consuming CPU resources) I/O (started on and consuming disks). See also the section on activities above.
Basic management
Querying info
-
virtual double simgrid::s4u::Activity::get_remaining() const
Get the remaining amount of work that this Activity entails. When it’s 0, it’s done.
-
inline Activity::State simgrid::s4u::Activity::get_state() const
Retrieve the current state of the activity
Activities life cycle
Suspending and resuming an activity
class Comm
- class simgrid.Comm
Communication. See the C++ documentation for details.
Basic management
Querying info
-
inline size_t simgrid::s4u::Comm::get_dst_data_size() const
Retrieve the size of the received data. Not to be mixed with Activity::get_remaining()
-
inline Mailbox *simgrid::s4u::Comm::get_mailbox() const
Retrieve the mailbox on which this comm acts. This is nullptr if the comm was created through sendto()
-
CommPtr simgrid::s4u::Comm::set_dst_data(void **buff)
Specify where to receive the data.
That’s a buffer where the sent data will be copied
-
CommPtr simgrid::s4u::Comm::set_dst_data(void **buff, size_t size)
Specify the buffer in which the data should be received
That’s a buffer where the sent data will be copied
-
inline Comm *simgrid::s4u::Comm::detach()
Start the activity, and ignore its result. It can be completely forgotten after that.
-
CommPtr simgrid::s4u::Comm::set_payload_size(uint64_t bytes)
Specify the amount of bytes which exchange should be simulated (not to be mixed with set_src_data_size())
That’s the size of the simulated data, that’s completely unrelated from the actual data size (given by
simgrid::s4u::Comm::set_src_data_size()).
-
CommPtr simgrid::s4u::Comm::set_rate(double rate)
Sets the maximal communication rate (in byte/sec). Must be done before start
-
CommPtr simgrid::s4u::Comm::set_src_data(void *buff)
Specify the data to send.
This is way will get actually copied over to the receiver. That’s completely unrelated from the simulated size (given by
simgrid::s4u::Comm::set_payload_size()): you can send a short buffer in your simulator, that represents a very large message in the simulated world, or the opposite.
-
CommPtr simgrid::s4u::Comm::set_src_data(void *buff, size_t size)
Specify the data to send and its size (not to be mixed with set_payload_size())
This is way will get actually copied over to the receiver. That’s completely unrelated from the simulated size (given by
simgrid::s4u::Comm::set_payload_size()): you can send a short buffer in your simulator, that represents a very large message in the simulated world, or the opposite.
-
CommPtr simgrid::s4u::Comm::set_src_data_size(size_t size)
Specify the size of the data to send (not to be mixed with set_payload_size())
That’s the size of the data to actually copy in the simulator (ie, the data passed with
simgrid::s4u::Comm::set_src_data()). That’s completely unrelated from the simulated size (given bysimgrid::s4u::Comm::set_payload_size())): you can send a short buffer in your simulator, that represents a very large message in the simulated world, or the opposite.
- Comm.dst_data_size
Retrieve the size of the received data.
- Comm.mailbox
Retrieve the mailbox on which this comm acts.
- Comm.sender
- Comm.state_str
Retrieve the Comm state as string
- Comm.detach(self: simgrid.Comm) simgrid.Comm
Start the comm, and ignore its result. It can be completely forgotten after that.
- Comm.set_payload_size(self: simgrid.Comm, bytes: int) simgrid.Comm
Specify the amount of bytes which exchange should be simulated.
- Comm.set_rate(self: simgrid.Comm, rate: float) simgrid.Comm
Sets the maximal communication rate (in byte/sec). Must be done before start
Direct host-to-host communication
Most communications are created using Mailboxes, but you can also start direct communications as shown below. See also the relevant examples.
- static Comm.sendto(from: simgrid.Host, to: simgrid.Host, simulated_size_in_bytes: int) None
Do a blocking communication between two arbitrary hosts.
- static Comm.sendto_init(from: simgrid.Host, to: simgrid.Host) simgrid.Comm
Creates a communication between the two given hosts, bypassing the mailbox mechanism.
- static Comm.sendto_async(from: simgrid.Host, to: simgrid.Host, simulated_size_in_bytes: int) simgrid.Comm
Do a blocking communication between two arbitrary hosts.
This initializes a communication that completely bypass the mailbox and actors mechanism. There is really no limit on the hosts involved. In particular, the actor does not have to be on one of the involved hosts.
Life cycle
- Comm.cancel(self: simgrid.Comm) simgrid.Comm
Cancel the activity.
- Comm.start(self: simgrid.Comm) simgrid.Comm
Starts a previously created activity. This function is optional: you can call wait() even if you didn’t call start()
- Comm.test(self: simgrid.Comm) bool
Test whether the communication is terminated.
- Comm.wait(self: simgrid.Comm) simgrid.Comm
Block until the completion of that communication.
- Comm.wait_for(self: simgrid.Comm, timeout: float) simgrid.Comm
Block until the completion of that communication, or raises TimeoutException after the specified timeout.
- Comm.wait_until(self: simgrid.Comm, time_limit: float) None
Block until the completion of that communication, or raises TimeoutException after the specified time.
-
sg_error_t sg_comm_wait(sg_comm_t comm)
Block this actor until this communication is finished
Suspending and resuming a communication
-
virtual Activity *simgrid::s4u::Comm::suspend()
Blocks the progression of this activity until it gets resumed
- Comm.suspend(self: simgrid.Comm) simgrid.Activity
Suspend the activity.
- Comm.resume(self: simgrid.Comm) simgrid.Activity
Resume the activity.
- Comm.is_suspended
Whether this Comm is suspended
Signals
-
static inline void simgrid::s4u::Comm::on_completion_cb(const std::function<void(Comm const&)> &cb)
Add a callback fired when any activity completes (either normally, cancelled or failed)
-
static inline void simgrid::s4u::Comm::on_start_cb(const std::function<void(Comm const&)> &cb)
Add a callback fired when any activity starts (no veto)
-
static inline void simgrid::s4u::Comm::on_recv_cb(const std::function<void(Comm const&)> &cb)
Add a callback fired when the recv of any Comm is posted
-
static inline void simgrid::s4u::Comm::on_send_cb(const std::function<void(Comm const&)> &cb)
Add a callback fired when the send of any Comm is posted
Warning
doxygenfunction: Cannot find function “simgrid::s4u::Comm::on_suspended_cb” in doxygen xml output for project “simgrid” from directory: ../build/xml
-
static inline void simgrid::s4u::Comm::on_suspend_cb(const std::function<void(Comm const&)> &cb)
Add a callback fired when any activity is suspended
-
static inline void simgrid::s4u::Comm::on_resume_cb(const std::function<void(Comm const&)> &cb)
Add a callback fired when any activity is resumed after being suspended
Warning
doxygenfunction: Cannot find function “simgrid::s4u::Comm::on_resumed_cb” in doxygen xml output for project “simgrid” from directory: ../build/xml
-
static inline void simgrid::s4u::Comm::on_veto_cb(const std::function<void(Comm&)> &cb)
Add a callback fired each time that any activity fails to start because of a veto (e.g., unsolved dependency or no resource assigned)
-
inline void simgrid::s4u::Comm::on_this_completion_cb(const std::function<void(Comm const&)> &cb)
Add a callback fired when this specific activity completes (either normally, cancelled or failed)
-
inline void simgrid::s4u::Comm::on_this_recv_cb(const std::function<void(Comm const&)> &cb)
Add a callback fired when the recv of this specific Comm is posted
-
inline void simgrid::s4u::Comm::on_this_resume_cb(const std::function<void(Comm const&)> &cb)
Add a callback fired when this specific activity is resumed after being suspended
-
inline void simgrid::s4u::Comm::on_this_send_cb(const std::function<void(Comm const&)> &cb)
Add a callback fired when the send of this specific Comm is posted
-
inline void simgrid::s4u::Comm::on_this_start_cb(const std::function<void(Comm const&)> &cb)
Add a callback fired when this specific activity starts (no veto)
Warning
doxygenfunction: Cannot find function “simgrid::s4u::Comm::on_this_suspended_cb” in doxygen xml output for project “simgrid” from directory: ../build/xml
class Exec
-
class Exec : public simgrid::s4u::Activity_T<Exec>
Computation Activity, representing the asynchronous executions.
Most of them are created with
simgrid::s4u::this_actor::exec_init()orsimgrid::s4u::Host::execute(), and represent a classical (sequential) execution. This can be used to simulate some computation occurring in another thread when the calling actor is not blocked during the execution.You can also use
simgrid::s4u::this_actor::parallel_execute()to create parallel executions. These objects represent distributed computations involving computations on several hosts and communications between them. Such objects can for example represent a matrix multiplication done with ScaLAPACK on a real system. Once created, parallel Exec are very similar to the sequential ones. The only difference is that you cannot migrate them, and their remaining amount of work can only be defined as a ratio. See the doc ofsimgrid::s4u::Exec::get_remaining()andsimgrid::s4u::Exec::get_remaining_ratio()for more info.
- class simgrid.Exec
Execution. See the C++ documentation for details.
Basic management
Querying info
-
Host *simgrid::s4u::Exec::get_host() const
Retrieve the host on which this activity takes place. If it runs on more than one host, only the first host is returned.
-
virtual double simgrid::s4u::Exec::get_remaining() const override
On sequential executions, returns the amount of flops that remain to be done; This cannot be used on parallel executions.
-
double simgrid::s4u::Exec::get_remaining_ratio() const
Returns the ratio of elements that are still to do.
The returned value is between 0 (completely done) and 1 (nothing done yet).
-
ExecPtr simgrid::s4u::Exec::set_bound(double bound)
change the execution bound This means changing the maximal amount of flops per second that it may consume, regardless of what the host may deliver. Currently, this cannot be changed once the exec started. See also the “cloud-capping” example.
- Exec.host
Host on which this execution runs. Only the first host is returned for parallel executions. Changing this value migrates the execution.
- Exec.remaining
Amount of flops that remain to be computed until completion (read-only property).
- Exec.remaining_ratio
Amount of work remaining until completion from 0 (completely done) to 1 (nothing done yet) (read-only property).
-
const char *sg_exec_get_name(const_sg_exec_t exec)
-
double sg_exec_get_remaining(const_sg_exec_t exec)
-
double sg_exec_get_remaining_ratio(const_sg_exec_t exec)
Life cycle
- Exec.cancel(self: simgrid.Exec) simgrid.Exec
Cancel that execution.
- Exec.start(self: simgrid.Exec) simgrid.Exec
Start that execution.
- Exec.test(self: simgrid.Exec) bool
Test whether the execution is terminated.
- Exec.wait(self: simgrid.Exec) simgrid.Exec
Block until the completion of that execution.
Suspending and resuming an execution
-
virtual Activity *simgrid::s4u::Exec::suspend()
Blocks the progression of this activity until it gets resumed
- Exec.suspend(self: simgrid.Exec) simgrid.Activity
Suspend that execution.
- Exec.resume(self: simgrid.Exec) simgrid.Activity
Resume that execution.
- Exec.is_suspended
Whether this Exec is suspended
Signals
-
static inline void simgrid::s4u::Exec::on_start_cb(const std::function<void(Exec const&)> &cb)
Add a callback fired when any activity starts (no veto)
-
inline void simgrid::s4u::Exec::on_this_start_cb(const std::function<void(Exec const&)> &cb)
Add a callback fired when this specific activity starts (no veto)
-
static inline void simgrid::s4u::Exec::on_completion_cb(const std::function<void(Exec const&)> &cb)
Add a callback fired when any activity completes (either normally, cancelled or failed)
-
inline void simgrid::s4u::Exec::on_this_completion_cb(const std::function<void(Exec const&)> &cb)
Add a callback fired when this specific activity completes (either normally, cancelled or failed)
Warning
doxygenfunction: Cannot find function “simgrid::s4u::Exec::on_suspended_cb” in doxygen xml output for project “simgrid” from directory: ../build/xml
Warning
doxygenfunction: Cannot find function “simgrid::s4u::Exec::on_resumed_cb” in doxygen xml output for project “simgrid” from directory: ../build/xml
class Io
- class simgrid.Io
I/O activities. See the C++ documentation for details.
Basic management
Querying info
Life cycle
- Io.test(self: simgrid.Io) bool
Test whether the I/O is terminated.
- Io.wait(self: simgrid.Io) simgrid.Io
Block until the completion of that I/O operation
Signals
-
static inline void simgrid::s4u::Io::on_start_cb(const std::function<void(Io const&)> &cb)
Add a callback fired when any activity starts (no veto)
-
inline void simgrid::s4u::Io::on_this_start_cb(const std::function<void(Io const&)> &cb)
Add a callback fired when this specific activity starts (no veto)
-
static inline void simgrid::s4u::Io::on_completion_cb(const std::function<void(Io const&)> &cb)
Add a callback fired when any activity completes (either normally, cancelled or failed)
-
inline void simgrid::s4u::Io::on_this_completion_cb(const std::function<void(Io const&)> &cb)
Add a callback fired when this specific activity completes (either normally, cancelled or failed)
Warning
doxygenfunction: Cannot find function “simgrid::s4u::Io::on_suspended_cb” in doxygen xml output for project “simgrid” from directory: ../build/xml
Warning
doxygenfunction: Cannot find function “simgrid::s4u::Io::on_resumed_cb” in doxygen xml output for project “simgrid” from directory: ../build/xml
class ActivitySet
-
class ActivitySet : public xbt::Extendable<ActivitySet>
ActivitiesSet.
This class is a container of activities, allowing to wait for the completion of any or all activities in the set. This is somehow similar to the select(2) system call under UNIX, allowing you to wait for the next event about these activities.
- class simgrid.ActivitySet
ActivitySet. See the C++ documentation for details.
Basic management
#include <simgrid/s4u/ActivitySet.hpp>
-
using simgrid::s4u::ActivitySetPtr = boost::intrusive_ptr<ActivitySet>
Smart pointer to a simgrid::s4u::Activity
from simgrid import ActivitySet
#include <simgrid/activity_set.h>
-
sg_activity_set_t sg_activity_set_init()
-
void sg_activity_set_delete(sg_activity_set_t as)
Managing activities
-
inline void simgrid::s4u::ActivitySet::push(ActivityPtr a)
Add an activity to the set
-
void simgrid::s4u::ActivitySet::erase(ActivityPtr a)
Remove that activity from the set (no-op if the activity is not in the set)
-
inline int simgrid::s4u::ActivitySet::empty() const
Return whether the set is empty. Failed activities (if any) are not counted
-
inline int simgrid::s4u::ActivitySet::size() const
Get the amount of activities in the set. Failed activities (if any) are not counted
- ActivitySet.push()
push(self: simgrid.ActivitySet, activity: simgrid.Activity) -> None
Add an activity to the set
- ActivitySet.erase()
erase(self: simgrid.ActivitySet, activity: simgrid.Activity) -> None
Remove that activity from the set
- ActivitySet.empty()
empty(self: simgrid.ActivitySet) -> int
Returns whether the set is empty
- ActivitySet.size()
Count of activities in the set
-
void sg_activity_set_push(sg_activity_set_t as, sg_activity_t acti)
-
void sg_activity_set_erase(sg_activity_set_t as, sg_activity_t acti)
-
int sg_activity_set_empty(sg_activity_set_t as)
-
size_t sg_activity_set_size(sg_activity_set_t as)
Interacting with the set
-
ActivityPtr simgrid::s4u::ActivitySet::test_any()
Returns the first terminated activity if any, or ActivityPtr(nullptr) if no activity is terminated
-
inline void simgrid::s4u::ActivitySet::wait_all()
Wait for the completion of all activities in the set. The set is NOT emptied afterward.
-
void simgrid::s4u::ActivitySet::wait_all_for(double timeout)
Wait for the completion of all activities in the set, but not longer than the provided timeout
On timeout, an exception is raised.
In any case, the completed activities remain in the set. Use test_any() to retrieve them.
-
inline ActivityPtr simgrid::s4u::ActivitySet::wait_any()
Wait for the completion of one activity from the set.
If an activity fails during that time, an exception is raised, and the failed exception is marked as failed in the set. Use get_failed_activity() to retrieve it.
If more than one activity failed, the other ones are also removed from the set. Use get_failed_activity() several time to retrieve them all.
- Returns:
the first terminated activity, which is automatically removed from the set. If more than one activity terminated at the same timestamp, then the other ones are still in the set. Use either test_any() or wait_any() to retrieve the other ones.
-
ActivityPtr simgrid::s4u::ActivitySet::wait_any_for(double timeout)
Wait for the completion of one activity from the set, but not longer than the provided timeout.
See wait_any() for details.
- Returns:
the first terminated activity, which is automatically removed from the set.
- ActivitySet.test_any()
test_any(self: simgrid.ActivitySet) -> simgrid.Activity
Returns the first terminated activity if any, or None if no activity is terminated
- ActivitySet.wait_all()
wait_all(self: simgrid.ActivitySet) -> None
Wait for the completion of all activities in the set, endlessly
- ActivitySet.wait_all_for()
wait_all_for(self: simgrid.ActivitySet, timeout: float) -> None
Wait for the completion of all activities in the set, but not longer than the provided timeout
- ActivitySet.wait_any()
wait_any(self: simgrid.ActivitySet) -> simgrid.Activity
Wait for the completion of one activity in the set, endlessly
- ActivitySet.wait_any_for()
wait_any_for(self: simgrid.ActivitySet, timeout: float) -> simgrid.Activity
Wait for the completion of one activity in the set, but not longer than the provided timeout
-
sg_activity_t sg_activity_set_test_any(sg_activity_set_t as)
-
void sg_activity_set_wait_all(sg_activity_set_t as)
-
int sg_activity_set_wait_all_for(sg_activity_set_t as, double timeout)
Returns true if it terminated successfully (or false on timeout)
-
sg_activity_t sg_activity_set_wait_any(sg_activity_set_t as)
-
sg_activity_t sg_activity_set_wait_any_for(sg_activity_set_t as, double timeout)
-
void sg_activity_unref(sg_activity_t acti)
You must call this function manually on activities extracted from an activity_set with waitany and friends
Dealing with failed activities
Warning
doxygenfunction: Unable to resolve function “simgrid::s4u::ActivitySet::get_failed_activity” with arguments () const in doxygen xml output for project “simgrid” from directory: ../build/xml. Potential matches:
- ActivityPtr get_failed_activity()
Warning
doxygenfunction: Unable to resolve function “simgrid::s4u::ActivitySet::has_failed_activities” with arguments () in doxygen xml output for project “simgrid” from directory: ../build/xml. Potential matches:
- bool has_failed_activities() const
Tasks
class Task
-
class Task
Task class
Subclassed by simgrid::s4u::CommTask, simgrid::s4u::ExecTask, simgrid::s4u::IoTask
Known subclasses: Communication Tasks, Executions Tasks, I/O Tasks. See also the section on activities above.
Basic management
Querying info
-
inline const char *simgrid::s4u::Task::get_cname() const
Retrieves the name of that Task as a C string
-
inline const std::string &simgrid::s4u::Task::get_name() const
Retrieves the name of that Task as a C++ string
-
inline int simgrid::s4u::Task::get_count(const std::string &instance = "collector") const
- Returns:
Number of times this instance of this Task has been completed
-
inline double simgrid::s4u::Task::get_amount(const std::string &instance = "instance_0") const
- Returns:
Amout of work this instance of this Task has to process
-
inline int simgrid::s4u::Task::get_queued_firings(const std::string &instance = "instance_0") const
- Returns:
Amount of queued firings for this instance of this Task
-
inline int simgrid::s4u::Task::get_running_count(const std::string &instance = "instance_0") const
- Returns:
Amount currently running of this instance of this Task
Life cycle
-
void simgrid::s4u::Task::set_amount(double amount, std::string instance = "instance_0")
Note
In flops for ExecTasks instances and in bytes for CommTasks instances. In flops for dispatcher and collector instances
- Parameters:
amount – The new amount of work this instance of this Task has to do
Warning
doxygenfunction: Unable to resolve function “simgrid::s4u::Task::set_parallelism_degree” with arguments (int, std::string) in doxygen xml output for project “simgrid” from directory: ../build/xml. Potential matches:
- void set_parallelism_degree(int new_degree, const std::string &instance = "all")
Managing Dependencies
Managing Tokens
-
inline std::shared_ptr<Token> simgrid::s4u::Task::get_token_from(TaskPtr t) const
- Parameters:
t – A Smart pointer to a Task
- Returns:
Oldest token received by this Task that was sent by Task t
-
inline std::deque<std::shared_ptr<Token>> simgrid::s4u::Task::get_tokens_from(TaskPtr t) const
- Parameters:
t – A Smart pointer to a Task
- Returns:
All tokens received by this Task that were sent by Task t
-
void simgrid::s4u::Task::deque_token_from(TaskPtr t)
Pop the oldest token received by this Task that was sent by Task t.
- Parameters:
t – A Smart pointer to a Task
- Parameters:
token – The new token
Signals
-
static inline void simgrid::s4u::Task::on_start_cb(const std::function<void(Task*)> &cb)
Add a callback fired before a task activity starts. Triggered after the on_this_start function
-
inline void simgrid::s4u::Task::on_this_start_cb(const std::function<void(Task*)> &func)
Add a callback fired before this task activity starts
class CommTask
Basic management
Querying info
-
inline Host *simgrid::s4u::CommTask::get_source() const
- Returns:
A pointer to the source Host of this CommTask
-
inline Host *simgrid::s4u::CommTask::get_destination() const
- Returns:
A pointer to the destination Host of this CommTask
-
inline double simgrid::s4u::CommTask::get_bytes() const
- Returns:
The amout of bytes this CommTask has to send
-
CommTaskPtr simgrid::s4u::CommTask::set_source(Host *source)
- Parameters:
source – The new source Host of this CommTask
- Returns:
A Smart pointer to this CommTask
-
CommTaskPtr simgrid::s4u::CommTask::set_destination(Host *destination)
- Parameters:
destination – The new destination of this CommTask
- Returns:
A Smart pointer to the destination Host of this CommTask
-
CommTaskPtr simgrid::s4u::CommTask::set_bytes(double bytes)
- Parameters:
bytes – The amount of bytes this CommTask has to send
class ExecTask
Basic management
Querying info
-
inline Host *simgrid::s4u::ExecTask::get_host(std::string instance = "instance_0") const
- Returns:
A pointer to the host of this instance of this ExecTask
-
inline double simgrid::s4u::ExecTask::get_flops(std::string instance = "instance_0") const
- Returns:
The amount of flops this instance of this ExecTask has to execute
-
ExecTaskPtr simgrid::s4u::ExecTask::set_host(Host *host, std::string instance = "all")
- Parameters:
host – The new host of this instance of this ExecTask
- Returns:
a Smart pointer to this ExecTask
-
ExecTaskPtr simgrid::s4u::ExecTask::set_flops(double flops, std::string instance = "instance_0")
- Parameters:
flops – The new amount of flops this instance of this Task has to execute
- Returns:
A Smart pointer to this ExecTask
class IoTask
Basic management
Querying info
-
inline double simgrid::s4u::IoTask::get_bytes() const
- Returns:
The amount of bytes this IoTask has to write or read
-
inline Io::OpType simgrid::s4u::IoTask::get_op_type() const
- Returns:
The type of operation this IoTask has to to
-
IoTaskPtr simgrid::s4u::IoTask::set_disk(Disk *disk)
- Parameters:
disk – The new disk of this IoTask
- Returns:
A Smart pointer to this IoTask
Synchronization Objects
Mutex
-
class Mutex
A classical mutex, but blocking in the simulation world.
S4U mutexes are not recursive. If an actor tries to lock the same object twice, it deadlocks with itself.
It is strictly impossible to use a real mutex, such as std::mutex or pthread_mutex_t, because it would block the whole simulation. Instead, you should use the present class, that is a drop-in replacement of these mechanisms.
An example is available in Section Classical synchronization objects.
As for any S4U object, you can use the RAII idiom for memory management of Mutexes. Use
create()to get asimgrid::s4u::MutexPtrto a newly created mutex, and only manipulatesimgrid::s4u::MutexPtr.
- class simgrid.Mutex
A classical mutex, but blocking in the simulation world.See the C++ documentation for details.
Basic management
#include <simgrid/s4u/Mutex.hpp>
- using simgrid::s4u::MutexPtr = boost::intrusive_ptr<Mutex>
Smart pointer to a
simgrid::s4u::Mutexfrom simgrid import Mutex mutex = Mutex() # Use a context manager to acquire and automatically release the mutex # when leaving the scope. with mutex: # Access shared resource ... pass
- Mutex.__init__(self: simgrid.Mutex, recursive: bool = False) None
Mutex constructor (pass True as a parameter to get a recursive Mutex).
#include <simgrid/mutex.h>
- typedef s4u_Mutex *sg_mutex_t
- typedef const s4u_Mutex *const_sg_mutex_t
Pointer to a constant mutex object.
- sg_mutex_t sg_mutex_init()
- void sg_mutex_destroy(const_sg_mutex_t mutex)
Locking
- Mutex.lock(self: simgrid.Mutex) None
Block until the mutex is acquired.
- Mutex.try_lock(self: simgrid.Mutex) bool
Try to acquire the mutex. Return true if the mutex was acquired, false otherwise.
- Mutex.unlock(self: simgrid.Mutex) None
Release the mutex.
- void sg_mutex_lock(sg_mutex_t mutex)
- int sg_mutex_try_lock(sg_mutex_t mutex)
- void sg_mutex_unlock(sg_mutex_t mutex)
Barrier
#include <simgrid/s4u/Barrier.hpp>
-
using simgrid::s4u::BarrierPtr = boost::intrusive_ptr<Barrier>
Smart pointer to a simgrid::s4u::Barrier
-
static BarrierPtr simgrid::s4u::Barrier::create(unsigned int expected_actors)
Creates a barrier for the given amount of actors
from simgrid import Barrier
barrier = Barrier(2)
- Barrier.__init__(self: simgrid.Barrier, expected_actors: int) None
Barrier constructor.
- Barrier.wait(self: simgrid.Barrier) int
Blocks into the barrier. Every waiting actors will be unlocked once the expected amount of actors reaches the barrier.
Condition variable
-
class ConditionVariable
SimGrid’s condition variables are meant to be drop-in replacements of
std::condition_variable. Please refer to the documentation of standard C++ for more information on condition variables. A SimGrid example is available in Section Classical synchronization objects.
Basic management
#include <simgrid/s4u/ConditionVariable.hpp>
- using simgrid::s4u::ConditionVariablePtr = boost::intrusive_ptr<ConditionVariable>
Smart pointer to a
simgrid::s4u::ConditionVariable
- static ConditionVariablePtr simgrid::s4u::ConditionVariable::create()
Create a new condition variable and return a smart pointer
You should only manipulate
simgrid::s4u::ConditionVariablePtr, as created by this function (see also Memory Management).
Waiting and notifying
- void simgrid::s4u::ConditionVariable::notify_all()
Unblock all actors blocked on that condition variable. If none was blocked, nothing happens.
- void simgrid::s4u::ConditionVariable::notify_one()
Unblock one actor blocked on that condition variable. If none was blocked, nothing happens.
- void simgrid::s4u::ConditionVariable::wait(s4u::MutexPtr lock)
Wait until notification, with no timeout.
- void simgrid::s4u::ConditionVariable::wait(const std::unique_lock<s4u::Mutex> &lock)
Wait until notification, with no timeout.
- template<class P>
inline void simgrid::s4u::ConditionVariable::wait(const std::unique_lock<Mutex> &lock, P pred)
- std::cv_status simgrid::s4u::ConditionVariable::wait_for(const std::unique_lock<s4u::Mutex> &lock, double duration)
Wait for the given amount of seconds (specified as a plain double)
- template<class Rep, class Period>
inline std::cv_status simgrid::s4u::ConditionVariable::wait_for(const std::unique_lock<s4u::Mutex> &lock, std::chrono::duration<Rep, Period> duration)Wait for the given amount of seconds (specified in C++ style)
- template<class Duration>
inline std::cv_status simgrid::s4u::ConditionVariable::wait_until(const std::unique_lock<s4u::Mutex> &lock, const SimulationTimePoint<Duration> &timeout_time)Wait until the given instant (specified in C++ style)
- std::cv_status simgrid::s4u::ConditionVariable::wait_until(const std::unique_lock<s4u::Mutex> &lock, double timeout_time)
Wait until the given instant (specified as a plain double)
- void sg_cond_wait(sg_cond_t cond, sg_mutex_t mutex)
Blocks onto the given condition variable.
- int sg_cond_wait_for(sg_cond_t cond, sg_mutex_t mutex, double delay)
Blocks onto the given condition variable, but only for the given amount of time.
- Returns:
0 on success, 1 on timeout
Semaphore
-
class Semaphore
A classical semaphore, but blocking in the simulation world.
It is strictly impossible to use a real semaphore, such as sem_init, because it would block the whole simulation. Instead, you should use the present class, that offers a very similar interface.
An example is available in Section Classical synchronization objects.
As for any S4U object, you can use the RAII idiom for memory management of semaphores. Use
create()to get asimgrid::s4u::SemaphorePtrto a newly created semaphore, that will get automatically freed when the variable goes out of scope.
- class simgrid.Semaphore
A classical semaphore, but blocking in the simulation world. See the C++ documentation for details.
Basic management
#include <simgrid/s4u/Semaphore.hpp>
- using simgrid::s4u::SemaphorePtr = boost::intrusive_ptr<Semaphore>
Smart pointer to a simgrid::s4u::Semaphore
- static SemaphorePtr simgrid::s4u::Semaphore::create(unsigned int initial_capacity)
Constructs a new semaphore
from simgrid import Semaphore semaphore = Semaphore(1) # Automatically acquire the semaphore, and release it after leaving the scope. with semaphore: # Do something with the shared resource pass
- Semaphore.__init__(self: simgrid.Semaphore, capacity: int) None
Semaphore constructor.
Locking
- Semaphore.acquire(self: simgrid.Semaphore) None
Acquire on the semaphore object with no timeout. Blocks until the semaphore is acquired.
- Semaphore.acquire_timeout(self: simgrid.Semaphore, timeout: float) bool
Acquire on the semaphore object with no timeout. Blocks until the semaphore is acquired or return true if it has not been acquired after the specified timeout.
- Semaphore.capacity
Get the semaphore capacity.
- Semaphore.release(self: simgrid.Semaphore) None
Release the semaphore.
- Semaphore.would_block
Check whether trying to acquire the semaphore would block (in other word, checks whether this semaphore has capacity).
- int sg_sem_get_capacity(const_sg_sem_t sem)
- int sg_sem_would_block(const_sg_sem_t sem)
Error reporting
-
class Exception : public std::runtime_error
Ancestor class of all SimGrid exception
Subclassed by simgrid::AssertionError, simgrid::CancelException, simgrid::HostFailureException, simgrid::NetworkFailureException, simgrid::ParseError, simgrid::StorageFailureException, simgrid::TimeoutException, simgrid::TracingError, simgrid::VmFailureException
The following exceptions denote a problem in the simulated platform, and it is often useful to catch them.
-
class CancelException : public simgrid::Exception
Exception raised when something got canceled before completion
-
class NetworkFailureException : public simgrid::Exception
Exception raised when a communication fails because of the network or because of the remote host
The following errors denote a problem in the SimGrid tool itself. Most of the time, you should let these exception go, so that the simulation stops. But you may want to catch them, for example when you launch SimGrid from a python notebook and want to handle the problem accordingly.
The following exceptions denote a problem in the simulated platform, and it is often useful to catch them.
- class simgrid.CancelException
- class simgrid.HostFailureException
- class simgrid.NetworkFailureException
- class simgrid.StorageFailureException
- class simgrid.TimeoutException
- class simgrid.VmFailureException
The following errors denote a problem in the SimGrid tool itself. Most of the time, you should let these exception go, so that the simulation stops. But you may want to catch them, for example when you launch SimGrid from a python notebook and want to handle the problem accordingly.
- class simgrid.AssertionError
-
enum sg_error_t
Values:
-
enumerator SG_OK
Code returned when no problem occured
-
enumerator SG_ERROR_CANCELED
Code returned when something got canceled before completion
-
enumerator SG_ERROR_TIMEOUT
Code returned when timeout elapsed
-
enumerator SG_ERROR_HOST
Code returned when a host fails
-
enumerator SG_ERROR_NETWORK
Code returned when a communication fails because of the network or because of the remote host
-
enumerator SG_ERROR_STORAGE
Code returned when a storage fails
-
enumerator SG_ERROR_VM
Code returned when a VM fails
-
enumerator SG_OK