Small cleanups in the public headers

include/starpu-data-interfaces.h

@@ -193,16 +193,6 @@ size_t starpu_get_bcsr_elemsize(starpu_data_handle);
 
 unsigned starpu_get_handle_interface_id(starpu_data_handle);
 
-#if 0
-typedef union {
-	starpu_blas_interface_t blas;	/* dense BLAS representation */
-	starpu_block_interface_t block;	/* BLOCK interface for 3D dense blocks */
-	starpu_vector_interface_t vector; /* continuous vector */
-	starpu_csr_interface_t csr;	/* compressed sparse row */
-	starpu_csc_interface_t csc; 	/* compressed sparse column */
-	starpu_bcsr_interface_t bcsr;	/* blocked compressed sparse row */
-	uint8_t pad[64];
-} starpu_data_interface_t;
 #endif
 
 #ifdef __cplusplus

include/starpu-task.h

@@ -177,8 +177,21 @@ void starpu_tag_notify_from_apps(starpu_tag_t id);
 /* To release resources, tags should be freed after use */
 void starpu_tag_remove(starpu_tag_t id);
 
+/* Initialize a task structure with default values. */
 void starpu_task_init(struct starpu_task *task);
+
+/* Allocate a task structure and initialize it with default values. Tasks
+ * allocated dynamically with starpu_task_create are automatically liberated
+ * when the task is terminated. If the destroy flag is explicitely unset, the
+ * ressources used by the task are liberated by calling starpu_task_destroy.
+ * */
 struct starpu_task *starpu_task_create(void);
+
+/* Liberate the ressource allocated during starpu_task_create. This function
+ * can be called automatically after the execution of a task by setting the
+ * "destroy" flag of the starpu_task structure (default behaviour). Calling
+ * this function on a statically allocated task results in an undefined
+ * behaviour. */
 void starpu_task_destroy(struct starpu_task *task);
 int starpu_submit_task(struct starpu_task *task);
 
@@ -189,6 +202,8 @@ int starpu_submit_task(struct starpu_task *task);
  * indicates that the waited task was either synchronous or detached. */
 int starpu_wait_task(struct starpu_task *task);
 
+/* This function waits until all the tasks that were already submitted have
+ * been executed. */
 int starpu_wait_all_tasks(void);
 
 void starpu_display_codelet_stats(struct starpu_codelet_t *cl);

include/starpu-util.h

@@ -184,12 +184,6 @@ extern "C" {
 
 #endif // USE_CUDA
 
-
-
-#define STARPU_SUCCESS	0
-#define STARPU_TRYAGAIN	1
-#define STARPU_FATAL	2
-
 static inline int starpu_get_env_number(const char *str)
 {
 	char *strval;
@@ -213,14 +207,22 @@ static inline int starpu_get_env_number(const char *str)
 	}
 }
 
+/* Add an event in the execution trace if FxT is enabled */
 void starpu_trace_user_event(unsigned code);
 
 /* Some helper functions for application using CUBLAS kernels */
 void starpu_helper_init_cublas(void);
 void starpu_helper_shutdown_cublas(void);
+
+/* Call func(arg) on every worker matching the "where" mask (eg. CUDA|CORE to
+ * execute the function on every CPUs and every CUDA devices). This function is
+ * synchronous, but the different workers may execute the function in parallel.
+ * */
 void starpu_execute_on_each_worker(void (*func)(void *), void *arg, uint32_t where);
 
 #ifdef USE_CUDA
+/* In case the application is using streams, these functions will
+ * repespectively create, and return, a unique stream for every GPU worker. */
 void starpu_helper_create_per_gpu_streams(void);
 cudaStream_t *starpu_helper_get_local_stream(void);
 #endif