move documentation from public include file to doxygen file

doc/doxygen/chapters/api/modularized_scheduler.doxy

@@ -1,55 +1,22 @@
-/*! \defgroup API_Modularized_Scheduler Modularized Scheduler Interface
-
-\struct starpu_sched_component
-\ingroup API_Modularized_Scheduler
-This structure represent a scheduler module.
-
-\var starpu_sched_component::push_task
-	push a task in the scheduler module.
-\var starpu_sched_component::pop_task
-	pop a task from the scheduler module, the task returned by this function is executable by the caller
-	It should use starpu_sched_component::fathers[sched_ctx_id] to perform a recursive call.
+/*
+ * This file is part of the StarPU Handbook.
+ * Copyright (C) 2013        Simon Archipoff
+ * Copyright (C) 2009--2011  Universit@'e de Bordeaux
+ * Copyright (C) 2014        Centre National de la Recherche Scientifique
+ * Copyright (C) 2013, 2014  INRIA
+ * See the file version.doxy for copying conditions.
+ */
 
-\var starpu_sched_component::estimated_load
-	is an heuristic to compute load of scheduler module. Basically the number of tasks divided by the sum
-	of relatives speedup of workers available in context.
-\var starpu_sched_component::estimated_end
-	return the time when a worker will enter in starvation. This function is relevant only if the task->predicted
-	member has been set.
-\var starpu_sched_component::nchildren
-	the number of modules downstairs
-\var starpu_sched_component::children
-	modules downstairs
-\var starpu_sched_component::workers
-	this member contain the set of underlying workers
-\var starpu_sched_component::workers_in_ctx
-	this member contain the subset of starpu_sched_component::workers that is currently available in the context
-	The push method should take this member into account.
-\var starpu_sched_component::properties
-	flags starpu_sched_component_properties for things
-\var starpu_sched_component::data
-	data used by the scheduler module
-\var starpu_sched_component::add_child
-	add a child to component
-\var starpu_sched_component::remove_child
-	remove a child from component
-
-\var starpu_sched_component::fathers
-	the array of scheduler module above indexed by scheduling context index
-
-\var starpu_sched_component::notify_change_workers
-	this function is called when starpu_sched_component::workers_in_ctx or starpu_sched_component::workers is changed
-\var starpu_sched_component::deinit_data
-	called by starpu_sched_component_destroy. Should free data allocated during creation
-\var starpu_sched_component::obj
-	the hwloc object associated to scheduler module
+/*! \defgroup API_Modularized_Scheduler Modularized Scheduler Interface
 
 \enum starpu_sched_component_properties
 \ingroup API_Modularized_Scheduler
 flags for starpu_sched_component::properties
-\var STARPU_SCHED_component_HOMOGENEOUS
+\var starpu_sched_component_properties::STARPU_SCHED_COMPONENT_HOMOGENEOUS
+\ingroup API_Modularized_Scheduler
      indicate that all workers have the same starpu_worker_archtype
-\var STARPU_SCHED_component_SINGLE_MEMORY_component
+\var starpu_sched_component_properties::STARPU_SCHED_COMPONENT_SINGLE_MEMORY_NODE
+\ingroup API_Modularized_Scheduler
      indicate that all workers have the same memory component
 
 \def STARPU_SCHED_COMPONENT_IS_HOMOGENEOUS
@@ -59,18 +26,116 @@ flags for starpu_sched_component::properties
 \ingroup API_Modularized_Scheduler
      indicate if all workers have the same memory component
 
+\struct starpu_sched_component
+\ingroup API_Modularized_Scheduler
+This structure represent a scheduler module.  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
+components, a list of parent is defined indexed by sched_ctx_id. They
+embed there specialised method in a pseudo object-style, so calls are
+like component->push_task(component,task)
+
+\var struct starpu_sched_tree *starpu_sched_component::tree
+     The tree containing the component
+\var struct starpu_bitmap *starpu_sched_component::workers
+     this member contain the set of underlying workers
+\var starpu_sched_component::workers_in_ctx
+     this member contain the subset of starpu_sched_component::workers that is currently available in the context
+     The push method should take this member into account.
+     this member is set with :
+     component->workers UNION tree->workers UNION
+     component->child[i]->workers_in_ctx iff exist x such as component->children[i]->parents[x] == component
+\var starpu_sched_component::data
+     private data
+\var starpu_sched_component::nchildren
+     the number of compoments's children
+\var starpu_sched_component::children
+     the vector of component's children
+\var starpu_sched_component::nparents
+     the numbers of component's parents
+\var struct starpu_sched_component **starpu_sched_component::parents
+     the vector of component's parents
+
+\var void(*starpu_sched_component::add_child)(struct starpu_sched_component *component, struct starpu_sched_component *child)
+     add a child to component
+\var void(*starpu_sched_component::remove_child)(struct starpu_sched_component *component, struct starpu_sched_component *child)
+     remove a child from component
+\var void(*starpu_sched_component::add_parent)(struct starpu_sched_component *component, struct starpu_sched_component *parent)
+     todo
+\var void(*starpu_sched_component::remove_parent)(struct starpu_sched_component *component, struct starpu_sched_component *parent)
+     todo
+
+\var int (*starpu_sched_component::push_task)(struct starpu_sched_component *, struct starpu_task *)
+     push a task in the scheduler module. this function is called to
+     push a task on component subtree, this can either perform a
+     recursive call on a child or store the task in the component,
+     then it will be returned by a further pull_task call.
+     the caller must ensure that component is able to execute task.
+\var struct starpu_task * (*starpu_sched_component::pull_task)(struct starpu_sched_component *)
+     pop a task from the scheduler module. this function is called by workers to get a task from their
+     parents. this function should first return a locally stored task
+     or perform a recursive call on the parents.
+     the task returned by this function is executable by the caller
+
+\var int (*starpu_sched_component::can_push)(struct starpu_sched_component *component)
+     This function is called by a component which implements a queue,
+     allowing it to signify to its parents that an empty slot is
+     available in its queue. The basic implementation of this function
+     is a recursive call to its parents, the user have to specify a
+     personally-made function to catch those calls.
+\var void (*starpu_sched_component::can_pull)(struct starpu_sched_component *component)
+     This function allow a component to wake up a worker. It is
+     currently called by component which implements a queue, to
+     signify to its children that a task have been pushed in its local
+     queue, and is available to been popped by a worker, for example.
+     The basic implementation of this function is a recursive call to
+     its children, until at least one worker have been woken up.
+
+\var double (*starpu_sched_component::estimated_load)(struct starpu_sched_component *component)
+	is an heuristic to compute load of scheduler module. Basically the number of tasks divided by the sum
+	of relatives speedup of workers available in context.
+	estimated_load(component) = sum(estimated_load(component_children)) + nb_local_tasks / average(relative_speedup(underlying_worker))
+\var starpu_sched_component::estimated_end
+	return the time when a worker will enter in starvation. This function is relevant only if the task->predicted
+	member has been set.
+
+\var void (*starpu_sched_component::deinit_data)(struct starpu_sched_component *component)
+	called by starpu_sched_component_destroy. Should free data allocated during creation
+\var void (*starpu_sched_component::notify_change_workers)(struct starpu_sched_component *component)
+	this function is called for each component when workers are added or removed from a context
+\var int starpu_sched_component::properties
+	todo
+\var hwloc_obj_t starpu_sched_component::obj
+	the hwloc object associated to scheduler module. points to the
+	part of topology that is binded to this component, eg: a numa
+	node for a ws component that would balance load between
+	underlying sockets
 
 \struct starpu_sched_tree
 \ingroup API_Modularized_Scheduler
 The actual scheduler
-\var starpu_sched_tree::root
+\var struct starpu_sched_component *starpu_sched_tree::root
 	this is the entry module of the scheduler
-\var starpu_sched_tree::workers
+\var struct starpu_bitmap *starpu_sched_tree::workers
 	this is the set of workers available in this context, this value is used to mask workers in modules
-\var starpu_sched_tree::lock
-	this lock protect concurrent access from the hypervisor and the application.
-\var starpu_sched_tree::sched_ctx_id
+\var unsigned starpu_sched_tree::sched_ctx_id
 	the context id of the scheduler
+\var starpu_pthread_mutex_t starpu_sched_tree::lock
+	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
+\var struct starpu_sched_component *starpu_sched_tree::worker_components[STARPU_NMAXWORKERS]
+     	worker components
+
+\fn struct starpu_sched_tree *starpu_sched_tree_create(unsigned sched_ctx_id)
+\ingroup API_Modularized_Scheduler
+	 create a empty initialized starpu_sched_tree
+
+\fn void starpu_sched_tree_destroy(struct starpu_sched_tree *tree)
+\ingroup API_Modularized_Scheduler
+	 destroy tree and free all non shared component in it.
+
+
 
 \fn struct starpu_sched_component *starpu_sched_component_create(struct starpu_sched_tree *tree)
 \ingroup API_Modularized_Scheduler
@@ -83,7 +148,6 @@ The actual scheduler
 	.notify_change_workers does nothing
 	.deinit_data does nothing
 
-
 \fn void starpu_sched_component_destroy(struct starpu_sched_component *component)
 \ingroup API_Modularized_Scheduler
 	 free data allocated by starpu_sched_component_create and call component->deinit_data(component)
@@ -108,21 +172,22 @@ The actual scheduler
 \ingroup API_Modularized_Scheduler
 	 return the struct starpu_sched_component corresponding to \p workerid. Undefined if \p workerid is not a valid workerid
 
-
 \fn int starpu_sched_component_is_worker(struct starpu_sched_component *component)
 \ingroup API_Modularized_Scheduler
 	 return true iff \p component is a worker component
+
 \fn int starpu_sched_component_is_simple_worker(struct starpu_sched_component *component)
 \ingroup API_Modularized_Scheduler
 	 return true iff \p component is a simple worker component
+
 \fn int starpu_sched_component_is_combined_worker(struct starpu_sched_component *component)
 \ingroup API_Modularized_Scheduler
 	 return true iff \p component is a combined worker component
+
 \fn int starpu_sched_component_worker_get_workerid(struct starpu_sched_component *worker_component)
 \ingroup API_Modularized_Scheduler
 	 return the workerid of \p worker_component, undefined if starpu_sched_component_is_worker(worker_component) == 0
 
-
 \fn struct starpu_sched_component *starpu_sched_component_fifo_create(struct starpu_sched_tree *tree, struct starpu_fifo_data *fifo_data)
 \ingroup API_Modularized_Scheduler
 	 Return a struct starpu_sched_component with a fifo. A stable sort is performed according to tasks priorities.
@@ -137,7 +202,6 @@ The actual scheduler
 \ingroup API_Modularized_Scheduler
 	 return a component that perform a work stealing scheduling. Tasks are pushed in a round robin way. estimated_end return the average of expected length of fifos, starting at the average of the expected_end of his children. When a worker have to steal a task, it steal a task in a round robin way, and get the last pushed task of the higher priority.
 
-
 \fn int starpu_sched_tree_work_stealing_push_task(struct starpu_task *task)
 \ingroup API_Modularized_Scheduler
 	 undefined if there is no work stealing component in the scheduler. If any, \p task is pushed in a default way if the caller is the application, and in the caller's fifo if its a worker.
@@ -169,38 +233,35 @@ The actual scheduler
 	 Also set starpu_task::predicted and starpu_task::predicted_transfer for memory component of the first suitable workerid.
 	 If starpu_sched_component::push method is called and starpu_sched_component::nchild > 1 the result is undefined.
 
-\fn struct starpu_sched_tree *starpu_sched_tree_create(unsigned sched_ctx_id)
-\ingroup API_Modularized_Scheduler
-	 create a empty initialized starpu_sched_tree
-\fn void starpu_sched_tree_destroy(struct starpu_sched_tree *tree)
-\ingroup API_Modularized_Scheduler
-	 destroy tree and free all non shared component in it.
 \fn void starpu_sched_component_destroy_rec(struct starpu_sched_component *component)
 \ingroup API_Modularized_Scheduler
 	 recursively destroy non shared parts of a \p component 's tree
 
-
 \fn int starpu_sched_tree_push_task(struct starpu_task *task)
 \ingroup API_Modularized_Scheduler
 	 compatibility with starpu_sched_policy interface
+
 \fn struct starpu_task *starpu_sched_tree_pop_task()
 \ingroup API_Modularized_Scheduler
 	 compatibility with starpu_sched_policy interface
+
 \fn void starpu_sched_tree_add_workers(unsigned sched_ctx_id, int *workerids, unsigned nworkers)
 \ingroup API_Modularized_Scheduler
 	 compatibility with starpu_sched_policy interface
+
 \fn void starpu_sched_tree_remove_workers(unsigned sched_ctx_id, int *workerids, unsigned nworkers)
 \ingroup API_Modularized_Scheduler
 	 compatibility with starpu_sched_policy interface
+
 \fn void starpu_sched_component_worker_pre_exec_hook(struct starpu_task *task)
 \ingroup API_Modularized_Scheduler
 	 compatibility with starpu_sched_policy interface
 	 update predictions for workers
+
 \fn void starpu_sched_component_worker_post_exec_hook(struct starpu_task *task)
 \ingroup API_Modularized_Scheduler
 	 compatibility with starpu_sched_policy interface
 
-
 \fn void starpu_sched_tree_update_workers(struct starpu_sched_tree *t)
 \ingroup API_Modularized_Scheduler
 	 recursively set all starpu_sched_component::workers, do not take into account shared parts (except workers).
@@ -212,9 +273,11 @@ The actual scheduler
 \struct starpu_bitmap
 \ingroup API_Modularized_Scheduler
 	 implement a simple bitmap
+
 \fn struct starpu_bitmap *starpu_bitmap_create(void)
 \ingroup API_Modularized_Scheduler
 	 create a empty starpu_bitmap
+
 \fn void starpu_bitmap_destroy(struct starpu_bitmap *b)
 \ingroup API_Modularized_Scheduler
 	 free a starpu_bitmap
@@ -222,6 +285,7 @@ The actual scheduler
 \fn void starpu_bitmap_set(struct starpu_bitmap *b, int e)
 \ingroup API_Modularized_Scheduler
 	 set bit \p e in \p b
+
 \fn void starpu_bitmap_unset(struct starpu_bitmap *b, int e)
 \ingroup API_Modularized_Scheduler
 	 unset bit \p e in \p b
@@ -238,10 +302,10 @@ The actual scheduler
 \ingroup API_Modularized_Scheduler
 	 return the number of set bits in \p b
 
-
 \fn int starpu_bitmap_first(struct starpu_bitmap *b)
 \ingroup API_Modularized_Scheduler
 	 return the position of the first set bit of \p b, -1 if none
+
 \fn int starpu_bitmap_last(struct starpu_bitmap *b)
 \ingroup API_Modularized_Scheduler
 	 return the position of the last set bit of \p b, -1 if none
@@ -250,7 +314,6 @@ The actual scheduler
 \ingroup API_Modularized_Scheduler
 	 return the position of set bit right after \p e in \p b, -1 if none
 
-
 \struct starpu_sched_component_composed_recipe
 \ingroup API_Modularized_Scheduler
 	parameters for starpu_sched_component_composed_component_create
@@ -259,7 +322,6 @@ The actual scheduler
 \ingroup API_Modularized_Scheduler
 	 return an empty recipe for a composed component, it should not be used without modification
 
-
 \fn struct starpu_sched_component_composed_recipe *starpu_sched_component_create_recipe_singleton(struct starpu_sched_component *(*create_component)(struct starpu_sched_tree *tree, void *arg), void *arg)
 \ingroup API_Modularized_Scheduler
 	 return a recipe to build a composed component with a \p create_component
@@ -277,7 +339,6 @@ The actual scheduler
 	 create a component that behave as all component of recipe where linked. Except that you cant use starpu_sched_component_is_foo function
 	 if recipe contain a single create_foo arg_foo pair, create_foo(arg_foo) is returned instead of a composed component
 
-
 \struct starpu_sched_specs
 \ingroup API_Modularized_Scheduler
 	 Define how build a scheduler according to topology. Each level (except for hwloc_machine_composed_sched_component) can be NULL, then
@@ -291,7 +352,6 @@ The actual scheduler
      the composed component to put for each socket
 \var starpu_sched_specs::hwloc_cache_composed_sched_component
      the composed component to put for each cache
-     
 \var starpu_sched_specs::worker_composed_sched_component
      a function that return a starpu_sched_component_composed_recipe to put on top of a worker of type \p archtype.
      NULL is a valid return value, then no component will be added on top
@@ -304,4 +364,5 @@ The actual scheduler
 \fn struct starpu_sched_tree *starpu_sched_component_make_scheduler(unsigned sched_ctx_id, struct starpu_sched_specs s)
 \ingroup API_Modularized_Scheduler
 	 this function build a scheduler for \p sched_ctx_id according to \p s and the hwloc topology of the machine.
+
 */

include/starpu_sched_component.h

@@ -38,45 +38,15 @@ enum starpu_sched_component_properties
 #define STARPU_SCHED_COMPONENT_IS_HOMOGENEOUS(component) ((component)->properties & STARPU_SCHED_COMPONENT_HOMOGENEOUS)
 #define STARPU_SCHED_COMPONENT_IS_SINGLE_MEMORY_NODE(component) ((component)->properties & STARPU_SCHED_COMPONENT_SINGLE_MEMORY_NODE)
 
-/* struct starpu_sched_component 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 components, a list of parent is
- * defined indexed by sched_ctx_id
- *
- * they embed there specialised method in a pseudo object-style, so calls are like component->push_task(component,task)
- *
- */
 struct starpu_sched_component
 {
-	/* The tree containing the component */
 	struct starpu_sched_tree *tree;
-
-	/* the set of workers in the component's subtree
-	 */
 	struct starpu_bitmap *workers;
-	/* the workers available in context
-	 * this member is set with :
-	 * component->workers UNION tree->workers UNION
-	 * component->child[i]->workers_in_ctx iff exist x such as component->children[i]->parents[x] == component
-	 */
 	struct starpu_bitmap *workers_in_ctx;
-
-	/* component's private data, no restriction on use
-	 */
 	void *data;
-
-	/* the numbers of component's children
-	 */
 	int nchildren;
-	/* the vector of component's children
-	 */
 	struct starpu_sched_component **children;
-	/* the numbers of component's parents
-	 */
 	int nparents;
-	/* may be shared by several contexts
-	 * so we need several parents
-	 */
 	struct starpu_sched_component **parents;
 
 	void (*add_child)(struct starpu_sched_component *component, struct starpu_sched_component *child);
@@ -84,63 +54,20 @@ struct starpu_sched_component
 	void (*add_parent)(struct starpu_sched_component *component, struct starpu_sched_component *parent);
 	void (*remove_parent)(struct starpu_sched_component *component, struct starpu_sched_component *parent);
 
-	/* component->push_task(component, task)
-	 * this function is called to push a task on component subtree, this can either
-	 * perform a recursive call on a child or store the task in the component, then
-	 * it will be returned by a further pull_task call
-	 *
-	 * the caller must ensure that component is able to execute task
-	 */
 	int (*push_task)(struct starpu_sched_component *, struct starpu_task *);
-	/* this function is called by workers to get a task on them parents
-	 * this function should first return a localy stored task or perform
-	 * a recursive call on parent
-	 *
-	 * a default implementation simply do a recursive call on parent
-	 */
 	struct starpu_task * (*pull_task)(struct starpu_sched_component *);
 
-	/* This function is called by a component which implements a queue, allowing it to
-	 * signify to its parents that an empty slot is available in its queue.
-	 * The basic implementation of this function is a recursive call to its
-	 * parents, the user have to specify a personally-made function to catch those
-	 * calls.
-	 */
 	int (*can_push)(struct starpu_sched_component *component);
-	/* This function allow a component to wake up a worker.
-	 * It is currently called by component which implements a queue, to signify to
-	 * its children that a task have been pushed in its local queue, and is
-	 * available to been popped by a worker, for example.
-	 * The basic implementation of this function is a recursive call to
-	 * its children, until at least one worker have been woken up.
-	 */
 	void (*can_pull)(struct starpu_sched_component *component);
 
-	/* this function is an heuristic that compute load of subtree, basicaly
-	 * it compute
-	 * estimated_load(component) = sum(estimated_load(component_children)) +
-	 *          nb_local_tasks / average(relative_speedup(underlying_worker))
-	 */
 	double (*estimated_load)(struct starpu_sched_component *component);
 	double (*estimated_end)(struct starpu_sched_component *component);
 
-	/* this function is called by starpu_sched_component_destroy just before freeing component
-	 */
 	void (*deinit_data)(struct starpu_sched_component *component);
-	/* this function is called for each component when workers are added or removed from a context
-	 */
 	void (*notify_change_workers)(struct starpu_sched_component *component);
-
-	/* is_homogeneous is 0 if workers in the component's subtree are heterogeneous,
-	 * this field is set and updated automaticaly, you shouldn't write on it
-	 */
 	int properties;
 
 #ifdef STARPU_HAVE_HWLOC
-	/* in case of a modularized scheduler, this is set to the part of
-	 * topology that is binded to this component, eg: a numa node for a ws
-	 * component that would balance load between underlying sockets
-	 */
 	hwloc_obj_t obj;
 #else
 	void *obj;
@@ -152,14 +79,7 @@ struct starpu_sched_tree
 	struct starpu_sched_component *root;
 	struct starpu_bitmap *workers;
 	unsigned sched_ctx_id;
-
-	/* this array store worker components */
 	struct starpu_sched_component *worker_components[STARPU_NMAXWORKERS];
-
-	/* 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_mutex_t lock;
 };
 
@@ -167,8 +87,6 @@ struct starpu_sched_tree
  *							Scheduling Tree's Interface 					   *
  ******************************************************************************/
 
-/* create an empty tree
- */
 struct starpu_sched_tree *starpu_sched_tree_create(unsigned sched_ctx_id);
 void starpu_sched_tree_destroy(struct starpu_sched_tree *tree);
 struct starpu_sched_tree *starpu_get_tree(unsigned sched_ctx_id);