From 87f40446646326cb07fe9d8f15034826c2fa9d19 Mon Sep 17 00:00:00 2001 From: thiery Date: Wed, 28 Jun 2006 09:05:15 +0000 Subject: [PATCH] Add documentation for workstations and fix a few bugs git-svn-id: svn+ssh://scm.gforge.inria.fr/svn/simgrid/simgrid/trunk@2459 48e7efb5-ca39-0410-a469-dd3cf9ba447f --- doc/modules.doc | 4 +- examples/simdag/sd_test.c | 1 + include/simdag/simdag.h | 21 +++++++--- src/simdag/sd_task.c | 17 ++++---- src/simdag/sd_workstation.c | 83 +++++++++++++++++++++++++++++++------ 5 files changed, 98 insertions(+), 28 deletions(-) diff --git a/doc/modules.doc b/doc/modules.doc index 74de864675..10b92e03f6 100644 --- a/doc/modules.doc +++ b/doc/modules.doc @@ -121,9 +121,9 @@ SimDag provides some functionnalities to simulate parallel task scheduling with DAGs models (Direct Acyclic Graphs). The old versions of SimGrid were based on DAGs. But the DAG part (named SG) - was removed in SimGrid 3 because the new kernel (\ref SURF) was implemented. \ref SURF + was removed in SimGrid 3 because the new kernel (\ref SURF_API) was implemented. \ref SURF_API was much faster and more flexible than SG and did not use DAGs. - SimDag is a new implementation of DAGs handling and it is built on top of \ref SURF. + SimDag is a new implementation of DAGs handling and it is built on top of \ref SURF_API. \section SD_who Who should use this (and who shouldn't) diff --git a/examples/simdag/sd_test.c b/examples/simdag/sd_test.c index 3c37701bb5..3c65b568ec 100644 --- a/examples/simdag/sd_test.c +++ b/examples/simdag/sd_test.c @@ -80,6 +80,7 @@ int main(int argc, char **argv) { } i++; } + free(changed_tasks); SD_task_destroy(taskA); diff --git a/include/simdag/simdag.h b/include/simdag/simdag.h index 1215fc00f3..6efe56bc0f 100644 --- a/include/simdag/simdag.h +++ b/include/simdag/simdag.h @@ -23,9 +23,19 @@ void SD_link_destroy(SD_link_t link); /************************** Workstation handling ****************************/ -/* private (called by SD_environment_create) -SD_workstation_t SD_workstation_create(void *data, const char *name, double power, - double available_power);*/ +/** @defgroup SD_workstation_management Workstations + * @brief Functions for managing the workstations + * + * This section describes the functions for managing the workstations. + * + * A workstation is a place where a task can be executed. + * A workstation is represented as a physical + * resource with computing capabilities and has a name. + * + * @see SD_workstation_t + * + * @{ + */ SD_workstation_t SD_workstation_get_by_name(const char *name); SD_workstation_t* SD_workstation_get_list(void); int SD_workstation_get_number(void); @@ -36,9 +46,8 @@ SD_link_t* SD_workstation_route_get_list(SD_workstation_t src, SD_workst int SD_workstation_route_get_size(SD_workstation_t src, SD_workstation_t dst); double SD_workstation_get_power(SD_workstation_t workstation); double SD_workstation_get_available_power(SD_workstation_t workstation); -/* private (called by SD_clean) -void SD_workstation_destroy(SD_workstation_t workstation); -*/ + +/** @} */ /************************** Task handling ************************************/ diff --git a/src/simdag/sd_task.c b/src/simdag/sd_task.c index b534a22783..59530d8507 100644 --- a/src/simdag/sd_task.c +++ b/src/simdag/sd_task.c @@ -54,16 +54,16 @@ e_SD_task_state_t SD_task_get_state(SD_task_t task) { SD_CHECK_INIT_DONE(); xbt_assert0(task != NULL, "Invalid parameter"); - if (task->state_set == sd_global->not_scheduled_task_set) - return SD_NOT_SCHEDULED; if (task->state_set == sd_global->scheduled_task_set) return SD_SCHEDULED; - if (task->state_set == sd_global->ready_task_set) - return SD_READY; - if (task->state_set == sd_global->running_task_set) - return SD_RUNNING; if (task->state_set == sd_global->done_task_set) return SD_DONE; + if (task->state_set == sd_global->running_task_set) + return SD_RUNNING; + if (task->state_set == sd_global->ready_task_set) + return SD_READY; + if (task->state_set == sd_global->not_scheduled_task_set) + return SD_NOT_SCHEDULED; return SD_FAILED; } @@ -87,8 +87,11 @@ void __SD_task_set_state(SD_task_t task, e_SD_task_state_t new_state) { case SD_DONE: task->state_set = sd_global->done_task_set; break; - default: /* SD_FAILED */ + case SD_FAILED: task->state_set = sd_global->failed_task_set; + break; + default: + xbt_assert0(0, "Invalid state"); } xbt_swag_insert(task,task->state_set); diff --git a/src/simdag/sd_workstation.c b/src/simdag/sd_workstation.c index 567cd0bd71..05bf3d3bdc 100644 --- a/src/simdag/sd_workstation.c +++ b/src/simdag/sd_workstation.c @@ -21,7 +21,13 @@ SD_workstation_t __SD_workstation_create(void *surf_workstation, void *data) { return workstation; } -/* Returns a workstation given its name, or NULL if there is no such workstation. +/** @ingroup SD_workstation_management + * @brief Returns a workstation given its name + * + * If there is no such workstation, the function returns NULL. + * + * @param name workstation name + * @return the workstation, or NULL if there is no such workstation */ SD_workstation_t SD_workstation_get_by_name(const char *name) { SD_CHECK_INIT_DONE(); @@ -31,12 +37,19 @@ SD_workstation_t SD_workstation_get_by_name(const char *name) { return xbt_dict_get_or_null(sd_global->workstations, name); } -/* Returns a NULL-terminated array of existing workstations. +/** @ingroup SD_workstation_management + * @brief Returns the workstations list + * + * Use SD_workstation_get_number to known the array size. + * + * @return an array of SD_workstation_t containing all workstations + * @see SD_workstation_get_number */ SD_workstation_t* SD_workstation_get_list(void) { SD_CHECK_INIT_DONE(); + xbt_assert0(SD_workstation_get_number() > 0, "There is no workstation!"); - SD_workstation_t* array = xbt_new0(SD_workstation_t, sd_global->workstation_count + 1); + SD_workstation_t* array = xbt_new0(SD_workstation_t, sd_global->workstation_count); xbt_dict_cursor_t cursor; char *key; @@ -46,19 +59,30 @@ SD_workstation_t* SD_workstation_get_list(void) { xbt_dict_foreach(sd_global->workstations, cursor, key, data) { array[i++] = (SD_workstation_t) data; } - array[i] = NULL; return array; } -/* Returns the number or workstations. +/** @ingroup SD_workstation_management + * @brief Returns the number of workstations + * + * @return the number of existing workstations + * @see SD_workstation_get_list */ int SD_workstation_get_number(void) { SD_CHECK_INIT_DONE(); return sd_global->workstation_count; } -/* Sets the data of a workstation. The new data can be NULL. The old data should have been freed first if it was not NULL. +/** @ingroup SD_workstation_management + * @brief Sets the user data of a workstation + * + * The new data can be NULL. The old data should have been freed first + * if it was not NULL. + * + * @param workstation a workstation + * @param data the new data you want to associate with this workstation + * @see SD_workstation_get_data */ void SD_workstation_set_data(SD_workstation_t workstation, void *data) { SD_CHECK_INIT_DONE(); @@ -66,7 +90,12 @@ void SD_workstation_set_data(SD_workstation_t workstation, void *data) { workstation->data = data; } -/* Returns the data of a workstation. The user data can be NULL. +/** @ingroup SD_workstation_management + * @brief Returns the user data of a workstation + * + * @param workstation a workstation + * @return the user data associated with this workstation (can be NULL) + * @see SD_workstation_set_data */ void* SD_workstation_get_data(SD_workstation_t workstation) { SD_CHECK_INIT_DONE(); @@ -74,7 +103,11 @@ void* SD_workstation_get_data(SD_workstation_t workstation) { return workstation->data; } -/* Returns the name of a workstation. +/** @ingroup SD_workstation_management + * @brief Returns the name of a workstation + * + * @param workstation a workstation + * @return the name of this workstation (cannot be NULL) */ const char* SD_workstation_get_name(SD_workstation_t workstation) { SD_CHECK_INIT_DONE(); @@ -82,7 +115,15 @@ const char* SD_workstation_get_name(SD_workstation_t workstation) { return surf_workstation_resource->common_public->get_resource_name(workstation->surf_workstation); } -/* Returns an new array of links representating the route between two workstations. +/** @ingroup SD_workstation_management + * @brief Returns the route between two workstations + * + * Use SD_workstation_route_get_size to known the array size. + * + * @param src a workstation + * @param dst another workstation + * @return a new array of SD_link_t representating the route between these two workstations + * @see SD_workstation_route_get_size */ SD_link_t* SD_workstation_route_get_list(SD_workstation_t src, SD_workstation_t dst) { SD_CHECK_INIT_DONE(); @@ -104,7 +145,13 @@ SD_link_t* SD_workstation_route_get_list(SD_workstation_t src, SD_workstation_t return route; } -/* Returns the number of links on the route between two workstations. +/** @ingroup SD_workstation_management + * @brief Returns the number of links on the route between two workstations + * + * @param src a workstation + * @param dst another workstation + * @return the number of links on the route between these two workstations + * @see SD_workstation_route_get_list */ int SD_workstation_route_get_size(SD_workstation_t src, SD_workstation_t dst) { SD_CHECK_INIT_DONE(); @@ -112,7 +159,12 @@ int SD_workstation_route_get_size(SD_workstation_t src, SD_workstation_t dst) { get_route_size(src->surf_workstation, dst->surf_workstation); } -/* Returns the total power of a workstation. +/** @ingroup SD_workstation_management + * @brief Returns the total power of a workstation + * + * @param workstation a workstation + * @return the total power of this workstation + * @see SD_workstation_get_available_power */ double SD_workstation_get_power(SD_workstation_t workstation) { SD_CHECK_INIT_DONE(); @@ -120,7 +172,12 @@ double SD_workstation_get_power(SD_workstation_t workstation) { return surf_workstation_resource->extension_public->get_speed(workstation->surf_workstation, 1.0); } -/* Returns the proportion of available power in a workstation (normally a number between 0 and 1). +/** @ingroup SD_workstation_management + * @brief Returns the proportion of available power in a workstation + * + * @param workstation a workstation + * @return the proportion of power currently available in this workstation (normally a number between 0 and 1) + * @see SD_workstation_get_power */ double SD_workstation_get_available_power(SD_workstation_t workstation) { SD_CHECK_INIT_DONE(); @@ -128,7 +185,7 @@ double SD_workstation_get_available_power(SD_workstation_t workstation) { return surf_workstation_resource->extension_public->get_available_speed(workstation->surf_workstation); } -/* Destroys a workstation. The user data (if any) should have been destroyed first. +/* Destroys a workstation. */ void __SD_workstation_destroy(void *workstation) { SD_CHECK_INIT_DONE(); -- 2.20.1