include: remove documentation as it is already defined elsewhere

include/starpu_data.h

@@ -48,21 +48,10 @@ struct starpu_data_descr
 
 struct starpu_data_interface_ops;
 
-/* Destroy the data handle, in case we don't need to update the value of the
- * data in the home node, we can use starpu_data_unregister_no_coherency
- * instead. */
 void starpu_data_unregister(starpu_data_handle_t handle);
 void starpu_data_unregister_no_coherency(starpu_data_handle_t handle);
-
-/* Destroy the data handle once it is not needed anymore by any submitted task.
- * No coherency is assumed.
- */
 void starpu_data_unregister_submit(starpu_data_handle_t handle);
-
-/* Destroy all data replicates. After data invalidation, the first access to
- * the handle must be performed in write-only mode. */
 void starpu_data_invalidate(starpu_data_handle_t handle);
-/* Same, but waits for previous task completion */
 void starpu_data_invalidate_submit(starpu_data_handle_t handle);
 
 void starpu_data_advise_as_important(starpu_data_handle_t handle, unsigned is_important);
@@ -98,7 +87,6 @@ int starpu_data_request_allocation(starpu_data_handle_t handle, unsigned node);
 
 int starpu_data_prefetch_on_node(starpu_data_handle_t handle, unsigned node, unsigned async);
 
-
 enum starpu_node_kind
 {
 	STARPU_UNUSED     = 0x00,
@@ -118,11 +106,6 @@ unsigned starpu_worker_get_memory_node(unsigned workerid);
 unsigned starpu_memory_nodes_get_count(void);
 enum starpu_node_kind starpu_node_get_kind(unsigned node);
 
-
-/* It is possible to associate a mask to a piece of data (and its children) so
- * that when it is modified, it is automatically transfered into those memory
- * node. For instance a (1<<0) write-through mask means that the CUDA workers will
- * commit their changes in main memory (node 0). */
 void starpu_data_set_wt_mask(starpu_data_handle_t handle, uint32_t wt_mask);
 
 void starpu_data_set_sequential_consistency_flag(starpu_data_handle_t handle, unsigned flag);
@@ -130,7 +113,6 @@ unsigned starpu_data_get_sequential_consistency_flag(starpu_data_handle_t handle
 unsigned starpu_data_get_default_sequential_consistency_flag(void);
 void starpu_data_set_default_sequential_consistency_flag(unsigned flag);
 
-/* Query the status of the handle on the specified memory node. */
 void starpu_data_query_status(starpu_data_handle_t handle, int memory_node, int *is_allocated, int *is_valid, int *is_requested);
 
 struct starpu_codelet;

include/starpu_perfmodel.h

@@ -72,40 +72,18 @@ _Static_assert(STARPU_MIC_DEFAULT < STARPU_SCC_DEFAULT,
 
 struct starpu_perfmodel_history_entry
 {
-	//double measured;
-
-	/* mean_n = 1/n sum */
 	double mean;
-
-	/* n dev_n = sum2 - 1/n (sum)^2 */
 	double deviation;
-
-	/* sum of samples */
 	double sum;
-
-	/* sum of samples^2 */
 	double sum2;
-
-//	/* sum of ln(measured) */
-//	double sumlny;
-//
-//	/* sum of ln(size) */
-//	double sumlnx;
-//	double sumlnx2;
-//
-//	/* sum of ln(size) ln(measured) */
-//	double sumlnxlny;
-//
 	unsigned nsample;
-
 	uint32_t footprint;
 #ifdef STARPU_HAVE_WINDOWS
-	unsigned size; /* in bytes */
+	unsigned size;
 #else
-	size_t size; /* in bytes */
+	size_t size;
 #endif
-
-	double flops; /* Provided by the application */
+	double flops;
 };
 
 struct starpu_perfmodel_history_list
@@ -116,26 +94,20 @@ struct starpu_perfmodel_history_list
 
 struct starpu_perfmodel_regression_model
 {
-	/* sum of ln(measured) */
 	double sumlny;
 
-	/* sum of ln(size) */
 	double sumlnx;
 	double sumlnx2;
 
-	/* minimum/maximum(size) */
 	unsigned long minx;
 	unsigned long maxx;
 
-	/* sum of ln(size) ln(measured) */
 	double sumlnxlny;
 
-	/* y = alpha size ^ beta */
 	double alpha;
 	double beta;
 	unsigned valid;
 
-	/* y = a size ^b + c */
 	double a, b, c;
 	unsigned nl_valid;
 
@@ -148,11 +120,10 @@ struct starpu_perfmodel_history_table;
 
 struct starpu_perfmodel_per_arch
 {
-	double (*cost_model)(struct starpu_data_descr *t) STARPU_DEPRECATED; /* returns expected duration in µs */
-	double (*cost_function)(struct starpu_task *task, enum starpu_perfmodel_archtype arch, unsigned nimpl); /* returns expected duration in µs */
+	double (*cost_model)(struct starpu_data_descr *t) STARPU_DEPRECATED;
+	double (*cost_function)(struct starpu_task *task, enum starpu_perfmodel_archtype arch, unsigned nimpl);
 	size_t (*size_base)(struct starpu_task *, enum starpu_perfmodel_archtype arch, unsigned nimpl);
 
-	/* internal variables */
 	struct starpu_perfmodel_history_table *history;
 	struct starpu_perfmodel_history_list *list;
 	struct starpu_perfmodel_regression_model regression;

include/starpu_scheduler.h

@@ -27,53 +27,23 @@ extern "C"
 
 struct starpu_task;
 
-/* This structure contains all the methods that implement a scheduling policy.
- * An application may specify which scheduling strategy in the "sched_policy"
- * field of the starpu_conf structure passed to the starpu_init function. */
 struct starpu_sched_policy
 {
-	/* Initialize the scheduling policy. */
 	void (*init_sched)(unsigned sched_ctx_id);
-
-	/* Cleanup the scheduling policy. */
 	void (*deinit_sched)(unsigned sched_ctx_id);
 
-	/* Insert a task into the scheduler. */
 	int (*push_task)(struct starpu_task *);
-
-	/* Notify the scheduler that a task was directly pushed to the worker
-	 * without going through the scheduler. This method is called when a
-	 * task is explicitely assigned to a worker. This method therefore
-	 * permits to keep the timing state of the scheduler coherent even
-	 * when StarPU bypasses the scheduling strategy. */
 	void (*push_task_notify)(struct starpu_task *, int workerid, unsigned sched_ctx_id);
-
-	/* Get a task from the scheduler. The mutex associated to the worker is
-	 * already taken when this method is called. */
 	struct starpu_task *(*pop_task)(unsigned sched_ctx_id);
-
-	 /* Remove all available tasks from the scheduler (tasks are chained by
-	  * the means of the prev and next fields of the starpu_task
-	  * structure). The mutex associated to the worker is already taken
-	  * when this method is called. */
 	struct starpu_task *(*pop_every_task)(unsigned sched_ctx_id);
 
-	/* This method is called every time a task is starting. (optional) */
 	void (*pre_exec_hook)(struct starpu_task *);
-
-	/* This method is called every time a task has been executed. (optional) */
 	void (*post_exec_hook)(struct starpu_task *);
 
-	/* Initialize scheduling structures corresponding to each worker. */
 	void (*add_workers)(unsigned sched_ctx_id, int *workerids, unsigned nworkers);
-
-	/* Deinitialize scheduling structures corresponding to each worker. */
 	void (*remove_workers)(unsigned sched_ctx_id, int *workerids, unsigned nworkers);
 
-	/* Name of the policy (optionnal) */
 	const char *policy_name;
-
-	/* Description of the policy (optionnal) */
 	const char *policy_description;
 };
 

include/starpu_task.h

@@ -77,20 +77,14 @@ typedef starpu_scc_kernel_t (*starpu_scc_func_t)(void);
 #define STARPU_MULTIPLE_CUDA_IMPLEMENTATIONS   ((starpu_cuda_func_t) -1)
 #define STARPU_MULTIPLE_OPENCL_IMPLEMENTATIONS ((starpu_opencl_func_t) -1)
 
-/*
- * A codelet describes the various function
- * that may be called from a worker
- */
 struct starpu_task;
 struct starpu_codelet
 {
-	/* where can it be performed ? */
 	uint32_t where;
 	int (*can_execute)(unsigned workerid, struct starpu_task *task, unsigned nimpl);
 	enum starpu_codelet_type type;
 	int max_parallelism;
 
-	/* the different implementations of the codelet */
 	starpu_cpu_func_t cpu_func STARPU_DEPRECATED;
 	starpu_cuda_func_t cuda_func STARPU_DEPRECATED;
 	starpu_opencl_func_t opencl_func STARPU_DEPRECATED;
@@ -103,21 +97,13 @@ struct starpu_codelet
 
 	char *cpu_funcs_name[STARPU_MAXIMPLEMENTATIONS];
 
-	/* how many buffers do the codelet takes as argument ? */
 	unsigned nbuffers;
-	/* which are the access modes for these buffers */
 	enum starpu_data_access_mode modes[STARPU_NMAXBUFS];
 	enum starpu_data_access_mode *dyn_modes;
 
-	/* performance model of the codelet */
 	struct starpu_perfmodel *model;
-	/* consumption model of the codelet.
-	 * In the case of parallel codelets, accounts for all units. */
 	struct starpu_perfmodel *power_model;
 
-	/* statistics collected at runtime: this is filled by StarPU and should
-	 * not be accessed directly (use the starpu_codelet_display_stats
-	 * function instead for instance). */
 	unsigned long per_worker_stats[STARPU_NMAXWORKERS];
 
 	const char *name;
@@ -127,7 +113,6 @@ struct starpu_task
 {
 	struct starpu_codelet *cl;
 
-	/* arguments managed by the DSM */
 	struct starpu_data_descr buffers[STARPU_NMAXBUFS] STARPU_DEPRECATED;
 	starpu_data_handle_t handles[STARPU_NMAXBUFS];
 	void *interfaces[STARPU_NMAXBUFS];
@@ -135,104 +120,51 @@ struct starpu_task
 	starpu_data_handle_t *dyn_handles;
 	void **dyn_interfaces;
 
-	/* arguments not managed by the DSM are given as a buffer */
 	void *cl_arg;
-	/* in case the argument buffer has to be uploaded explicitely */
 	size_t cl_arg_size;
-	/* must StarPU release cl_arg ? - 0 by default */
 	unsigned cl_arg_free;
 
-	/* when the task is done, callback_func(callback_arg) is called */
 	void (*callback_func)(void *);
 	void *callback_arg;
 
-	/* Whether tag_id should be considered */
 	unsigned use_tag;
-	/* Tag associated with this task */
 	starpu_tag_t tag_id;
 
-	/* Whether we should enforce sequential consistency for this task */
 	unsigned sequential_consistency;
 
-	/* options for the task execution */
-	unsigned synchronous; /* if set, a call to push is blocking */
-	int priority; /* STARPU_MAX_PRIO = most important; STARPU_MIN_PRIO = least important */
+	unsigned synchronous;
+	int priority;
 
-	/* in case the task has to be executed on a specific worker */
 	unsigned execute_on_a_specific_worker;
 	unsigned workerid;
 
-	/* Bundle including the task */
 	starpu_task_bundle_t bundle;
 
-	/* If this flag is set, it is not possible to synchronize with the task
-	 * by the means of starpu_task_wait later on. Internal data structures
-	 * are only garanteed to be freed once starpu_task_wait is called if
-	 * that flag is not set. */
 	int detach;
-
-	/* If that flag is set, the task structure will automatically be freed,
-	 * either after the execution of the callback if the task is detached,
-	 * or during starpu_task_wait otherwise. If this flag is not set,
-	 * dynamically allocated data structures will not be freed until
-	 * starpu_task_destroy is called explicitely. Setting this flag for a
-	 * statically allocated task structure will result in undefined
-	 * behaviour. */
 	int destroy;
-
-	/* If this flag is set, the task will be re-submitted to StarPU once it
-	 * has been executed. This flag must not be set if the destroy flag is
-	 * set too. */
 	int regenerate;
 
 	enum starpu_task_status status;
 
-	/* This gets filled when profiling is enabled by using
-	 * starpu_profiling_status_set */
 	struct starpu_profiling_task_info *profiling_info;
 
-	/* Predicted duration of the task in µs. This field is only valid if the
-	 * scheduling strategy uses performance models. */
 	double predicted;
-
-	/* Predicted data transfer duration for the task in µs. This field is
-	 * only valid if the scheduling strategy uses performance models. */
 	double predicted_transfer;
 
-	/* This field are provided for the convenience of the scheduler. */
-	struct starpu_task *prev;
-	struct starpu_task *next;
-
 	unsigned int mf_skip;
 
-	/* this is private to StarPU, do not modify. If the task is allocated
-	 * by hand (without starpu_task_create), this field should be set to
-	 * NULL. */
+	struct starpu_task *prev;
+	struct starpu_task *next;
 	void *starpu_private;
-
-	/* the magic field is set when initialising the task.
-	 * starpu_task_submit will fail if the field does not have the
-	 * right value. This will hence avoid submitting tasks which
-	 * have not been properly initialised.
-	 */
 	int magic;
 
-	/* Scheduling context */
 	unsigned sched_ctx;
-
-  /* Helps the hypervisor monitor the execution of this task */
 	int hypervisor_tag;
-
-	/* Number of flops computed by this tag, used by resource reallocation for contexts */
 	double flops;
 
-	/* Whether the scheduler has pushed the task on some queue */
 	unsigned scheduled;
 };
 
-/* It is possible to initialize statically allocated tasks with this value.
- * This is equivalent to initializing a starpu_task structure with the
- * starpu_task_init function. */
 #define STARPU_TASK_INITIALIZER 			\
 {							\
 	.cl = NULL,					\
@@ -268,90 +200,35 @@ struct starpu_task
 #define STARPU_CODELET_GET_MODE(codelet, i) ((codelet->dyn_modes) ? codelet->dyn_modes[i] : codelet->modes[i])
 #define STARPU_CODELET_SET_MODE(codelet, mode, i) do { if (codelet->dyn_modes) codelet->dyn_modes[i] = mode; else codelet->modes[i] = mode; } while(0)
 
-/*
- * handle task dependencies: it is possible to associate a task with a unique
- * "tag" and to express dependencies between tasks by the means of those tags
- *
- * To do so, fill the tag_id field with a tag number (can be arbitrary) and set
- * use_tag to 1.
- *
- * If starpu_tag_declare_deps is called with that tag number, the task will not
- * be started until the task which wears the declared dependency tags are
- * complete.
- */
-
-/*
- * WARNING ! use with caution ...
- *  In case starpu_tag_declare_deps is passed constant arguments, the caller
- *  must make sure that the constants are casted to starpu_tag_t. Otherwise,
- *  due to integer sizes and argument passing on the stack, the C compiler
- *  might consider the tag *  0x200000003 instead of 0x2 and 0x3 when calling:
- *      "starpu_tag_declare_deps(0x1, 2, 0x2, 0x3)"
- *  Using starpu_tag_declare_deps_array is a way to avoid this problem.
- */
-/* make id depend on the list of ids */
 void starpu_tag_declare_deps(starpu_tag_t id, unsigned ndeps, ...);
 void starpu_tag_declare_deps_array(starpu_tag_t id, unsigned ndeps, starpu_tag_t *array);
 
-/* task depends on the tasks in task array */
 void starpu_task_declare_deps_array(struct starpu_task *task, unsigned ndeps, struct starpu_task *task_array[]);
 
 int starpu_tag_wait(starpu_tag_t id);
 int starpu_tag_wait_array(unsigned ntags, starpu_tag_t *id);
 
-/* The application can feed a tag explicitely */
 void starpu_tag_notify_from_apps(starpu_tag_t id);
 
-/* To reuse a tag not associated with a task */
 void starpu_tag_restart(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);
-
-/* Release all the structures automatically allocated to execute the task. This
- * is called implicitely by starpu_task_destroy, but the task structure itself
- * is not freed. Values previously set by the user remain unchanged.
- * This should be used for statically allocated tasks for instance.
- * It should also be used for submitting the same task several times.
- */
 void starpu_task_clean(struct starpu_task *task);
 
-/* Allocate a task structure and initialize it with default values. Tasks
- * allocated dynamically with starpu_task_create are automatically freed when
- * the task is terminated. If the destroy flag is explicitely unset, the
- * ressources used by the task are freed by calling starpu_task_destroy.
- * */
 struct starpu_task *starpu_task_create(void);
 
-/* Free the ressource allocated during the execution of the task and deallocate
- * the task structure itself. 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_task_submit(struct starpu_task *task) STARPU_WARN_UNUSED_RESULT;
 int starpu_task_submit_to_ctx(struct starpu_task *task, unsigned sched_ctx_id);
 
-/* This function blocks until the task was executed. It is not possible to
- * synchronize with a task more than once. It is not possible to wait
- * synchronous or detached tasks.
- * Upon successful completion, this function returns 0. Otherwise, -EINVAL
- * indicates that the waited task was either synchronous or detached. */
 int starpu_task_wait(struct starpu_task *task) STARPU_WARN_UNUSED_RESULT;
 
-/* This function waits until all the tasks that were already submitted 
- * (to the current context or the global one if there aren't any) have
- * been executed. */
 int starpu_task_wait_for_all(void);
 
-/* This function waits until all the tasks that were already submitted to the 
- * context have been executed */
 int starpu_task_wait_for_all_in_ctx(unsigned sched_ctx_id);
 
-/* This function waits until there is no more ready task. */
 int starpu_task_wait_for_no_ready(void);
 
 int starpu_task_nready(void);
@@ -361,16 +238,10 @@ void starpu_codelet_init(struct starpu_codelet *cl);
 
 void starpu_codelet_display_stats(struct starpu_codelet *cl);
 
-/* Return the task currently executed by the worker, or NULL if this is called
- * either from a thread that is not a task or simply because there is no task
- * being executed at the moment. */
 struct starpu_task *starpu_task_get_current(void);
 
-/* initialise the barrier for the parallel task, st all workers start it 
- * at the same time */
 void starpu_parallel_task_barrier_init(struct starpu_task* task, int workerid);
 
-/* duplicate the given task */
 struct starpu_task *starpu_task_dup(struct starpu_task *task);
 
 void starpu_task_set_implementation(struct starpu_task *task, unsigned impl);

include/starpu_worker.h

@@ -52,7 +52,6 @@ enum starpu_worker_collection_type
 	STARPU_WORKER_LIST
 };
 
-/* generic structure used by the scheduling contexts to iterate the workers */
 struct starpu_worker_collection
 {
 	/* hidden data structure used to memorize the workers */
@@ -91,9 +90,6 @@ unsigned starpu_scc_worker_get_count(void);
 
 unsigned starpu_mic_device_get_count(void);
 
-/* Return the identifier of the thread in case this is associated to a worker.
- * This will return -1 if this function is called directly from the application
- * or if it is a worker in which a single thread controls different devices. */
 int starpu_worker_get_id(void);
 
 int starpu_combined_worker_get_id(void);
@@ -112,9 +108,6 @@ int starpu_worker_get_by_devid(enum starpu_worker_archtype type, int devid);
 
 void starpu_worker_get_name(int id, char *dst, size_t maxlen);
 
-/* This functions returns the device id of the worker associated to an
- *  identifier (as returned by the starpu_worker_get_id() function)
- */
 int starpu_worker_get_devid(int id);
 
 int starpu_worker_get_mp_nodeid(int id);