From: Frederic Suter Date: Fri, 15 Apr 2016 19:45:23 +0000 (+0200) Subject: revise documentation of async examples X-Git-Tag: v3_13~100 X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/63f4cba590c1f4074f4891408b3a6cd6d8440eda revise documentation of async examples --- diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 12601ad858..c5e27c76cf 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -699,8 +699,8 @@ INPUT += @CMAKE_HOME_DIRECTORY@/examples/msg/app-pingpong/app-pi @CMAKE_HOME_DIRECTORY@/examples/msg/app-token-ring/app-token-ring.c \ @CMAKE_HOME_DIRECTORY@/examples/msg/app-masterworker/app-masterworker.c \ @CMAKE_HOME_DIRECTORY@/examples/msg/async-wait/async-wait.c \ - @CMAKE_HOME_DIRECTORY@/examples/msg/icomms/peer2.c \ - @CMAKE_HOME_DIRECTORY@/examples/msg/icomms/peer3.c \ + @CMAKE_HOME_DIRECTORY@/examples/msg/async-waitall/async-waitall.c \ + @CMAKE_HOME_DIRECTORY@/examples/msg/async-waitany/async-waitany.c \ @CMAKE_HOME_DIRECTORY@/examples/msg/process-suspend/process-suspend.c \ @CMAKE_HOME_DIRECTORY@/examples/msg/process-kill/process-kill.c \ @CMAKE_HOME_DIRECTORY@/examples/msg/process-migration/process-migration.c \ diff --git a/examples/msg/async-wait/async-wait.c b/examples/msg/async-wait/async-wait.c index 089cf09fda..1071d85353 100644 --- a/examples/msg/async-wait/async-wait.c +++ b/examples/msg/async-wait/async-wait.c @@ -6,26 +6,28 @@ #include "simgrid/msg.h" -XBT_LOG_NEW_DEFAULT_CATEGORY(msg_test, "Messages specific for this msg example"); +XBT_LOG_NEW_DEFAULT_CATEGORY(msg_async_wait, "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: + * In addition to the fully documented example of \ref MSG_ex_asynchronous_communications, there are several othe + * examples shipped in the archive: * - * - msg/icomms/peer.c: basic example of async functions (@ref MSG_task_isend, @ref MSG_task_irecv, @ref MSG_comm_wait) + * - Basic example: async-wait/async-wait.c. Illustrates the use of asynchronous functions (@ref MSG_task_isend, + * @ref MSG_task_irecv, and @ref MSG_comm_wait). */ +/** Sender process expects 6 arguments: */ static int sender(int argc, char *argv[]) { - long number_of_tasks = xbt_str_parse_int(argv[1], "Invalid amount of tasks: %s"); - double task_comp_size = xbt_str_parse_double(argv[2], "Invalid computational size: %s"); - double task_comm_size = xbt_str_parse_double(argv[3], "Invalid communication size: %s"); - long receivers_count = xbt_str_parse_int(argv[4], "Invalid amount of receivers: %s"); - double sleep_start_time = xbt_str_parse_double(argv[5], "Invalid sleep start time: %s"); - double sleep_test_time = xbt_str_parse_double(argv[6], "Invalid test time: %s"); + long number_of_tasks = xbt_str_parse_int(argv[1], "Invalid amount of tasks: %s"); /** - number of tasks */ + double task_comp_size = xbt_str_parse_double(argv[2], "Invalid computational size: %s"); /** - computational cost */ + double task_comm_size = xbt_str_parse_double(argv[3], "Invalid communication size: %s"); /** - communication cost */ + long receivers_count = xbt_str_parse_int(argv[4], "Invalid amount of receivers: %s"); /** - number of receivers */ + double sleep_start_time = xbt_str_parse_double(argv[5], "Invalid sleep start time: %s"); /** - start time */ + double sleep_test_time = xbt_str_parse_double(argv[6], "Invalid test time: %s"); /** - test time */ XBT_INFO("sleep_start_time : %f , sleep_test_time : %f", sleep_start_time, sleep_test_time); @@ -40,14 +42,15 @@ static int sender(int argc, char *argv[]) sprintf(mailbox, "receiver-%ld", i % receivers_count); sprintf(sprintf_buffer, "Task_%d", i); + /** This process first creates a task and send it asynchronously with @ref MSG_task_isend. Then, if: */ task = MSG_task_create(sprintf_buffer, task_comp_size, task_comm_size, NULL); comm = MSG_task_isend(task, mailbox); XBT_INFO("Send to receiver-%ld Task_%d", i % receivers_count, i); - if (sleep_test_time == 0) { + if (sleep_test_time == 0) { /** - "test_time" is set to 0, wait on @ref MSG_comm_wait */ MSG_comm_wait(comm, -1); } else { - while (MSG_comm_test(comm) == 0) { + while (MSG_comm_test(comm) == 0) { /** - Call @ref MSG_comm_test every "test_time" otherwise */ MSG_process_sleep(sleep_test_time); }; } @@ -74,45 +77,42 @@ static int sender(int argc, char *argv[]) return 0; } +/** Receiver process expects 3 arguments: */ static int receiver(int argc, char *argv[]) { msg_task_t task = NULL; XBT_ATTRIB_UNUSED msg_error_t res; - int id = -1; char mailbox[80]; msg_comm_t res_irecv; - double sleep_start_time = xbt_str_parse_double(argv[2], "Invalid sleep start parameter: %s"); - double sleep_test_time = xbt_str_parse_double(argv[3], "Invalid sleep test parameter: %s"); + int id = xbt_str_parse_int(argv[1], "Invalid id: %s"); /** - unique id */ + double sleep_start_time = xbt_str_parse_double(argv[2], "Invalid sleep start parameter: %s"); /** - start time */ + double sleep_test_time = xbt_str_parse_double(argv[3], "Invalid sleep test parameter: %s"); /** - test time */ XBT_INFO("sleep_start_time : %f , sleep_test_time : %f", sleep_start_time, sleep_test_time); - XBT_ATTRIB_UNUSED int read; - read = sscanf(argv[1], "%d", &id); - xbt_assert(read, "Invalid argument %s\n", argv[1]); - - MSG_process_sleep(sleep_start_time); + MSG_process_sleep(sleep_start_time); /** This process first sleeps for "start time" seconds. */ sprintf(mailbox, "receiver-%d", id); while (1) { - res_irecv = MSG_task_irecv(&(task), mailbox); + res_irecv = MSG_task_irecv(&(task), mailbox); /** Then it posts asynchronous receives (@ref MSG_task_irecv) and*/ XBT_INFO("Wait to receive a task"); - if (sleep_test_time == 0) { + if (sleep_test_time == 0) { /** - if "test_time" is set to 0, wait on @ref MSG_comm_wait */ res = MSG_comm_wait(res_irecv, -1); xbt_assert(res == MSG_OK, "MSG_task_get failed"); } else { - while (MSG_comm_test(res_irecv) == 0) { + while (MSG_comm_test(res_irecv) == 0) { /** - Call @ref MSG_comm_test every "test_time" otherwise */ MSG_process_sleep(sleep_test_time); }; } MSG_comm_destroy(res_irecv); XBT_INFO("Received \"%s\"", MSG_task_get_name(task)); - if (!strcmp(MSG_task_get_name(task), "finalize")) { + if (!strcmp(MSG_task_get_name(task), "finalize")) { /** If the received task is "finalize", the process ends */ MSG_task_destroy(task); break; } - XBT_INFO("Processing \"%s\"", MSG_task_get_name(task)); + XBT_INFO("Processing \"%s\"", MSG_task_get_name(task)); /** Otherwise, the task is processed */ MSG_task_execute(task); XBT_INFO("\"%s\" done", MSG_task_get_name(task)); MSG_task_destroy(task); @@ -130,13 +130,13 @@ int main(int argc, char *argv[]) xbt_assert(argc > 2, "Usage: %s platform_file deployment_file\n" "\tExample: %s msg_platform.xml msg_deployment.xml\n", argv[0], argv[0]); - MSG_create_environment(argv[1]); + MSG_create_environment(argv[1]);/** - Load the platform description */ MSG_function_register("sender", sender); MSG_function_register("receiver", receiver); - MSG_launch_application(argv[2]); + MSG_launch_application(argv[2]);/** - Deploy the @ref sender and @ref receiver processes */ - res = MSG_main(); + res = MSG_main(); /** - Run the simulation */ XBT_INFO("Simulation time %g", MSG_get_clock()); diff --git a/examples/msg/async-waitall/async-waitall.c b/examples/msg/async-waitall/async-waitall.c index 8a0759eae9..bc3db3b849 100644 --- a/examples/msg/async-waitall/async-waitall.c +++ b/examples/msg/async-waitall/async-waitall.c @@ -6,11 +6,11 @@ #include "simgrid/msg.h" -XBT_LOG_NEW_DEFAULT_CATEGORY(msg_test, "Messages specific for this msg example"); +XBT_LOG_NEW_DEFAULT_CATEGORY(msg_async_waitall, "Messages specific for this msg example"); /** @addtogroup MSG_examples * - * - msg/icomms/peer2.c: demonstrates the @ref MSG_comm_waitall function + * - Wait all: async-waitall/async-waitall.c. Illustrates the use of the @ref MSG_comm_waitall function. */ static int sender(int argc, char *argv[]) diff --git a/examples/msg/async-waitany/async-waitany.c b/examples/msg/async-waitany/async-waitany.c index db2d0f718a..4e053e4a18 100644 --- a/examples/msg/async-waitany/async-waitany.c +++ b/examples/msg/async-waitany/async-waitany.c @@ -6,7 +6,12 @@ #include "simgrid/msg.h" -XBT_LOG_NEW_DEFAULT_CATEGORY(msg_test, "Messages specific for this msg example"); +XBT_LOG_NEW_DEFAULT_CATEGORY(msg_async_waitany, "Messages specific for this msg example"); + +/** @addtogroup MSG_examples + * + * - Wait any: async-waitany/async-waitany.c. Illustrates the use of the @ref MSG_comm_waitany function. + */ static int sender(int argc, char *argv[]) {