a lot of comments in node_sched.h

src/sched_policies/node_sched.h

@@ -8,50 +8,104 @@
 #include <hwloc.h>
 #endif
 
+/* struct _starpu_sched_node are scheduler modules, a scheduler is a tree-like
+ * structure of them, some parts of scheduler can be shared by several contexes
+ * to perform some local optimisations, so, for all nodes, a list of father is
+ * defined indexed by sched_ctx_id
+ * 
+ * they embed there specialised method in a pseudo object-style, so calls are like node->push_task(node,task)
+ *
+ */
 struct _starpu_sched_node
 {
+	/* node->push_task(node, task)
+	 * this function is called to push a task on node subtree, this can either
+	 * perform a recursive call on a child or store the task in the node, then
+	 * it will be returned by a further pop_task call
+	 *
+	 * the caller must ensure that node is able to execute task
+	 */
 	int (*push_task)(struct _starpu_sched_node *,
 			 struct starpu_task *);
+	/* this function is called by workers to get a task on them fathers
+	 * this function should first return a localy stored task or perform
+	 * a recursive call on father
+	 *
+	 * a default implementation simply do a recursive call on father
+	 */
 	struct starpu_task * (*pop_task)(struct _starpu_sched_node *,
 					 unsigned sched_ctx_id);
 
+	/* this function notify underlying worker that a task as been pushed
+	 * and would be returned by a pop_task call
+	 * it should be called each time a node localy store a task
+	 * 
+	 * default implementation simply perform a recursive call on childrens
+	 * this function can be called by a worker as it doesn't try to wake up himself
+	 */
 	void (*available)(struct _starpu_sched_node *);
 	
-	/* this function is an heuristic that compute load of subtree */
+	/* this function is an heuristic that compute load of subtree, basicaly
+	 * it compute
+	 * estimated_load(node) = sum(estimated_load(node_childs)) +
+	 *          nb_local_tasks / average(relative_speedup(underlying_worker))
+	 */
 	double (*estimated_load)(struct _starpu_sched_node * node);
 
+	/* this function return a struct _starpu_task_execute_preds defined lower
+	 * wich basicaly give predictions for a task execution a call on 
+	 * homogeneous (with all workers of the same arch) node is optimised
+	 */
 	struct _starpu_task_execute_preds (*estimated_execute_preds)(struct _starpu_sched_node * node,
 								     struct starpu_task * task);
-	
+	/* the numbers of node's childs
+	 */
 	int nchilds;
+	/* the vector of node's childs
+	 */
 	struct _starpu_sched_node ** childs;
-
-	//the set of workers in the node's subtree
-	struct _starpu_bitmap * workers;
-	//is_homogeneous is 0 iff workers in the node's subtree are heterogeneous,
-	//this field is set and updated automaticaly, you shouldn't write on it
-	int is_homogeneous;
-
-	void * data;
 	/* may be shared by several contexts
 	 * so we need several fathers
 	 */
 	struct _starpu_sched_node * fathers[STARPU_NMAX_SCHED_CTXS];
+	/* the set of workers in the node's subtree
+	 */
+	struct _starpu_bitmap * workers;
+	/* is_homogeneous is 0 iff workers in the node's subtree are heterogeneous,
+	 * this field is set and updated automaticaly, you shouldn't write on it
+	 */
+	int is_homogeneous;
+	/* node's private data, no restriction on use
+	 */
+	void * data;
 
-	/* this function is called after all childs has been set
+	/* this function is called after all childs has been set, and the
+	 * workers member was filled, can be used to init data, or anything you want
 	 */
 	void (*init_data)(struct _starpu_sched_node *);
 	/* this function is called to free data allocated by init_data 
+	 * just before the call of _starpu_sched_node_destroy(node)
 	 */
 	void (*deinit_data)(struct _starpu_sched_node *);
 
 #ifdef STARPU_HAVE_HWLOC
+	/* in case of a hierarchical scheduler, this is set to the part of
+	 * topology that is binded to this node, eg: a numa node for a ws
+	 * node that would balance load between underlying sockets
+	 */
 	hwloc_obj_t obj;
 #endif
 };
 
+/* this structure is only returned by estimated_execute_preds and give
+ * predictions on task computations
+ */
 struct _starpu_task_execute_preds
 {
+	/* if several value are possible for state member,
+	 * in order of priority :
+	 * CALIBRATING, PERF_MODEL, NO_PERF_MODEL, CANNOT_EXECUTE
+	 */
 	enum {CANNOT_EXECUTE = 0, CALIBRATING , NO_PERF_MODEL, PERF_MODEL} state;
 
 	/* archtype and nimpl is set to
@@ -74,7 +128,10 @@ struct _starpu_sched_tree
 {
 	struct _starpu_sched_node * root;
 	struct _starpu_bitmap * workers;
-	//this lock is used to protect the scheduler during modifications of his structure
+	/* this lock is used to protect the scheduler,
+	 * it is taken in read mode pushing a task
+	 * and in write mode for adding or removing workers
+	 */
 	starpu_pthread_rwlock_t lock;
 };