Comments added in the task_bundle header file.

include/starpu_task_bundle.h

@@ -39,23 +39,99 @@ struct starpu_task;
  */
 typedef struct _starpu_task_bundle *starpu_task_bundle_t;
 
-/* Initialize a task bundle */
-void starpu_task_bundle_init(starpu_task_bundle_t *bundle);
+/* starpu_task_bundle_create
+ * =========================
+ * Purpose
+ * =======
+ * Factory function creating a bundle, when the call return,
+ * memory needed is allocated and the bundle is ready to use.
+ *
+ * Arguments
+ * =========
+ * bundle		(output)
+ * 			Bundle to create and initialize.
+ */
+void starpu_task_bundle_create(starpu_task_bundle_t *bundle);
 
-/* Deinitialize a bundle. */
-void starpu_task_bundle_deinit(starpu_task_bundle_t bundle);
+/* starpu_task_bundle_destroy
+ * ==========================
+ * Purpose
+ * =======
+ * Destroy and deinitialize a bundle,
+ * memory previoulsy allocated is freed.
+ *
+ * Arguments
+ * =========
+ * bundle		(input)
+ * 			Bundle to destroy.
+ */
+void starpu_task_bundle_destroy(starpu_task_bundle_t bundle);
 
-/* Insert a task into a bundle. */
+/* starpu_task_bundle_insert
+ * =========================
+ * Purpose
+ * =======
+ * Insert a task in a bundle. Until the task is removed from the bundle
+ * its expected length and data transfer time will be considered along
+ * those of the other tasks of the bundle.
+ * This function mustn't be called if the bundle is already closed and/or
+ * the task is already submitted.
+ *
+ * Return value
+ * ============
+ * On success, it returns 0.
+ * There are two cases of error :
+ * 	- if the bundle is already closed it returns -EPERM
+ * 	- if the task was already submitted it return -EINVAL.
+ *
+ * Arguments
+ * =========
+ * bundle		(input)
+ * 			Bundle where to insert the task.
+ *
+ * task			(input)
+ * 			Task to insert.
+ */
 int starpu_task_bundle_insert(starpu_task_bundle_t bundle, struct starpu_task *task);
 
-/* Remove a task from a bundle. This method must be called with bundle->mutex
- * hold. This function returns 0 if the task was found, -ENOENT if the element
- * was not found, 1 if the element is found and if the list was deinitialized
- * because it became empty. */
+/* starpu_task_bundle_remove
+ * =========================
+ * Purpose
+ * =======
+ * Remove the tasks passed as argument from the bundle.
+ * Of course the task must have been previously inserted in the bundle.
+ * This function mustn't be called if the bundle is already closed and/or
+ * the task is already submitted. Doing so would result in undefined behaviour.
+ *
+ * Return value
+ * ============
+ * On success, it returns 0.
+ * If the bundle is already closed it returns -ENOENT.
+ *
+ * Arguments
+ * =========
+ * bundle		(input)
+ * 			Bundle containing the task.
+ *
+ * task			(input)
+ * 			The task to remove.
+ */
 int starpu_task_bundle_remove(starpu_task_bundle_t bundle, struct starpu_task *task);
 
-/* Close a bundle. No task can be added to a closed bundle. A closed bundle
- * automatically gets deinitialized when it becomes empty. */
+/* starpu_task_bundle_close
+ * =========================
+ * Purpose
+ * =======
+ * Calling this functions informs the runtime that the user
+ * won't modify the bundle anymore, it means no more
+ * inserting or removing a task.
+ * Thus the runtime can destroy it when needed.
+ *
+ * Arguments
+ * =========
+ * bundle		(input)
+ * 			Bundle to close.
+ */
 void starpu_task_bundle_close(starpu_task_bundle_t bundle);
 
 /* Return the expected duration of the entire task bundle in µs. */

src/core/task_bundle.c

@@ -24,7 +24,7 @@
 #include <common/list.h>
 
 /* Initialize a task bundle */
-void starpu_task_bundle_init(starpu_task_bundle_t *bundle)
+void starpu_task_bundle_create(starpu_task_bundle_t *bundle)
 {
 	*bundle = (starpu_task_bundle_t) malloc(sizeof(struct _starpu_task_bundle));
 	STARPU_ASSERT(*bundle);
@@ -39,7 +39,7 @@ void starpu_task_bundle_init(starpu_task_bundle_t *bundle)
 
 /* Deinitialize a bundle. In case the destroy flag is set, the bundle structure
  * is freed too. */
-void starpu_task_bundle_deinit(starpu_task_bundle_t bundle)
+void starpu_task_bundle_destroy(starpu_task_bundle_t bundle)
 {
 	/* Remove all entries from the bundle (which is likely to be empty) */
 	while (bundle->list)
@@ -132,8 +132,8 @@ int starpu_task_bundle_remove(starpu_task_bundle_t bundle, struct starpu_task *t
 		if (bundle->closed && bundle->list == NULL)
 		{
 			_STARPU_PTHREAD_MUTEX_UNLOCK(&bundle->mutex);
-			starpu_task_bundle_deinit(bundle);
-			return 1;
+			starpu_task_bundle_destroy(bundle);
+			return 0;
 		}
 
 		_STARPU_PTHREAD_MUTEX_UNLOCK(&bundle->mutex);
@@ -174,7 +174,7 @@ void starpu_task_bundle_close(starpu_task_bundle_t bundle)
 	if (bundle->list == NULL)
 	{
 		_STARPU_PTHREAD_MUTEX_UNLOCK(&bundle->mutex);
-		starpu_task_bundle_deinit(bundle);
+		starpu_task_bundle_destroy(bundle);
 		return;
 	}
 

src/core/task_bundle.h

@@ -53,9 +53,13 @@ struct _starpu_task_bundle_entry
  *
  * Fields
  * ======
- * task			Pointer to the task structure.
+ * mutex		Mutex protecting the structure.
  *
- * next			Pointer to the next element in the linked list.
+ * list			Array of tasks included in the bundle.
+ *
+ * closed		Used to know if the user is still willing to
+ * 			add/remove some tasks in the bundle. Especially useful for
+ * 			the runtime to know whether it is safe to destroy a bundle.
  */
 
 struct _starpu_task_bundle
@@ -67,10 +71,8 @@ struct _starpu_task_bundle
 	pthread_mutex_t mutex;
 #endif
 
-	/* list of tasks */
 	struct _starpu_task_bundle_entry *list;
 
-	/* Is the bundle closed ? */
 	int closed;
 };
 

src/sched_policies/detect_combined_workers.c

@@ -24,7 +24,7 @@
 #ifdef STARPU_HAVE_HWLOC
 #include <hwloc.h>
 
-/* struct _starpi_tree
+/* struct _starpu_tree
  * ==================
  * Purpose
  * =======