From: Christophe Thiéry <christopho128@gmail.com>
Date: Mon, 7 Nov 2011 18:19:24 +0000 (+0100)
Subject: Add comments about who should or shouldn't call MSG_task_destroy
X-Git-Tag: exp_20120216~450
X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/50400654d17b3c623e7ae8653690142e52c6498b

Add comments about who should or shouldn't call MSG_task_destroy
---

diff --git a/src/msg/task.c b/src/msg/task.c
index 877467c1cd..68fd8a320a 100644
--- a/src/msg/task.c
+++ b/src/msg/task.c
@@ -152,7 +152,13 @@ void MSG_task_set_name(m_task_t task, const char *name)
  * \brief Destroy a #m_task_t.
  *
  * Destructor for #m_task_t. Note that you should free user data, if any, \b 
-   before calling this function.
+ * before calling this function.
+ *
+ * Only the process that owns the task can destroy it.
+ * The owner changes after a successful send.
+ * If a task is successfully sent, the receiver becomes the owner and is
+ * supposed to destroy it. The sender should not use it anymore.
+ * If the task failed to be sent, the sender remains the owner of the task.
  */
 MSG_error_t MSG_task_destroy(m_task_t task)
 {
@@ -160,7 +166,7 @@ MSG_error_t MSG_task_destroy(m_task_t task)
   xbt_assert((task != NULL), "Invalid parameter");
 
   if (task->simdata->isused) {
-    /* the task is still being used, it may be an unfinished dsend */
+    /* the task is being sent or executed: cancel it first */
     MSG_task_cancel(task);
   }
 #ifdef HAVE_TRACING