starpu-max/doc/doxygen/chapters/api/modularized_scheduler.doxy

/*! \defgroup API_Modularized_Scheduler Modularized Scheduler Interface

\struct starpu_sched_node
\ingroup API_Modularized_Scheduler
This structure represent a scheduler module.

\var starpu_sched_node::push_task
	push a task in the scheduler module.
\var starpu_sched_node::pop_task
	pop a task from the scheduler module, the task returned by this function is executable by the caller if its a worker
\var starpu_sched_node::available
	notify workers downstairs that a task is waiting for a pop, this member dont seems to be necessary
\var starpu_sched_node::estimated_load
	is an heuristic to compute load of scheduler module
\var starpu_sched_node::estimated_execute_preds
	compute executions prediction for a task
\var starpu_sched_node::nchilds
	the number of modules downstairs
\var starpu_sched_node::childs
	modules downstairs
\var starpu_sched_node::workers
	this member contain the set of underlaying workers
\var starpu_sched_node::is_homogeneous
	this is set to true iff all underlaying workers are the same
\var starpu_sched_node::data
	data used by the scheduler module
\var starpu_sched_node::fathers
	the array of scheduler module above indexed by scheduling context index
\var starpu_sched_node::init_data
	is called after all the scheduler is created and should init data member
	you can store things in node->data while calling _sched_node_create(arg)
	and use it with init_data
\var starpu_sched_node::deinit_data
	is called just before starpu_sched_node_destroy
\var starpu_sched_node::obj
	the hwloc object associed to scheduler module

\struct starpu_task_execute_preds
\ingroup API_Modularized_Scheduler
this structure containt predictions for a task and is filled by starpu_sched_node::estimated_execute_preds
\var starpu_task_execute_preds::state
	indicate status of prediction, if several status are possible, in order of priority it will be : CALIBRATING, PERF_MODEL, NO_PERF_MODEL, CANNOT_EXECUTE
\var starpu_task_execute_preds::archtype
\var starpu_task_execute_preds::impl
	those members are revelant is state is PERF_MODEL or CALIBRATING and is set to best or uncalibrated archtype and implementation, respectively, or suitable values if state is NO_PERF_MODEL
\var starpu_task_execute_preds::expected_finish_time
	expected finish time of task
\var starpu_task_execute_preds::expected_length
	expected compute time of task
\var starpu_task_execute_preds::expected_transfer_length
	expected time for transfering data to worker's memory node
\var starpu_task_execute_preds::expected_power
	expected power consumption for task

\struct starpu_sched_tree
\ingroup API_Modularized_Scheduler
\var starpu_sched_tree::root
	this is the entry module of the scheduler
\var starpu_sched_tree::workers
	this is the set of workers available in this context, this value is used to mask workers in modules
\var lock
	this lock protect the worker member

\fn struct starpu_sched_node * starpu_sched_node_create(void)
\ingroup API_Modularized_Scheduler
        allocate and initalise node field with defaults values :
	.pop_task make recursive call on father
	.available make a recursive call on childrens
	.estimated_load compute relative speedup and tasks in subtree
	.estimated_execute_preds return the average of recursive call on childs


\fn void starpu_sched_node_destroy(struct starpu_sched_node * node)
\ingroup API_Modularized_Scheduler
    	 free data allocated by starpu_sched_node_create, but dont call node->deinit_data(node)
\fn void starpu_sched_node_set_father(struct starpu_sched_node * node, struct starpu_sched_node * father_node, unsigned sched_ctx_id)
\ingroup API_Modularized_Scheduler
    	 set node->fathers[sched_ctx_id] to father_node
\fn void starpu_sched_node_add_child(struct starpu_sched_node* node, struct starpu_sched_node * child)
\ingroup API_Modularized_Scheduler
    	 add child to node->childs and increment nchilds as well
	 and dont modify child->fathers
\fn void starpu_sched_node_remove_child(struct starpu_sched_node * node, struct starpu_sched_node * child)
\ingroup API_Modularized_Scheduler
    	 remove child from node->childs and decrement nchilds


\fn int starpu_sched_node_can_execute_task(struct starpu_sched_node * node, struct starpu_task * task)
\ingroup API_Modularized_Scheduler
	 return true iff \p node can execute \p task, this function take into account the workers available in the scheduling context

\fn struct starpu_sched_node * starpu_sched_node_worker_get(int workerid)
\ingroup API_Modularized_Scheduler
	 return the struct starpu_sched_node corresponding to \p workerid


\fn int starpu_sched_node_is_worker(struct starpu_sched_node * node)
\ingroup API_Modularized_Scheduler
	 return true iff \p node is a worker node
\fn int starpu_sched_node_is_simple_worker(struct starpu_sched_node * node)
\ingroup API_Modularized_Scheduler
	 return true iff \p node is a simple worker node
\fn int starpu_sched_node_is_combined_worker(struct starpu_sched_node * node)
\ingroup API_Modularized_Scheduler
	 return true iff \p node is a combined worker node
\fn int starpu_sched_node_worker_get_workerid(struct starpu_sched_node * worker_node)
\ingroup API_Modularized_Scheduler
	 return the workerid of \p worker_node, undefined if starpu_sched_node_is_worker(worker_node) == 0


\fn struct starpu_sched_node * starpu_sched_node_fifo_create(void * arg STARPU_ATTRIBUTE_UNUSED)
\ingroup API_Modularized_Scheduler
	 return a struct starpu_sched_node with a fifo. A stable sort is performed according to tasks priorities.
	 a push_task call on this node does not perform recursive calls, underlaying nodes will have to call pop_task to get it.
	 estimated_execute_preds function compute the estimated length by dividing the sequencial length by the number of underlaying workers

\fn int starpu_sched_node_is_fifo(struct starpu_sched_node * node)
\ingroup API_Modularized_Scheduler
	 return true iff \p node is a fifo node


\fn struct starpu_sched_node * starpu_sched_node_work_stealing_create(void)
\ingroup API_Modularized_Scheduler
	 return a node that perform a work stealing scheduling,
	 a special function may be used instead of starpu_sched_tree_push_task that push tasks in the good fifo
	  
\fn int starpu_sched_node_is_work_stealing(struct starpu_sched_node * node)
\ingroup API_Modularized_Scheduler
	 return true iff \p node is a work stealing node

\fn struct starpu_sched_node * starpu_sched_node_random_create(void * arg STARPU_ATTRIBUTE_UNUSED)
\ingroup API_Modularized_Scheduler
	 create a node that perform a random scheduling

\fn int starpu_sched_node_is_random(struct starpu_sched_node *);
\ingroup API_Modularized_Scheduler
	 return true iff \p node is a random node


\fn struct starpu_sched_node * starpu_sched_node_heft_create(void * arg STARPU_ATTRIBUTE_UNUSED)
\ingroup API_Modularized_Scheduler
	 this node perform a heft scheduling using data provided by estimated_execute_preds, if no pred_model are available a random node is used to push tasks

\fn void starpu_sched_node_heft_set_no_model_node(struct starpu_sched_node * heft_node, struct starpu_sched_node * (*create_no_model_node)(void * arg), void * arg)
\ingroup API_Modularized_Scheduler
	 this should disapear and use arg to pass that kind of parameters

\fn int starpu_sched_node_is_heft(struct starpu_sched_node * node)
\ingroup API_Modularized_Scheduler
	 return true iff \p node is a heft node
\fn double starpu_sched_compute_expected_time(double now, double predicted_end, double predicted_length, double predicted_transfer)
\ingroup API_Modularized_Scheduler
	 compute expected end of a fifo with a task of \p predicted_length by taking in acount the fact that data may not be ready at \p predicted_end

\fn struct starpu_sched_tree * starpu_sched_tree_create(void)
\ingroup API_Modularized_Scheduler
	 create a empty initialized starpu_sched_tree
\fn void starpu_sched_tree_destroy(struct starpu_sched_tree * tree, unsigned sched_ctx_id)
\ingroup API_Modularized_Scheduler
	 destroy tree and free all non shared node in it.
\fn void starpu_sched_node_destroy_rec (struct starpu_sched_node *node, unsigned sched_ctx_id)
\ingroup API_Modularized_Scheduler
	 recursively destroy non shared parts of a \p node '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(unsigned sched_ctx_id)
\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_node_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_node_worker_post_exec_hook(struct starpu_task * task)
\ingroup API_Modularized_Scheduler
	 compatibility with starpu_sched_policy interface

\fn struct starpu_bitmap * _starpu_get_worker_mask(struct starpu_task *task)
\ingroup API_Modularized_Scheduler
	 return a ref to bitmap that give available worker to execute \p task



\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 *)
\ingroup API_Modularized_Scheduler
	 free a starpu_bitmap

\fn void starpu_bitmap_set(struct starpu_bitmap * bitmap, int e)
\ingroup API_Modularized_Scheduler
	 set bit \p e in \p bitmap
\fn void starpu_bitmap_unset(struct starpu_bitmap * bitmap, int e)
\ingroup API_Modularized_Scheduler
	 unset bit \p e in \p bitmap

\fn void starpu_bitmap_unset_all(struct starpu_bitmap * bitmap)
\ingroup API_Modularized_Scheduler
	 unset all bits in \b bitmap

\fn int starpu_bitmap_get(struct starpu_bitmap * bitmap, int e);
\ingroup API_Modularized_Scheduler
	 return true iff bit \p e is set in \p bitmap

\fn int starpu_bitmap_cardinal(struct starpu_bitmap * bitmap);
\ingroup API_Modularized_Scheduler
	 return the number of set bits in \p bitmap


\fn int starpu_bitmap_first(struct starpu_bitmap * bitmap)
\ingroup API_Modularized_Scheduler
	 return the position of the first set bit of \p bitmap, -1 if none
\fn int starpu_bitmap_last(struct starpu_bitmap * bitmap)
\ingroup API_Modularized_Scheduler
	 return the position of the last set bit of \p bitmap, -1 if none

\fn int starpu_bitmap_next(struct starpu_bitmap *, int e)
\ingroup API_Modularized_Scheduler
	 return the position of set bit right after \p e in \p bitmap, -1 if none

*/