X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/5089a0a98b27f5eeee62321dff4f025f1648f025..1738c10ed9593cdd280ec4d911902cd282fb5317:/examples/README.rst diff --git a/examples/README.rst b/examples/README.rst index ecd2ab421a..0b74ab5ae0 100644 --- a/examples/README.rst +++ b/examples/README.rst @@ -28,12 +28,12 @@ to simulate. Actors: the Active Entities =========================== -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 `, but you can + is a :ref:`better scientific habit `, but you can also create them directly from your code. .. tabs:: @@ -54,6 +54,13 @@ Starting and Stoping Actors - 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. @@ -75,21 +82,31 @@ Starting and Stoping Actors - 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 - - **Controling the actor life cycle from the XML:** + See also :cpp:func:`sg_actor_kill`, :cpp:func:`sg_actor_kill_all`, :cpp:func:`sg_actor_exit`, :cpp:func:`sg_actor_on_exit`. + + - **Controlling the actor life cycle from the XML:** You can specify a start time and a kill time in the deployment file. .. tabs:: @@ -102,6 +119,14 @@ Starting and Stoping Actors 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. @@ -116,6 +141,21 @@ Starting and Stoping Actors 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`, + 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 ------------------------- @@ -131,27 +171,36 @@ synchronization objects `. .. 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. @@ -166,6 +215,10 @@ synchronization objects `. 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 @@ -181,6 +234,10 @@ synchronization objects `. 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 --------------------------- @@ -232,28 +289,51 @@ Communications on the Network .. tabs:: - .. example-tab:: examples/s4u/async-wait/s4u-async-wait.cpp + .. example-tab:: examples/s4u/comm-wait/s4u-comm-wait.cpp See also :cpp:func:`simgrid::s4u::Mailbox::put_async()` and :cpp:func:`simgrid::s4u::Comm::wait()`. - .. example-tab:: examples/python/async-wait/async-wait.py + .. example-tab:: examples/python/comm-wait/comm-wait.py See also :py:func:`simgrid.Mailbox.put_async()` and :py:func:`simgrid.Comm.wait()`. + .. example-tab:: examples/c/comm-wait/comm-wait.c + + See also :cpp:func:`sg_mailbox_put_async()` and :cpp:func:`sg_comm__wait()`. + + - **Suspending communications:** + The ``suspend()`` and ``resume()`` functions allow to block the + progression of a given communication for a while and then unblock it. + ``is_suspended()`` can be used to retrieve whether the activity is + currently blocked or not. + + .. tabs:: + + .. example-tab:: examples/s4u/comm-suspend/s4u-comm-suspend.cpp + + See also :cpp:func:`simgrid::s4u::Activity::suspend()` + :cpp:func:`simgrid::s4u::Activity::resume()` and + :cpp:func:`simgrid::s4u::Activity::is_suspended()`. + + - **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. .. tabs:: - .. example-tab:: examples/s4u/async-waitall/s4u-async-waitall.cpp + .. example-tab:: examples/s4u/comm-waitall/s4u-comm-waitall.cpp See also :cpp:func:`simgrid::s4u::Comm::wait_all()`. - .. example-tab:: examples/python/async-waitall/async-waitall.py + .. example-tab:: examples/python/comm-waitall/comm-waitall.py See also :py:func:`simgrid.Comm.wait_all()`. + .. example-tab:: examples/c/comm-waitall/comm-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 @@ -261,13 +341,17 @@ Communications on the Network .. tabs:: - .. example-tab:: examples/s4u/async-waitany/s4u-async-waitany.cpp + .. example-tab:: examples/s4u/comm-waitany/s4u-comm-waitany.cpp See also :cpp:func:`simgrid::s4u::Comm::wait_any()`. - .. example-tab:: examples/python/async-waitany/async-waitany.py + .. example-tab:: examples/python/comm-waitany/comm-waitany.py See also :py:func:`simgrid.Comm.wait_any()`. + + .. example-tab:: examples/c/comm-waitany/comm-waitany.c + + See also :cpp:func:`sg_comm_wait_any`. .. _s4u_ex_execution: @@ -292,6 +376,11 @@ Executions on the CPU 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. @@ -317,7 +406,17 @@ Executions on the CPU :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. @@ -332,11 +431,22 @@ Executions on the CPU 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 PDGEM and the other ScaLAPACK routines. Note that this only works with the "ptask_L07" host model (``--cfg=host/model:ptask_L07``). + + This example demonstrates several kind of parallel tasks: regular + ones, communication-only (without computation), computation-only + (without communication), synchronization-only (neither + communication nor computation). It also shows how to reconfigure a + task after its start, to change the amount of hosts it runs onto. + This allows to simulate malleable tasks. .. tabs:: @@ -346,7 +456,7 @@ Executions on the CPU - **Using Pstates on a host:** This example shows how define a set of pstates in the XML. The current pstate - of an host can then be accessed and changed from the program. + of a host can then be accessed and changed from the program. .. tabs:: @@ -354,12 +464,18 @@ Executions on the CPU 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 ---------------------- @@ -375,6 +491,8 @@ write actions on the disk resources. .. 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. @@ -400,27 +518,36 @@ result in short reads and short write, as in reality. .. 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:: @@ -446,6 +573,13 @@ Interacting with the Platform - :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:** @@ -481,6 +615,8 @@ Interacting with the Platform .. 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 @@ -515,14 +651,22 @@ Energy Simulation ================= - **Describing the energy profiles in the platform:** - This platform file contains the energy profile of each links and - hosts, which is necessary to get energy consumption predictions. - As usual, you should not trust our example, and you should strive - to double-check that your instantiation matches your target platform. + The first platform file contains the energy profile of each links and + hosts for a wired network, which is necessary to get energy consumption + predictions. The second platform file is the equivalent for a wireless + network. As usual, you should not trust our example, and you should + strive to double-check that your instantiation matches your target + platform. .. tabs:: - .. example-tab:: examples/platforms/energy_platform.xml + .. group-tab:: XML + + .. showfile:: examples/platforms/energy_platform.xml + :language: xml + + .. showfile:: examples/platforms/wifi_energy.xml + :language: xml - **Consumption due to the CPU:** This example shows how to retrieve the amount of energy consumed @@ -532,14 +676,24 @@ Energy Simulation .. example-tab:: examples/s4u/energy-exec/s4u-energy-exec.cpp - - **Consumption due to the network:** + .. example-tab:: examples/c/energy-exec/energy-exec.c + + - **Consumption due to the wired network:** This example shows how to retrieve and display the energy consumed - by the network during communications. + by the wired network during communications. .. tabs:: .. example-tab:: examples/s4u/energy-link/s4u-energy-link.cpp + - **Consumption due to the wireless network:** + This example shows how to retrieve and display the energy consumed + by the wireless network during communications. + + .. tabs:: + + .. example-tab:: examples/s4u/energy-wifi/s4u-energy-wifi.cpp + - **Modeling the shutdown and boot of hosts:** Simple example of model of model for the energy consumption during the host boot and shutdown periods. @@ -563,7 +717,7 @@ options to see the task executions: - **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:: @@ -586,6 +740,8 @@ than the previous examples. .. 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. @@ -594,6 +750,8 @@ than the previous examples. .. 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. @@ -613,6 +771,11 @@ than the previous examples. .. 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 -------------- @@ -633,6 +796,17 @@ 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. @@ -640,6 +814,17 @@ Data diffusion .. 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) ----------------------------- @@ -675,6 +860,23 @@ 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 @@ -688,6 +890,8 @@ 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. @@ -695,6 +899,88 @@ Simulating Clouds .. 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 + + - **wifi links** + + This demonstrates how to declare a wifi link in your platform and + how to use it in your simulation. The basics is to have a link + which sharing policy is set to `WIFI`. Such links can have more + than one bandwidth value (separated by commas), corresponding to + the several SNR level of your wifi link. + + In this case, SimGrid automatically switches to validated + performance models of wifi networks, where the time is shared + between users instead of the bandwidth for wired links (the + corresponding publication is currently being written). + + If your wifi link provides more than one SNR level, you can switch + the level of a given host using + :cpp:func:`simgrid::s4u::Link::set_host_wifi_rate`. By default, + the first level is used. + + .. tabs:: + + .. example-tab:: examples/s4u/network-wifi/s4u-network-wifi.cpp + + .. group-tab:: XML + + **Platform files:** + + .. showfile:: examples/platforms/wifi.xml + :language: xml + +=============== +Plugin Examples +=============== + +It is possible to extend SimGrid without modifying its internals by +attaching code to the existing signals and by adding extra data to the +simulation objects through extensions. How to do that is not exactly +documented yet, and you should look for examples in the src/plugins +directory. + +This section documents how the existing plugins can be used. Remember +that you are very welcome to modify the plugins to fit your needs. It +should be much easier than modifying the SimGrid kernel. + + - **Monitoring the host load** + + .. tabs:: + + .. example-tab:: examples/s4u/plugin-host-load/s4u-plugin-host-load.cpp + + .. example-tab:: examples/c/plugin-host-load/plugin-host-load.c + + - **Monitoring the link load** + + .. tabs:: + + .. example-tab:: examples/s4u/plugin-link-load/s4u-plugin-link-load.cpp + ======================= Model-Checking Examples =======================