.. documentation, but it should remain readable directly.
-S4U Examples
-************
+Examples
+********
SimGrid comes with an extensive set of examples, documented on this
page. Most of them only demonstrate one single feature, with some
of the provided examples to constitute the skeleton of what you plan
to simulate.
+.. _s4u_ex_actors:
+
===========================
Actors: the Active Entities
===========================
-.. _s4u_ex_actors:
-
-Starting and Stoping Actors
+Starting and Stopping Actors
---------------------------
- **Creating actors:**
Most actors are started from the deployment XML file, because this
- is a :ref:`better scientific habbit <howto_science>`, but you can
+ is a :ref:`better scientific habit <howto_science>`, but you can
also create them directly from your code.
.. tabs::
- Directly with :py:func:`simgrid.Actor.create()`
- From XML with :py:func:`simgrid.Engine.register_actor()` and then :py:func:`simgrid.Engine.load_deployment()`
+ .. example-tab:: examples/c/actor-create/actor-create.c
+
+ You create actors either:
+
+ - Directly with :cpp:func:`sg_actor_create()` followed by :cpp:func:`sg_actor_start`.
+ - From XML with :cpp:func:`simgrid_register_function` and then :cpp:func:`simgrid_load_deployment`.
+
.. example-tab:: examples/python/actor-create/actor-create_d.xml
The following file is used in both C++ and Python.
- the end of any actor: :cpp:member:`simgrid::s4u::Actor::on_termination()`
- the destruction of any actor: :cpp:member:`simgrid::s4u::Actor::on_destruction()`
+ .. example-tab:: examples/c/actor-exiting/actor-exiting.c
+
+ This example shows how to attach a callback to the end of a specific actor with
+ :cpp:func:`sg_actor_on_exit()`.
+
- **Kill actors:**
Actors can forcefully stop other actors.
-
+
.. tabs::
-
+
.. example-tab:: examples/s4u/actor-kill/s4u-actor-kill.cpp
-
+
See also :cpp:func:`void simgrid::s4u::Actor::kill(void)`, :cpp:func:`void simgrid::s4u::Actor::kill_all()`,
- :cpp:func:`simgrid::s4u::this_actor::exit`.
+ :cpp:func:`simgrid::s4u::this_actor::exit`, :cpp:func:`simgrid::s4u::this_actor::on_exit`.
.. example-tab:: examples/python/actor-kill/actor-kill.py
- See also :py:func:`simgrid.Actor.kill`, :py:func:`simgrid.Actor.kill_all`, :py:func:`simgrid.this_actor.exit`.
+ See also :py:func:`simgrid.Actor.kill`, :py:func:`simgrid.Actor.kill_all`, :py:func:`simgrid.this_actor.exit`,
+ :py:func:`simgrid.this_actor.on_exit`.
+
+ .. example-tab:: examples/c/actor-kill/actor-kill.c
+
+ See also :cpp:func:`sg_actor_kill`, :cpp:func:`sg_actor_kill_all`, :cpp:func:`sg_actor_exit`, :cpp:func:`sg_actor_on_exit`.
- - **Controling the actor life cycle from the XML:**
+ - **Controlling the actor life cycle from the XML:**
You can specify a start time and a kill time in the deployment file.
.. tabs::
This demonstrates the ``start_time`` and ``kill_time`` attribute of the :ref:`pf_tag_actor` tag.
+ .. example-tab:: examples/python/actor-lifetime/actor-lifetime.py
+
+ This file is not really interesting: the important matter is in the XML file.
+
+ .. example-tab:: examples/c/actor-lifetime/actor-lifetime.c
+
+ This file is not really interesting: the important matter is in the XML file.
+
- **Daemonize actors:**
Some actors may be intended to simulate daemons that run in background. This example show how to transform a regular
actor into a daemon that will be automatically killed once the simulation is over.
See also :py:func:`simgrid.Actor.daemonize()` and :py:func:`simgrid.Actor.is_daemon()`.
+ .. example-tab:: examples/c/actor-daemon/actor-daemon.c
+
+ See also :cpp:func:`sg_actor_daemonize` and :cpp:func:`sg_actor_is_daemon`.
+
+ - **Specify the stack size to use**
+ The stack size can be specified by default on the command line,
+ globally by changing the configuration with :cpp:func:`simgrid::s4u::Engine::set_config(std::string)`,
+ or for a specific actor using :cpp:func:`simgrid::s4u::Actor::set_stacksize` before its start.
+
+ .. tabs::
+
+ .. example-tab:: examples/s4u/actor-stacksize/s4u-actor-stacksize.cpp
+
+ .. example-tab:: examples/c/actor-stacksize/actor-stacksize.c
+
Inter-Actors Interactions
-------------------------
.. example-tab:: examples/s4u/actor-suspend/s4u-actor-suspend.cpp
See also :cpp:func:`simgrid::s4u::this_actor::suspend()`,
- :cpp:func:`simgrid::s4u::Actor::suspend()`, :cpp:func:`simgrid::s4u::Actor::resume()` and
+ :cpp:func:`simgrid::s4u::Actor::suspend()`, :cpp:func:`simgrid::s4u::Actor::resume()`, and
:cpp:func:`simgrid::s4u::Actor::is_suspended()`.
.. example-tab:: examples/python/actor-suspend/actor-suspend.py
See also :py:func:`simgrid.this_actor.suspend()`,
- :py:func:`simgrid.Actor.suspend()`, :py:func:`simgrid.Actor.resume()` and
+ :py:func:`simgrid.Actor.suspend()`, :py:func:`simgrid.Actor.resume()`, and
:py:func:`simgrid.Actor.is_suspended()`.
+ .. example-tab:: examples/c/actor-suspend/actor-suspend.c
+
+ See also :cpp:func:`sg_actor_suspend()`, :cpp:func:`sg_actor_resume()`, and
+ :cpp:func:`sg_actor_is_suspended()`.
+
- **Migrating Actors:**
- Actors can move or be moved from a host to another very easily.
+ Actors can move or be moved from a host to another very easily. It amount to setting them on a new host.
.. tabs::
.. example-tab:: examples/s4u/actor-migrate/s4u-actor-migrate.cpp
- See also :cpp:func:`simgrid::s4u::this_actor::migrate()` and :cpp:func:`simgrid::s4u::Actor::migrate()`.
+ See also :cpp:func:`simgrid::s4u::this_actor::set_host()` and :cpp:func:`simgrid::s4u::Actor::set_host()`.
.. example-tab:: examples/python/actor-migrate/actor-migrate.py
- See also :py:func:`simgrid.this_actor.migrate()` and :py:func:`simgrid.Actor.migrate()`.
+ See also :py:func:`simgrid.this_actor.set_host()` and :py:func:`simgrid.Actor.set_host()`.
+
+ .. example-tab:: examples/c/actor-migrate/actor-migrate.c
+
+ See also :cpp:func:`sg_actor_set_host()`.
- **Waiting for the termination of an actor:** (joining on it)
You can block the current actor until the end of another actor.
See also :py:func:`simgrid.Actor.join()`.
+ .. example-tab:: examples/c/actor-join/actor-join.c
+
+ See also :cpp:func:`sg_actor_join`.
+
- **Yielding to other actors**.
The ```yield()``` function interrupts the execution of the current
actor, leaving a chance to the other actors that are ready to run
See also :py:func:`simgrid.this_actor.yield_()`.
+ .. example-tab:: examples/c/actor-yield/actor-yield.c
+
+ See also :cpp:func:`sg_actor_yield()`.
+
Traces Replay as a Workload
---------------------------
See also :py:func:`simgrid.Mailbox.put_async()` and :py:func:`simgrid.Comm.wait()`.
+ .. example-tab:: examples/c/async-wait/async-wait.c
+
+ See also :cpp:func:`sg_mailbox_put_async()` and :cpp:func:`sg_comm__wait()`.
+
- **Waiting for all communications in a set:**
The ``wait_all()`` function is useful when you want to block until
all activities in a given set have completed.
See also :py:func:`simgrid.Comm.wait_all()`.
+ .. example-tab:: examples/c/async-waitall/async-waitall.c
+
+ See also :cpp:func:`sg_comm_wait_all()`.
+
- **Waiting for the first completed communication in a set:**
The ``wait_any()`` function is useful
when you want to block until one activity of the set completes, no
.. example-tab:: examples/python/async-waitany/async-waitany.py
See also :py:func:`simgrid.Comm.wait_any()`.
+
+ .. example-tab:: examples/c/async-waitany/async-waitany.c
+
+ See also :cpp:func:`sg_comm_wait_any`.
.. _s4u_ex_execution:
See also :py:func:`simgrid.this_actor.execute()`.
+ .. example-tab:: examples/c/exec-basic/exec-basic.c
+
+ See also :cpp:func:`void sg_actor_execute(double)`
+ and :cpp:func:`void sg_actor_execute_with_priority(double, double)`.
+
- **Asynchronous execution:**
You can start asynchronous executions, just like you would fire
background threads.
:py:func:`simgrid.Exec.get_remaining_ratio()`,
:py:func:`simgrid.this_actor.exec_async()` and
:py:func:`simgrid.Activity.cancel()`.
-
+
+ .. example-tab:: examples/c/exec-async/exec-async.c
+
+ See also :cpp:func:`sg_actor_exec_init()`,
+ :cpp:func:`sg_exec_start()`,
+ :cpp:func:`sg_exec_wait()`,
+ :cpp:func:`sg_exec_get_remaining()`,
+ :cpp:func:`sg_exec_get_remaining_ratio()`,
+ :cpp:func:`sg_actor_exec_async()` and
+ :cpp:func:`sg_exec_cancel()`,
+
- **Remote execution:**
You can start executions on remote hosts, or even change the host
on which they occur during their execution.
See also :py:func:`simgrid.Exec.set_host()`.
+ .. example-tab:: examples/c/exec-remote/exec-remote.c
+
+ See also :cpp:func:`sg_exec_set_host()`.
+
- **Parallel executions:**
These objects are convenient abstractions of parallel
computational kernels that span over several machines, such as a
See also :cpp:func:`simgrid::s4u::Host::get_pstate_speed` and :cpp:func:`simgrid::s4u::Host::set_pstate`.
+ .. example-tab:: examples/c/exec-dvfs/exec-dvfs.c
+
+ See also :cpp:func:`sg_host_get_pstate_speed` and :cpp:func:`sg_host_set_pstate`.
+
.. example-tab:: examples/python/exec-dvfs/exec-dvfs.py
See also :py:func:`Host.get_pstate_speed` and :py:func:`Host.set_pstate`.
.. example-tab:: examples/platforms/energy_platform.xml
+.. _s4u_ex_disk_io:
+
I/O on Disks and Files
----------------------
.. example-tab:: examples/s4u/io-disk-raw/s4u-io-disk-raw.cpp
+ .. example-tab:: examples/c/io-disk-raw/io-disk-raw.c
+
.. example-tab:: examples/platforms/hosts_with_disks.xml
This shows how to declare disks in XML.
.. example-tab:: examples/s4u/io-file-remote/s4u-io-file-remote.cpp
+ .. example-tab:: examples/c/io-file-remote/io-file-remote.c
+
.. _s4u_ex_IPC:
Classical synchronization objects
---------------------------------
- - **Mutex:**
- Shows how to use simgrid::s4u::Mutex synchronization objects.
+ - **Barrier:**
+ Shows how to use :cpp:type:`simgrid::s4u::Barrier` synchronization objects.
.. tabs::
- .. example-tab:: examples/s4u/synchro-mutex/s4u-synchro-mutex.cpp
+ .. example-tab:: examples/s4u/synchro-barrier/s4u-synchro-barrier.cpp
- - **Barrier:**
- Shows how to use simgrid::s4u::Barrier synchronization objects.
+ - **Condition variable:**
+ Shows how to use :cpp:type:`simgrid::s4u::ConditionVariable` synchronization objects.
.. tabs::
- .. example-tab:: examples/s4u/synchro-barrier/s4u-synchro-barrier.cpp
+ .. example-tab:: examples/s4u/synchro-condition-variable/s4u-synchro-condition-variable.cpp
+
+ - **Mutex:**
+ Shows how to use :cpp:type:`simgrid::s4u::Mutex` synchronization objects.
+
+ .. tabs::
+
+ .. example-tab:: examples/s4u/synchro-mutex/s4u-synchro-mutex.cpp
- **Semaphore:**
- Shows how to use simgrid::s4u::Semaphore synchronization objects.
+ Shows how to use :cpp:type:`simgrid::s4u::Semaphore` synchronization objects.
.. tabs::
- :cpp:func:`simgrid::s4u::Link::get_property()` and :cpp:func:`simgrid::s4u::Link::set_property()`
- :cpp:func:`simgrid::s4u::NetZone::get_property()` and :cpp:func:`simgrid::s4u::NetZone::set_property()`
+ .. example-tab:: examples/c/platform-properties/platform-properties.c
+
+ - :cpp:func:`sg_actor_get_property()` and :cpp:func:`sg_actor_set_property()`
+ - :cpp:func:`sg_host_get_property()` and :cpp:func:sg_host_set_property()`
+ - :cpp:func:`sg_link_get_property()` and :cpp:func:`sg_link_set_property()`
+ - :cpp:func:`sg_link_get_property()` and :cpp:func:`sg_link_set_property()`
+
.. group-tab:: XML
**Deployment file:**
.. example-tab:: examples/s4u/platform-failures/s4u-platform-failures.cpp
+ .. example-tab:: examples/c/platform-failures/platform-failures.c
+
.. group-tab:: XML
.. showfile:: examples/platforms/small_platform_failures.xml
.. example-tab:: examples/s4u/energy-exec/s4u-energy-exec.cpp
+ .. example-tab:: examples/c/energy-exec/energy-exec.c
+
- **Consumption due to the network:**
This example shows how to retrieve and display the energy consumed
by the network during communications.
- **Platform Tracing:**
This program is a toy example just loading the platform, so that
- you can play with the platform visualization. Recommanded options:
+ you can play with the platform visualization. Recommended options:
``--cfg=tracing:yes --cfg=tracing/categorized:yes``
.. tabs::
.. example-tab:: examples/s4u/app-pingpong/s4u-app-pingpong.cpp
+ .. example-tab:: examples/c/app-pingpong/app-pingpong.c
+
- **Token ring:**
Shows how to implement a classical communication pattern, where a
token is exchanged along a ring to reach every participant.
.. example-tab:: examples/s4u/app-token-ring/s4u-app-token-ring.cpp
+ .. example-tab:: examples/c/app-token-ring/app-token-ring.c
+
- **Master Workers:**
Another good old example, where one Master process has a bunch of task to dispatch to a set of several Worker
processes.
.. showfile:: examples/s4u/app-masterworkers/s4u-app-masterworkers-fun.cpp
:language: cpp
+
+ .. group-tab:: C
+
+ .. showfile:: examples/c/app-masterworker/app-masterworker.c
+ :language: cpp
Data diffusion
--------------
.. showfile:: examples/s4u/app-bittorrent/s4u-tracker.cpp
:language: cpp
+ .. group-tab:: C
+
+ .. showfile:: examples/c/app-bittorrent/app-bittorrent.c
+ :language: cpp
+
+ .. showfile:: examples/c/app-bittorrent/bittorrent-peer.c
+ :language: cpp
+
+ .. showfile:: examples/c/app-bittorrent/tracker.c
+ :language: cpp
+
- **Chained Send:**
Data broadcast over a ring of processes.
.. example-tab:: examples/s4u/app-chainsend/s4u-app-chainsend.cpp
+ .. group-tab:: C
+
+ .. showfile:: examples/c/app-chainsend/chainsend.c
+ :language: c
+
+ .. showfile:: examples/c/app-chainsend/broadcaster.c
+ :language: c
+
+ .. showfile:: examples/c/app-chainsend/peer.c
+ :language: c
+
Distributed Hash Tables (DHT)
-----------------------------
.. showfile:: examples/s4u/dht-kademlia/node.cpp
:language: cpp
+ .. group-tab:: C
+
+ .. showfile:: examples/c/dht-kademlia/dht-kademlia.c
+ :language: cpp
+
+ .. showfile:: examples/c/dht-kademlia/routing_table.c
+ :language: cpp
+
+ .. showfile:: examples/c/dht-kademlia/answer.c
+ :language: cpp
+
+ .. showfile:: examples/c/dht-kademlia/message.c
+ :language: cpp
+
+ .. showfile:: examples/c/dht-kademlia/node.c
+ :language: cpp
+
.. _s4u_ex_clouds:
Simulating Clouds
.. example-tab:: examples/s4u/cloud-simple/s4u-cloud-simple.cpp
+ .. example-tab:: examples/c/cloud-simple/cloud-simple.c
+
- **Migrating VMs**
This example shows how to migrate VMs between PMs.
.. example-tab:: examples/s4u/cloud-migration/s4u-cloud-migration.cpp
+ .. example-tab:: examples/c/cloud-migration/cloud-migration.c
+
+=======================
+Model-Related Examples
+=======================
+
+ - **ns-3 as a SimGrid Network Model**
+ This simple ping-pong example demonstrates how to use the bindings to the Network
+ Simulator. The most interesting is probably not the C++ files since
+ they are unchanged from the other simulations, but the associated files,
+ such as the platform file to see how to declare a platform to be used
+ with the ns-3 bindings of SimGrid and the tesh file to see how to actually
+ start a simulation in these settings.
+
+ .. tabs::
+
+ .. example-tab:: examples/s4u/network-ns3/s4u-network-ns3.cpp
+
+ .. group-tab:: XML
+
+ **Platform files:**
+
+ .. showfile:: examples/platforms/small_platform_one_link_routes.xml
+ :language: xml
+
=======================
Model-Checking Examples
=======================
