@top_srcdir@/include/gras \
@top_srcdir@/include/amok \
@top_srcdir@/include/xbt \
- @top_srcdir@/include/simdag \
+ @top_srcdir@/include/simdag \
@top_srcdir@/src/include/surf \
@top_srcdir@/src/xbt/ \
@top_srcdir@/src/xbt/datadesc \
@top_srcdir@/src/amok/PeerManagement \
@top_srcdir@/src/simdag
+###################################################
+## PLEASE DON'T MESS WITH THE ORDER OF EXAMPLES ## (unless you know what you are doing, of course)
+###################################################
+
+INPUT += @top_srcdir@/examples/msg/sendrecv/sendrecv.c \
+ @top_srcdir@/examples/msg/masterslave/masterslave_forwarder.c \
+ @top_srcdir@/examples/msg/masterslave/masterslave_console.c \
+ @top_srcdir@/examples/msg/migration \
+ @top_srcdir@/examples/msg/suspend \
+ @top_srcdir@/examples/msg/properties \
+ @top_srcdir@/examples/msg/parallel_task \
+ @top_srcdir@/examples/msg/priority \
+ @top_srcdir@/examples/msg/icomms/peer.c \
+ @top_srcdir@/examples/msg/icomms/peer2.c \
+ @top_srcdir@/examples/msg/icomms/peer3.c \
+ @top_srcdir@/examples/msg/tracing/simple.c \
+ @top_srcdir@/examples/msg/tracing/ms.c \
+ @top_srcdir@/examples/msg/tracing/categories.c \
+ @top_srcdir@/examples/msg/tracing/procmig.c \
+ @top_srcdir@/examples/msg/tracing/trace_platform.c \
+ @top_srcdir@/examples/msg/tracing/user_variables.c \
+ @top_srcdir@/examples/msg/ns3 \
+ @top_srcdir@/examples/msg/gtnets \
+ @top_srcdir@/examples/msg/io \
+ @top_srcdir@/examples/msg/gpu \
+ @top_srcdir@/examples/msg/actions \
+ @top_srcdir@/examples/msg/token_ring \
+ @top_srcdir@/examples/msg/pmm \
+ @top_srcdir@/examples/msg/chord \
+
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
# also the default input encoding. Doxygen uses libiconv (or the iconv built
- \ref msg_easier_life
- \ref msg_simulation
- \section MSG_examples Examples of MSG
-
- - \ref MSG_ex_master_slave
- - \ref MSG_ex_asynchronous_communications
- - \ref MSG_ex_master_slave_scrip_lua
+ Also make sure to visit the page @ref MSG_examples.
*/
@htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Simulation functions" --> @endhtmlonly
*/
+
+
+/**
+@defgroup MSG_examples MSG Examples
+@ingroup MSG_API
+MSG comes with an extensive set of examples. It is sometimes difficult
+to find the one you need.
+
+@section MSG_ex_basics Basic examples and features
+
+*/
+
/**
@defgroup MSG_LUA Lua bindings
@ingroup MSG_API
- \ref MSG_ex_master_slave_lua
- \ref MSG_ex_master_slave_lua_bypass
- - Also, the Chord example (in the source tree) is a working
- non-trivial example of use of the lua bindings
+ - Also, the lua version of the Chord example (in the source tree)
+ is a working non-trivial example of use of the lua bindings
*/
-/** \page MSG_ex_asynchronous_communications Asynchronous communication applications
+/** \defgroup MSG_ex_asynchronous_communications Asynchronous communications
+ \ingroup MSG_examples
Simulation of asynchronous communications between a sender and a receiver using a realistic platform and
an external description of the deployment.
*/
-/** \page MSG_ex_master_slave_scrip_lua Master/slave application using lua console
-
- Simulation of a master-slave application using a realistic platform and
- an external description of the deployment via a lua script.
-
- \section MSG_ex_msl_TOC Table of contents:
-
- - \ref MSG_ext_msl_code
- - \ref MSG_ext_msl_preliminary
- - \ref MSG_ext_msl_master
- - \ref MSG_ext_msl_slave
- - \ref MSG_ext_msl_core
- - \ref MSG_ext_msl_main
- - \ref MSG_ext_msl_helping
- - \ref MSG_ext_msl_platform
-
-<hr>
-
- \dontinclude msg/masterslave/masterslave_console.c
-
- \section MSG_ext_msl_code Code of the application
-
- \subsection MSG_ext_msl_preliminary Preliminary declarations
-
- \skip include
- \until } channel_t;
-
- \subsection MSG_ext_msl_master Master code
-
- This function has to be assigned to a m_process_t that will behave as the master.
- It should not be called directly but either given as a parameter to
- #MSG_process_create() or registered as a public function through
- #MSG_function_register() and then automatically assigned to a process through
- #MSG_load_platform_script().
-
- C style arguments (argc/argv) are interpreted as:
- - the number of tasks to distribute
- - the computation size of each task
- - the size of the files associated to each task
- - number of hosts that will accept those tasks.
-
- Tasks are dumbly sent in a round-robin style.
-
- \until end_of_master
-\subsection MSG_ext_msl_slave Slave code
-
- This function has to be assigned to a #m_process_t that has to behave as a slave.
- Just like the master fuction (described in \ref MSG_ext_ms_master), it should not be called directly.
-
- This function keeps waiting for tasks and executes them as it receives them.
-
- \until end_of_slave
-
-\subsection MSG_ext_msl_core Simulation core
-
- This function is the core of the simulation and is divided now only into 2 parts
- thanks to MSG_load_platform_script().
- -# Simulation settings and application deployment : MSG_load_platform_script() loads and creates a realistic
- environment and the agents on the right locations, described in the lua script file (see example below).
- Note that the use of this function require a lua installation on your machine.
- -# The simulation is run with #MSG_main().
-
- Its arguments are:
- - <i>platform_script_file</i>: the name of the script file containing a valid platform and application description, using bound lua methods to bypass the surfxml parser.
-
- \until end_of_test_all
-
-\subsection MSG_ext_msl_main Main() function
-
- This initializes MSG, runs a simulation, and free all data-structures created by MSG.
-
- \until end_of_main
-
- \section MSG_ext_msl_helping Helping files
-
- \subsection MSG_ext_msl_platform Example of platform script file
-
- \include msg/masterslave/platform_script.lua
-
-
-*/
-
-/** \page MSG_ex_master_slave Master/slave application
+/** @defgroup MSG_ex_master_slave Basic Master/Slaves
+ @ingroup MSG_examples
Simulation of a master-slave application using a realistic platform and
an external description of the deployment.
#include "xbt.h" /* calloc, printf */
#include "instr/instr_private.h"
+/** @addtogroup MSG_examples
+ *
+ * @section MSG_ex_actions Trace driven simulations
+ *
+ * The <b>actions/actions.c</b> example demonstrates how to run trace-driven simulations. It
+ * is very handy when you want to test an algorithm or protocol that
+ * does nothing unless it receives some events from outside. For
+ * example, a P2P protocol reacts to requests from the user, but
+ * does nothing if there is no such event.
+ *
+ * In such situations, SimGrid allows to write your protocol in your
+ * C file, and the events to react to in a separate text file.
+ * Declare a function handling each of the events that you want to
+ * accept in your trace files, register them using @ref
+ * MSG_action_register in your main, and then use @ref
+ * MSG_action_trace_run to launch the simulation. You can either
+ * have one trace file containing all your events, or a file per
+ * simulated process. Check the tesh files in the example directory
+ * for details on how to do it.
+ *
+ * This example uses this approach to replay MPI-like traces. It
+ * comes with a set of event handlers reproducing MPI events. This
+ * is somehow similar to SMPI, yet differently implemented. This
+ * code should probably be changed to use SMPI internals instead,
+ * but wasn't, so far.
+ *
+ */
+
XBT_LOG_NEW_DEFAULT_CATEGORY(actions,
"Messages specific for this msg example");
int communicator_size = 0;
#include "xbt/asserts.h"
#include "simgrid/modelchecker.h"
-XBT_LOG_NEW_DEFAULT_CATEGORY(msg_chord,
+/** @addtogroup MSG_examples
+ *
+ * - <b>chord/chord.c: Classical Chord P2P protocol</b>
+ * This example implements the well known Chord P2P protocol. Its
+ * main advantage is that it constitute a fully working non-trivial
+ * example. In addition, its implementation is rather efficient, as
+ * demonstrated in http://hal.inria.fr/inria-00602216/
+ */
+
+
+ XBT_LOG_NEW_DEFAULT_CATEGORY(msg_chord,
"Messages specific for this msg example");
#define COMM_SIZE 10
/* This program is free software; you can redistribute it and/or modify it
* under the terms of the license (GNU LGPL) which comes with this package. */
+/** @addtogroup MSG_examples
+ *
+ * - <b>gpu/test_MSG_gpu_task_create.c</b> Example of use of the very experimental (for now) GPU resource.
+ */
+
#include <stdio.h>
#include <stdlib.h>
#include "msg/msg.h"
XBT_LOG_NEW_DEFAULT_CATEGORY(msg_test,
"Messages specific for this msg example");
+/** @addtogroup MSG_examples
+ *
+ * - <b>gtnets</b> Simple ping-pong using GTNeTs instead of the SimGrid network models.
+ */
+
int master(int argc, char *argv[]);
int slave(int argc, char *argv[]);
int timer(int argc, char *argv[]);
XBT_LOG_NEW_DEFAULT_CATEGORY(msg_test,
"Messages specific for this msg example");
+/** @addtogroup MSG_examples
+ *
+ * @section MSG_ex_icomms Asynchronous communications
+ *
+ * There is several examples of asynchronous communications coming in
+ * the archive. In addition to the fully documented example \ref
+ * MSG_ex_asynchronous_communications, there is several other
+ * examples in the archive:
+ *
+ * - <b>msg/icomms/peer.c</b>: basic example of async functions (@ref MSG_task_isend, @ref MSG_task_irecv, @ref MSG_comm_wait)
+ */
int sender(int argc, char *argv[]);
int receiver(int argc, char *argv[]);
XBT_LOG_NEW_DEFAULT_CATEGORY(msg_test,
"Messages specific for this msg example");
+/** @addtogroup MSG_examples
+ *
+ * - <b>msg/icomms/peer2.c</b>: demonstrates the @ref MSG_comm_waitall function
+ */
+
int sender(int argc, char *argv[]);
int receiver(int argc, char *argv[]);
XBT_LOG_NEW_DEFAULT_CATEGORY(msg_test,
"Messages specific for this msg example");
+/** @addtogroup MSG_examples
+ *
+ * - <b>msg/icomms/peer3.c</b>: demonstrates the @ref MSG_comm_waitany function
+ */
+
int sender(int argc, char *argv[]);
int receiver(int argc, char *argv[]);
/* This program is free software; you can redistribute it and/or modify it
* under the terms of the license (GNU LGPL) which comes with this package. */
+/** @addtogroup MSG_examples
+ *
+ * @subsection MSG_ex_resources Other resource kinds
+ *
+ * This section contains some sparse examples of how to use the other
+ * kind of resources, such as disk or GPU. These resources are quite
+ * experimental for now, but here we go anyway.
+ *
+ * - <b>io/file.c</b> Example with the disk resource
+ */
+
#include <stdio.h>
#include <stdlib.h>
#include "msg/msg.h"
-/* Copyright (c) 2007, 2008, 2009, 2010. The SimGrid Team.
- * All rights reserved. */
+/* Copyright (c) 2007-2012. The SimGrid Team. All rights reserved. */
/* This program is free software; you can redistribute it and/or modify it
* under the terms of the license (GNU LGPL) which comes with this package. */
+/** @addtogroup MSG_examples
+ *
+ * - <b>masterslave/masterslave_console.c</b>: demonstrate how to use
+ * lua files instead of XML for the platform and deployment
+ * declaration using @ref MSG_load_platform_script. The most
+ * interesting part is probably not the C code, but rather the
+ * <b>masterslave/masterslave_script.lua</b>, which demonstrates
+ * how to express the platform and deployment in lua.
+ *
+ */
+
#include <stdio.h>
#include "msg/msg.h" /* Yeah! If you want to use msg, you need to include msg/msg.h */
#include "surf/surfxml_parse.h" /* to override surf_parse and bypass the parser */
XBT_LOG_NEW_DEFAULT_CATEGORY(msg_test,
"Messages specific for this msg example");
+/** @addtogroup MSG_examples
+ *
+ * - <b>masterslave/masterslave_forwarder.c: Master/slaves
+ * example</b>. This good old example is also very simple. Its basic
+ * version is fully commented on this page: \ref MSG_ex_master_slave,
+ * but several variants can be found in the same directory.
+ */
+
+
int master(int argc, char *argv[]);
int slave(int argc, char *argv[]);
int forwarder(int argc, char *argv[]);
+-- Copyright (c) 2010-2012. The SimGrid Team. All rights reserved.
+
+-- This program is free software; you can redistribute it and/or modify it
+--under the terms of the license (GNU LGPL) which comes with this package.
+
+
+-- This file describes a platform very similar to the small_platform.xml, but in lua
+-- It is naturally to be used with the MSG_load_platform_script function
+
+-- Of course, such a flat file is maybe not very interesting wrt xml.
+-- The full power of lua reveals when you describe your platform programatically.
+
require "simgrid"
simgrid.AS.new{id="AS0",mode="Full"};
XBT_LOG_NEW_DEFAULT_CATEGORY(msg_test,
"Messages specific for this msg example");
+/** @addtogroup MSG_examples
+ *
+ * - <b>migration/migration.c</b> Demonstrates how to use the @ref
+ * MSG_process_migrate function to let processes change the host they
+ * run on after their start.
+ */
+
xbt_mutex_t mutex = NULL;
xbt_cond_t cond = NULL;
static m_process_t process_to_migrate = NULL;
XBT_LOG_NEW_DEFAULT_CATEGORY(msg_test,
"Messages specific for this msg example");
+
+/** @addtogroup MSG_examples
+ *
+ * @section MSG_ex_models Models-related examples
+ *
+ * @subsection MSG_ex_PLS Packet level simulators
+ *
+ * These examples demonstrate how to use the bindings to classical
+ * Packet-Level Simulators (PLS), as explained in \ref pls. 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 files to see how to declare a platform to be used with
+ * the PLS bindings of SimGrid and the tesh files to see how to
+ * actually start a simulation in these settings.
+ *
+ * - <b>ns3</b>: Simple ping-pong using ns3 instead of the SimGrid network models.
+ *
+ */
+
int master(int argc, char *argv[]);
int slave(int argc, char *argv[]);
int timer(int argc, char *argv[]);
XBT_LOG_NEW_DEFAULT_CATEGORY(msg_test,
"Messages specific for this msg example");
+/** @addtogroup MSG_examples
+ *
+ * - <b>parallel_task/parallel_task.c</b>: Demonstrates the use of
+ * @ref MSG_parallel_task_create, to create special tasks that run
+ * on several hosts at the same time. The resulting simulations are
+ * very close to what can be achieved in @ref SD_API, but still
+ * allows to use the other features of MSG (it'd be cool to be able
+ * to mix interfaces, but it's not possible ATM).
+ */
+
int test(int argc, char *argv[]);
MSG_error_t test_all(const char *platform_file);
#include "xbt/xbt_os_time.h"
#endif
+/** @addtogroup MSG_examples
+ *
+ * - <b>pmm/msg_pmm.c</b>: Parallel Matrix Multiplication is a little
+ * application. This is something that most MPI developper have
+ * written during their class, here implemented using MSG instead
+ * of MPI.
+ */
+
XBT_LOG_NEW_DEFAULT_CATEGORY(msg_pmm,
"Messages specific for this msg example");
XBT_LOG_NEW_DEFAULT_CATEGORY(msg_test,
"Messages specific for this msg example");
+/** @addtogroup MSG_examples
+ *
+ * - <b>priority/priority.c</b>: Demonstrates the use of @ref
+ * MSG_task_set_priority to change the computation priority of a
+ * given task.
+ *
+ */
+
static int test(int argc, char *argv[])
{
double computation_amount = 0.0;
#include <stdio.h>
#include <stdlib.h>
+/** @addtogroup MSG_examples
+ *
+ * - <b>properties/msg_prop.c</b> Attaching arbitrary informations to
+ * host, processes and such, and retrieving them with @ref
+ * MSG_host_get_properties, @ref MSG_host_get_property_value, @ref
+ * MSG_process_get_properties and @ref
+ * MSG_process_get_property_value. Also make sure to read the
+ * platform and deployment XML files to see how to declare these
+ * data.
+ *
+ */
+
XBT_LOG_NEW_DEFAULT_CATEGORY(test, "Property test");
int alice(int argc, char *argv[]);
#include "xbt/log.h"
#include "xbt/asserts.h"
+/** @addtogroup MSG_examples
+ *
+ * - <b>sendrecv/sendrecv.c: Ping-pong example</b>. It's hard to
+ * think of a simpler example. The tesh files laying in the
+ * directory are instructive concerning the way to pass options to the simulators (as described in \ref options).
+ */
+
XBT_LOG_NEW_DEFAULT_CATEGORY(msg_test,
"Messages specific for this msg example");
XBT_LOG_NEW_DEFAULT_CATEGORY(msg_test,
"Messages specific for this msg example");
+/** @addtogroup MSG_examples
+ *
+ * - <b>suspend/suspend.c</b>: Demonstrates how to suspend and resume processes using @ref MSG_process_suspend and @ref MSG_process_resume.
+ */
/** Lazy guy function. This process suspends itself asap. */
static int lazy_guy(int argc, char *argv[])
XBT_LOG_NEW_DEFAULT_CATEGORY(ring,
"Messages specific for this msg example");
+/** @addtogroup MSG_examples
+ *
+ * @section MSG_ex_apps Examples of full applications
+ *
+ * - <b>token_ring/ring_call.c</b>: Classical token ring
+ * communication, where a token is exchanged along a ring to reach
+ * every participant.
+ *
+ */
+
int host(int argc, char *argv[])
{
int host_number = atoi(MSG_process_get_name(MSG_process_self()));
/* This program is free software; you can redistribute it and/or modify it
* under the terms of the license (GNU LGPL) which comes with this package. */
+/** @addtogroup MSG_examples
+ *
+ * - <b>tracing/categories.c</b> example with the declaration of multiple categories
+ */
+
#include <stdio.h>
#include "msg/msg.h"
#include "xbt/sysdep.h" /* calloc, printf */
/* This program is free software; you can redistribute it and/or modify it
* under the terms of the license (GNU LGPL) which comes with this package. */
+/** @addtogroup MSG_examples
+ *
+ * - <b>tracing/ms.c</b> TODO
+ */
+
#include <stdio.h>
#include "msg/msg.h"
#include "xbt/sysdep.h" /* calloc, printf */
-/* Copyright (c) 2009 The SimGrid team. All rights reserved. */
+/* Copyright (c) 2010 The SimGrid team. All rights reserved. */
/* This program is free software; you can redistribute it and/or modify it
* under the terms of the license (GNU LGPL) which comes with this package. */
+/** @addtogroup MSG_examples
+ *
+ * - <b>tracing/procmig.c</b> example to trace process migration using the mask TRACE_PROCESS
+ */
+
#include "msg/msg.h" /* core library */
#include "xbt/sysdep.h" /* calloc */
#include "msg/msg.h"
#include "xbt/sysdep.h" /* calloc, printf */
+/** @addtogroup MSG_examples
+ *
+ * @section MSG_ex_tracing Tracing and vizualization features
+ *
+ * - <b>tracing/simple.c</b> very simple program that creates, executes and destroy a task
+ */
+
/* Create a log channel to have nice outputs. */
#include "xbt/log.h"
#include "xbt/asserts.h"
/* This program is free software; you can redistribute it and/or modify it
* under the terms of the license (GNU LGPL) which comes with this package. */
+/** @addtogroup MSG_examples
+ *
+ * - <b>tracing/trace_platform.c</b>: Demonstrates how to trace the platform
+ */
+
#include <stdio.h>
#include "msg/msg.h"
#include "xbt/sysdep.h" /* calloc, printf */
/* This program is free software; you can redistribute it and/or modify it
* under the terms of the license (GNU LGPL) which comes with this package. */
+/** @addtogroup MSG_examples
+ *
+ * - <b>tracing/user_variables.c</b>: Demonstrates how to trace user-provided variables
+ */
+
#include <stdio.h>
#include "msg/msg.h"
#include "xbt/sysdep.h" /* calloc, printf */
