From: thiery Date: Tue, 27 Jun 2006 12:33:59 +0000 (+0000) Subject: Update SimDag documentation: main page and datatypes X-Git-Tag: v3.3~2910 X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/5039b5173e59b6da9f849e09d9de348adbefd25e Update SimDag documentation: main page and datatypes git-svn-id: svn+ssh://scm.gforge.inria.fr/svn/simgrid/simgrid/trunk@2448 48e7efb5-ca39-0410-a469-dd3cf9ba447f --- diff --git a/doc/module-sd.doc b/doc/module-sd.doc index 95179f622d..8de54064d8 100644 --- a/doc/module-sd.doc +++ b/doc/module-sd.doc @@ -22,7 +22,7 @@ \ingroup SD_API */ /** \addtogroup SD_task_management \ingroup SD_API */ -/** \addtogroup SD_dependency_functions +/** \addtogroup SD_dependency_management \ingroup SD_API */ /** \addtogroup SD_platform_management \ingroup SD_API */ diff --git a/doc/modules.doc b/doc/modules.doc index d04280ef35..7163b6ebf7 100644 --- a/doc/modules.doc +++ b/doc/modules.doc @@ -37,9 +37,11 @@ \section MSG_who Who should use this (and who shouldn't) You should use this module if you want to study some heuristics for a - given problem you don't really want to implement. If you want to get a - real implementation of your solution, have a look at the \ref GRAS_API - programming environment. If you want to study an existing MPI program, + given problem you don't really want to implement. + If you want to use DAGs, have a look at the \ref SD_API programming + environment. + If you want to get a real implementation of your solution, have a look + at the \ref GRAS_API one. If you want to study an existing MPI program, have a look at the \ref SMPI_API one. If none of those programming environments fits your needs, you may consider implementing your own directly on top of \ref SURF_API (but you probably want to contact us @@ -68,7 +70,7 @@ may eventually be distributed. If you just want to study some heuristics for a given problem you don't want to implement really (ie, if your result would be a theorem), have a - look at the \ref MSG_API one. + look at the \ref MSG_API one, or the \ref SD_API one if you need to use DAGs. If you want to study an existing MPI program, have a look at the \ref SMPI_API one. If none of those programming environments fits your needs, you may @@ -104,7 +106,7 @@ \ref GRAS_API environment. If you want to study some heuristics for a given problem (and if your goal is to produce theorems, not code), have a look at the \ref MSG_API - environment. + environment, or the \ref SD_API one if you need to use DAGs. If none of those programming environments fits your needs, you may consider implementing your own directly on top of \ref SURF_API (but you probably want to contact us before). @@ -116,10 +118,25 @@ \ingroup SimGrid_API \brief Programming environment for DAG applications - PLACEHOLDER - + 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 (SURF) was implemented. SURF + 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 SURF. + \section SD_who Who should use this (and who shouldn't) - PLACEHOLDER -*/ + You should use this programming environment of the SimGrid suite if you want + to study algorithms and heuristics with DAGs of parallel tasks. + If you don't need to use DAGs for your simulation, have a look at the + \ref MSG_API programming environment. + If you want to implement a real distributed application, have a look at the + \ref GRAS_API programming environment. + If you want to study an existing MPI program, have a look at the + \ref SMPI_API one. + If none of those programming environments fits your needs, you may + consider implementing your own directly on top of \ref SURF_API (but you + probably want to contact us before). +*/ diff --git a/include/simdag/datatypes.h b/include/simdag/datatypes.h index 2904bd158f..90560351bb 100644 --- a/include/simdag/datatypes.h +++ b/include/simdag/datatypes.h @@ -3,34 +3,47 @@ /** @brief Workstation datatype @ingroup SD_datatypes_management - @{ */ + + 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_management */ typedef struct SD_workstation *SD_workstation_t; -/** @} */ /** @brief Link datatype @ingroup SD_datatypes_management - @{ */ + + A link is a network node represented as a name, a current + bandwidth and a current latency. A route is a list of + links between two workstations. + + @see SD_link_management */ typedef struct SD_link *SD_link_t; -/** @} */ /** @brief Task datatype @ingroup SD_datatypes_management - @{ */ + + A task is some computing amount that can be executed + in parallel on several workstations. A task may depend on other + tasks, this means that the task cannot start until the other tasks are done. + Each task has a \ref e_SD_task_state_t "state" indicating whether the task is scheduled, running, done, etc. + + @see SD_task_management */ typedef struct SD_task *SD_task_t; -/** @} */ /** @brief Task states @ingroup SD_datatypes_management - @{ */ + + @see SD_task_management */ typedef enum { SD_NOT_SCHEDULED = 0, /**< @brief Initial state (not valid for SD_watch and SD_unwatch). */ SD_SCHEDULED = 0x0001, /**< @brief A task becomes SD_SCHEDULED when you call function SD_task_schedule. SD_simulate will execute it when it becomes SD_READY. */ SD_READY = 0x0002, /**< @brief A scheduled task becomes ready as soon as its dependencies are satisfied. */ - SD_RUNNING = 0x0004, /**< @brief A ready task becomes running in SD_simulate. */ + SD_RUNNING = 0x0004, /**< @brief When a task is ready, it is launched in the function SD_simulate and becomes SD_RUNNING. */ SD_DONE = 0x0008, /**< @brief The task is successfuly finished. */ - SD_FAILED = 0x0010 /**< @brief A problem occured. */ + SD_FAILED = 0x0010 /**< @brief A problem occured during the execution of the task. */ } e_SD_task_state_t; -/** @} */ #endif diff --git a/src/simdag/sd_task.c b/src/simdag/sd_task.c index 5a64783d12..dbafd2b479 100644 --- a/src/simdag/sd_task.c +++ b/src/simdag/sd_task.c @@ -154,7 +154,7 @@ void __SD_print_dependencies(SD_task_t task) { /* Destroys a dependency between two tasks. */ -static void __SD_task_destroy_dependency(void *dependency) { +static void __SD_task_dependency_destroy(void *dependency) { if (((SD_dependency_t) dependency)->name != NULL) xbt_free(((SD_dependency_t) dependency)->name); xbt_free(dependency); @@ -224,7 +224,7 @@ void SD_task_dependency_remove(SD_task_t src, SD_task_t dst) { xbt_dynar_get_cpy(dynar, i, &dependency); if (dependency->src == src) { xbt_dynar_remove_at(dynar, i, NULL); - __SD_task_destroy_dependency(dependency); + __SD_task_dependency_destroy(dependency); found = 1; } }