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
	It should use starpu_sched_node::fathers[sched_ctx_id] to perform a recursive call.

\var starpu_sched_node::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_node::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_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 underlying workers
\var starpu_sched_node::workers_in_ctx
	this member contain the subset of starpu_sched_node::workers that is currently available in the context
	The push method should take this member into account.
\var starpu_sched_node::properties
	flags starpu_sched_node_properties for things
\var starpu_sched_node::data
	data used by the scheduler module
\var starpu_sched_node::add_child
	add a child to node
\var starpu_sched_node::remove_child
	remove a child from node

\var starpu_sched_node::fathers
	the array of scheduler module above indexed by scheduling context index

\var starpu_sched_node::notify_change_workers
	this function is called when starpu_sched_node::workers_in_ctx or starpu_sched_node::workers is changed
\var starpu_sched_node::deinit_data
	called by starpu_sched_node_destroy. Should free data allocated during creation
\var starpu_sched_node::obj
	the hwloc object associated to scheduler module

\enum starpu_sched_node_properties
\ingroup API_Modularized_Scheduler
flags for starpu_sched_node::properties
\var STARPU_SCHED_NODE_HOMOGENEOUS
     indicate that all workers have the same starpu_worker_archtype
\var STARPU_SCHED_NODE_SINGLE_MEMORY_NODE
     indicate that all workers have the same memory node

\def STARPU_SCHED_NODE_IS_HOMOGENEOUS
\ingroup API_Modularized_Scheduler
\def STARPU_SCHED_NODE_HOMOGENEOUS
     indicate if node is homogeneous
\def STARPU_SCHED_NODE_IS_SINGLE_MEMORY_NODE
\ingroup API_Modularized_Scheduler
     indicate if all workers have the same memory node


\struct starpu_sched_tree
\ingroup API_Modularized_Scheduler
The actual 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 starpu_sched_tree::lock
	this lock protect concurrent access from the hypervisor and the application.
\var starpu_sched_tree::sched_ctx_id
	the context id of the scheduler

\fn struct starpu_sched_node * starpu_sched_node_create(void)
\ingroup API_Modularized_Scheduler
	 allocate and initialize node field with defaults values :
	.pop_task make recursive call on father
	.estimated_load compute relative speedup and tasks in sub tree
	.estimated_end return the average of recursive call on childs
	.add_child is starpu_sched_node_add_child
	.remove_child is starpu_sched_node_remove_child
	.notify_change_workers does nothing
	.deinit_data does nothing


\fn void starpu_sched_node_destroy(struct starpu_sched_node * node)
\ingroup API_Modularized_Scheduler
    	 free data allocated by starpu_sched_node_create and call node->deinit_data(node)
	 set to null the member starpu_sched_node::fathers[sched_ctx_id] of all child if its equal to \p 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
	 \p child must not be already in starpu_sched_node::childs of \p node

\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 decrements nchilds
	 \p child must be in starpu_sched_node::child of \p node


\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 int STARPU_WARN_UNUSED_RESULT starpu_sched_node_execute_preds(struct starpu_sched_node * node, struct starpu_task * task, double * length);
\ingroup API_Modularized_Scheduler
	 return a non null value if \p node can execute \p task.
	 write the execution prediction length for the best implementation of the best worker available and write this at \p length address.
	 this result is more relevant if starpu_sched_node::is_homogeneous is non null.
	 if a worker need to be calibrated for an implementation, nan is set to \p length.

\fn double starpu_sched_node_transfer_length(struct starpu_sched_node * node, struct starpu_task * task);
\ingroup API_Modularized_Scheduler
	 return the average time to transfer \p task data to underlying \p node workers.

\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. Undefined if \p workerid is not a valid 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.
	 starpu_sched_node::estimated_end function compute the estimated length by dividing the sequential length by the number of underlying workers. Do not take into account tasks that are currently executed.

\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 * arg STARPU_ATTRIBUTE_UNUSED)
\ingroup API_Modularized_Scheduler
	 return a node 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 childs. 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 node 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.

\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(struct starpu_heft_data * heft_data)
\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 int starpu_sched_node_is_heft(struct starpu_sched_node * node)
\ingroup API_Modularized_Scheduler
	 return true iff \p node is a heft node

\struct starpu_heft_data
\ingroup API_Modularized_Scheduler
starpu_sched_node_heft_create parameters
\var starpu_heft_data::alpha
	 coefficient applied to computation length 
\var starpu_heft_data::beta
	 coefficient applied to communication length
\var starpu_heft_data::gamma
	 coefficient applied to power consumption
\var starpu_heft_data::idle_power
	 idle consumption of the machine
\var starpu_heft_data::no_perf_model_node_create
	 called to create the node to push task for whom no perf model is available
\var starpu_heft_data::arg_no_perf_model
	 argument passed to starpu_heft_data::no_perf_model_node_create
\var starpu_heft_data::calibrating_node_create
	 idem for tasks with an non calibrated implementation
\var starpu_heft_data::arg_calibrating_node
	 argument passed to starpu_heft_data::calibrating_node_create


\fn struct starpu_sched_node * starpu_sched_node_best_implementation_create(void * arg STARPU_ATTRIBUTE_UNUSED);
\ingroup API_Modularized_Scheduler
	 Select the implementation that offer the shortest computation length for the first worker that can execute the task.
	 Or an implementation that need to be calibrated.
	 Also set starpu_task::predicted and starpu_task::predicted_transfer for memory node of the first suitable workerid.
	 If starpu_sched_node::push method is called and starpu_sched_node::nchild > 1 the result is undefined.



\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 starpu_sched_node_available(struct starpu_sched_node * node)
\ingroup API_Modularized_Scheduler
	 notify all node's underlying workers that a task is available to pop

\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 void starpu_sched_tree_update_workers(struct starpu_sched_tree * t)
\ingroup API_Modularized_Scheduler
	 recursively set all starpu_sched_node::workers, do not take into account shared parts (except workers).

\fn void starpu_sched_tree_update_workers_in_ctx(struct starpu_sched_tree * t)
\ingroup API_Modularized_Scheduler
	 recursively set all starpu_sched_node::workers_in_ctx, do not take into account shared parts (except workers)

\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

*/