From: Martin Quinson Date: Mon, 16 May 2016 05:07:37 +0000 (+0200) Subject: doc example: actions and apps X-Git-Tag: v3_14~1223 X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/c4b490069d7cdcaa3af5c0709d9967321cf48f9f doc example: actions and apps --- diff --git a/examples/msg/README.doc b/examples/msg/README.doc index 61f9559667..ff47a2e31b 100644 --- a/examples/msg/README.doc +++ b/examples/msg/README.doc @@ -15,7 +15,7 @@ documentation, but it should remain readable directly. - @ref msg_ex_ns3 - @ref msg_ex_io - @ref msg_ex_actions - - @ref msg_ex_full_apps + - @ref msg_ex_apps - @ref msg_ex_misc @section msg_ex_basic Basic examples and features @@ -199,10 +199,52 @@ simulated storages. I/O operations can also be done in a remote, i.e. when the accessed disk is not mounted on the caller's host. - - @ref examples/msg/actions-comm/actions-comm.c \n - - @ref examples/msg/actions-storage/actions-storage.c \n - - @ref examples/msg/app-pmm/app-pmm.c \n - - @ref examples/msg/dht-chord \n +@section msg_ex_actions Following Workload Traces + +This section details how to run trace-driven simulations. It is very +handy when you want to test an algorithm or protocol that only react +to external events. For example, many P2P protocols react to user +requests, but do nothing if there is no such event. + +In such situations, you should write your protocol in C, and separate +the workload that you want to play onto your protocol in a separate +text file. Declare a function handling each type of the events in your +trace, register them using @ref xbt_replay_action_register in your +main, and then use @ref MSG_action_trace_run to launch the simulation. + +Then, you can either have one trace file containing all your events, +or a file per simulated process: the former may be easier to work +with, but the second is more efficient on very large traces. Check +also the tesh files in the example directories for details. + + - Communication replay. + @ref examples/msg/actions-comm/actions-comm.c \n + Presents a set of event handlers reproducing classical communication + primitives (synchronous and asynchronous send/receive, broadcast, + barrier, etc). + + - I/O replay. + @ref examples/msg/actions-storage/actions-storage.c \n + Presents a set of event handlers reproducing classical I/O + primitives (open, read, write, close, etc). + +@section msg_ex_apps Examples of Full Applications + + - Parallel Matrix Multiplication. + @ref examples/msg/app-pmm/app-pmm.c \n + This little application multiplies two matrices in parallel. Each + of the 9 processes computes a sub-block of the result, with the + sub-blocks of the input matrices exchanged between the processes. \n + This is a classical assignment in MPI lectures, here implemented + in MSG. + + - Chord P2P protocol. + @ref examples/msg/dht-chord/dht-chord.c \n + This example implements the well known Chord protocol, + constituting a fully working non-trivial example. This + implementation is also very efficient, as demonstrated in + http://hal.inria.fr/inria-00602216/ + - @ref examples/msg/task-priority/task-priority.c \n - @ref examples/msg/properties/properties.c \n @@ -245,10 +287,13 @@ example file). @example examples/msg/io-storage/io-storage.c @example examples/msg/io-file/io-file.c @example examples/msg/io-remote/io-remote.c + @example examples/msg/actions-comm/actions-comm.c @example examples/msg/actions-storage/actions-storage.c + @example examples/msg/app-pmm/app-pmm.c @example examples/msg/dht-chord + @example examples/msg/task-priority/task-priority.c @example examples/msg/properties/properties.c @@ -275,29 +320,6 @@ Basic examples and features MSG_task_set_priority() to change the computation priority of a given task. -Trace driven simulations -======================== - -The actions/actions.c 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 MSG_action_register in your main, and -then use 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. - Examples of full applications ============================= diff --git a/examples/msg/actions-comm/actions-comm.c b/examples/msg/actions-comm/actions-comm.c index da5e79f0a8..f840d898de 100644 --- a/examples/msg/actions-comm/actions-comm.c +++ b/examples/msg/actions-comm/actions-comm.c @@ -1,5 +1,4 @@ -/* Copyright (c) 2009-2015. The SimGrid Team. - * All rights reserved. */ +/* Copyright (c) 2009-2016. 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. */ @@ -8,24 +7,6 @@ #include "simgrid/simix.h" /* semaphores for the barrier */ #include -/** @addtogroup MSG_examples - * - * @section msg_ex_actions Trace driven simulations - * - * This section details 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 you to write your protocol in a 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 xbt_replay_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 directories for details on how to do it. - * - * - Communication: actions-comm/actions-comm.c. This example comes with a set of event handlers reproducing - * some classical communication primitives (synchronous and asynchronous send/receive, broadcast, barrier, ...). - */ - XBT_LOG_NEW_DEFAULT_CATEGORY(actions, "Messages specific for this msg example"); int communicator_size = 0; @@ -209,33 +190,30 @@ static void action_barrier(const char *const *action) static void action_bcast(const char *const *action) { - int i; - char *bcast_identifier; char mailbox[80]; double comm_size = parse_double(action[2]); msg_task_t task = NULL; - const char *process_name; double clock = MSG_get_clock(); process_globals_t counters = (process_globals_t) MSG_process_get_data(MSG_process_self()); xbt_assert(communicator_size, "Size of Communicator is not defined, can't use collective operations"); - process_name = MSG_process_get_name(MSG_process_self()); + const char * process_name = MSG_process_get_name(MSG_process_self()); - bcast_identifier = bprintf("bcast_%d", counters->bcast_counter++); + char *bcast_identifier = bprintf("bcast_%d", counters->bcast_counter++); if (!strcmp(process_name, "p0")) { XBT_DEBUG("%s: %s is the Root", bcast_identifier, process_name); msg_comm_t *comms = xbt_new0(msg_comm_t, communicator_size - 1); - for (i = 1; i < communicator_size; i++) { + for (int i = 1; i < communicator_size; i++) { sprintf(mailbox, "%s_p0_p%d", bcast_identifier, i); comms[i - 1] = MSG_task_isend(MSG_task_create(mailbox, 0, comm_size, NULL), mailbox); } MSG_comm_waitall(comms, communicator_size - 1, -1); - for (i = 1; i < communicator_size; i++) + for (int i = 1; i < communicator_size; i++) MSG_comm_destroy(comms[i - 1]); xbt_free(comms); @@ -294,7 +272,6 @@ static void action_finalize(const char *const *action) } } -/** Main function */ int main(int argc, char *argv[]) { msg_error_t res = MSG_OK; @@ -333,8 +310,7 @@ int main(int argc, char *argv[]) XBT_INFO("Simulation time %g", MSG_get_clock()); - /* Explicit finalization of the action module is required now*/ - MSG_action_exit(); + MSG_action_exit(); /* Explicit finalization of the action module */ return res != MSG_OK; } diff --git a/examples/msg/actions-storage/actions-storage.c b/examples/msg/actions-storage/actions-storage.c index 4165f23eaf..2be369d52e 100644 --- a/examples/msg/actions-storage/actions-storage.c +++ b/examples/msg/actions-storage/actions-storage.c @@ -1,5 +1,4 @@ -/* Copyright (c) 2015. The SimGrid Team. - * All rights reserved. */ +/* Copyright (c) 2015-2016. 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. */ @@ -8,11 +7,6 @@ #include XBT_LOG_NEW_DEFAULT_CATEGORY(storage_actions, "Messages specific for this example"); -/** @addtogroup MSG_examples - * - * - I/O: actions-comm/actions-comm.c. This example comes with a set of event handlers reproducing - * some classical I/O primitives (open, read, write, close, ...). - */ static xbt_dict_t opened_files = NULL; diff --git a/examples/msg/app-pmm/app-pmm.c b/examples/msg/app-pmm/app-pmm.c index f55f1a2c60..d6ee681457 100644 --- a/examples/msg/app-pmm/app-pmm.c +++ b/examples/msg/app-pmm/app-pmm.c @@ -1,7 +1,6 @@ -/* pmm - parallel matrix multiplication "double diffusion" */ +/* pmm - double broadcast parallel matrix multiplication */ -/* Copyright (c) 2006-2015. The SimGrid Team. - * All rights reserved. */ +/* Copyright (c) 2006-2016. 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. */ @@ -10,13 +9,6 @@ #include "xbt/matrix.h" #include "xbt/xbt_os_time.h" -/** @addtogroup MSG_examples - * @section msg_ex_full_apps Examples of full applications - * - * - Parallel Matrix Multiplication: app-pmm/app-pmm.c. This little application is something that most MPI - * developers have written during their studies. Here it is implemented in MSG. - */ - XBT_LOG_NEW_DEFAULT_CATEGORY(msg_pmm, "Messages specific for this msg example"); /* This example should always be executed using a deployment of GRID_SIZE * GRID_SIZE nodes. */ diff --git a/examples/msg/dht-chord/dht-chord.c b/examples/msg/dht-chord/dht-chord.c index df00c1c4e6..b8928e7bff 100644 --- a/examples/msg/dht-chord/dht-chord.c +++ b/examples/msg/dht-chord/dht-chord.c @@ -1,5 +1,4 @@ -/* Copyright (c) 2010-2015. The SimGrid Team. - * All rights reserved. */ +/* Copyright (c) 2010-2016. 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. */ @@ -9,14 +8,6 @@ #include #include "src/mc/mc_replay.h" // FIXME: this is an internal header -/** @addtogroup MSG_examples - * - * - Chord P2P protocol dht-chord/dht-chord.c:. This example implements the well known Chord P2P protocol. Its - * main advantage is that it constitutes 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 @@ -109,7 +100,7 @@ static void check_predecessor(node_t node); static void random_lookup(node_t); static void quit_notify(node_t node); -/* \brief Global initialization of the Chord simulation. */ +/* Global initialization of the Chord simulation. */ static void chord_initialize(void) { // compute the powers of 2 once for all @@ -147,19 +138,14 @@ static void chord_exit(void) xbt_free(powers2); } -/** - * \brief Turns an id into an equivalent id in [0, nb_keys). - * \param id an id - * \return the corresponding normalized id - */ +/* Turns an id into an equivalent id in [0, nb_keys). */ static int normalize(int id) { // like id % nb_keys, but works with negatives numbers (and faster) return id & (nb_keys - 1); } -/** - * \brief Returns whether an id belongs to the interval [start, end]. +/* Returns whether an id belongs to the interval [start, end]. * * The parameters are noramlized to make sure they are between 0 and nb_keys - 1). * 1 belongs to [62, 3] @@ -192,8 +178,7 @@ static int is_in_interval(int id, int start, int end) return id <= end; } -/** - * \brief Gets the mailbox name of a host given its chord id. +/* Gets the mailbox name of a host given its chord id. * \param node_id id of a node * \param mailbox pointer to where the mailbox name should be written * (there must be enough space) @@ -203,10 +188,7 @@ static void get_mailbox(int node_id, char* mailbox) snprintf(mailbox, MAILBOX_NAME_SIZE - 1, "%d", node_id); } -/** - * \brief Frees the memory used by a task. - * \param task the MSG task to destroy - */ +/* Frees the memory used by a task and destroy it */ static void task_free(void* task) { // TODO add a parameter data_free_function to MSG_task_create? @@ -216,10 +198,7 @@ static void task_free(void* task) } } -/** - * \brief Displays the finger table of a node. - * \param node a node - */ +/* Displays the finger table of a node. */ static void print_finger_table(node_t node) { if (XBT_LOG_ISENABLED(msg_chord, xbt_log_priority_verbose)) { @@ -233,8 +212,8 @@ static void print_finger_table(node_t node) } } -/** - * \brief Sets a finger of the current node. +/* Sets a finger of the current node. + * * \param node the current node * \param finger_index index of the finger to set (0 to nb_bits - 1) * \param id the id to set for this finger @@ -249,8 +228,8 @@ static void set_finger(node_t node, int finger_index, int id) } } -/** - * \brief Sets the predecessor of the current node. +/* Sets the predecessor of the current node. + * * \param node the current node * \param id the id to predecessor, or -1 to unset the predecessor */ @@ -268,8 +247,8 @@ static void set_predecessor(node_t node, int predecessor_id) } } -/** - * \brief Node Function +/* Node main Function + * * Arguments: * - my id * - the id of a guy I know in the system (except for the first node) @@ -426,11 +405,10 @@ int node(int argc, char *argv[]) return 0; } -/** - * \brief This function is called when the current node receives a task. +/* This function is called when the current node receives a task. + * * \param node the current node - * \param task the task to handle (don't touch it then: - * it will be destroyed, reused or forwarded) + * \param task the task to handle (don't touch it afterward: it will be destroyed, reused or forwarded) */ static void handle_task(node_t node, msg_task_t task) { @@ -525,10 +503,7 @@ static void handle_task(node_t node, msg_task_t task) { } } -/** - * \brief Initializes the current node as the first one of the system. - * \param node the current node - */ +/* Initializes the current node as the first one of the system */ static void create(node_t node) { XBT_DEBUG("Create a new Chord ring..."); @@ -536,9 +511,8 @@ static void create(node_t node) print_finger_table(node); } -/** - * \brief Makes the current node join the ring, knowing the id of a node - * already in the ring +/* Makes the current node join the ring, knowing the id of a node already in the ring + * * \param node the current node * \param known_id id of a node already in the ring * \return 1 if the join operation succeeded, 0 otherwise @@ -549,10 +523,8 @@ static int join(node_t node, int known_id) set_predecessor(node, -1); // no predecessor (yet) /* - int i; - for (i = 0; i < nb_bits; i++) { + for (int i = 0; i < nb_bits; i++) set_finger(node, i, known_id); - } */ int successor_id = remote_find_successor(node, known_id, node->id); @@ -567,21 +539,14 @@ static int join(node_t node, int known_id) return successor_id != -1; } -/** - * \brief Makes the current node quit the system - * \param node the current node - */ +/* Makes the current node quit the system */ static void leave(node_t node) { XBT_DEBUG("Well Guys! I Think it's time for me to quit ;)"); quit_notify(node); } -/** - * \brief Notifies the successor and the predecessor of the current node - * of the departure - * \param node the current node - */ +/* Notifies the successor and the predecessor of the current node before leaving */ static void quit_notify(node_t node) { char mailbox[MAILBOX_NAME_SIZE]; @@ -621,8 +586,8 @@ static void quit_notify(node_t node) } -/** - * \brief Makes the current node find the successor node of an id. +/* Makes the current node find the successor node of an id. + * * \param node the current node * \param id the id to find * \return the id of the successor node, or -1 if the request failed @@ -639,8 +604,8 @@ static int find_successor(node_t node, int id) return remote_find_successor(node, closest, id); } -/** - * \brief Asks another node the successor node of an id. +/* \brief Asks another node the successor node of an id. + * * \param node the current node * \param ask_to the node to ask to * \param id the id to find @@ -732,8 +697,8 @@ static int remote_find_successor(node_t node, int ask_to, int id) return successor; } -/** - * \brief Asks another node its predecessor. +/* Asks its predecessor to a remote node + * * \param node the current node * \param ask_to the node to ask to * \return the id of its predecessor node, or -1 if the request failed @@ -811,9 +776,8 @@ static int remote_get_predecessor(node_t node, int ask_to) return predecessor_id; } -/** - * \brief Returns the closest preceding finger of an id - * with respect to the finger table of the current node. +/* Returns the closest preceding finger of an id with respect to the finger table of the current node. + * * \param node the current node * \param id the id to find * \return the closest preceding finger of that id @@ -829,11 +793,7 @@ int closest_preceding_node(node_t node, int id) return node->id; } -/** - * \brief This function is called periodically. It checks the immediate - * successor of the current node. - * \param node the current node - */ +/* This function is called periodically. It checks the immediate successor of the current node. */ static void stabilize(node_t node) { XBT_DEBUG("Stabilizing node"); @@ -858,11 +818,7 @@ static void stabilize(node_t node) } } -/** - * \brief Notifies the current node that its predecessor may have changed. - * \param node the current node - * \param candidate_id the possible new predecessor - */ +/* Notifies the current node that its predecessor may have changed. */ static void notify(node_t node, int predecessor_candidate_id) { if (node->pred_id == -1 @@ -876,12 +832,7 @@ static void notify(node_t node, int predecessor_candidate_id) { } } -/** - * \brief Notifies a remote node that its predecessor may have changed. - * \param node the current node - * \param notify_id id of the node to notify - * \param candidate_id the possible new predecessor - */ +/* Notifies a remote node that its predecessor may have changed. */ static void remote_notify(node_t node, int notify_id, int predecessor_candidate_id) { task_data_t req_data = xbt_new0(s_task_data_t, 1); @@ -897,11 +848,7 @@ static void remote_notify(node_t node, int notify_id, int predecessor_candidate_ MSG_task_dsend(task, mailbox, task_free); } -/** - * \brief This function is called periodically. - * It refreshes the finger table of the current node. - * \param node the current node - */ +/* refreshes the finger table of the current node (called periodically) */ static void fix_fingers(node_t node) { XBT_DEBUG("Fixing fingers"); @@ -917,11 +864,7 @@ static void fix_fingers(node_t node) { } } -/** - * \brief This function is called periodically. - * It checks whether the predecessor has failed - * \param node the current node - */ +/* checks whether the predecessor has failed (called periodically) */ static void check_predecessor(node_t node) { XBT_DEBUG("Checking whether my predecessor is alive"); @@ -987,10 +930,7 @@ static void check_predecessor(node_t node) } } -/** - * \brief Performs a find successor request to a random id. - * \param node the current node - */ +/* Performs a find successor request to a random id */ static void random_lookup(node_t node) { int random_index = RngStream_RandInt (node->stream, 0, nb_bits - 1);