Add more scheduling documentation

doc/doxygen/chapters/350_scheduling_policy_definition.doxy

@@ -83,7 +83,10 @@ starpu_task_expected_length(), for the required data transfers with
 starpu_task_expected_data_transfer_time_for(), for the required energy with
 starpu_task_expected_energy(), etc. Other
 useful functions include starpu_transfer_bandwidth(), starpu_transfer_latency(),
-starpu_transfer_predict(), ... One can also directly the presence of a data handle with starpu_data_is_on_node().
+starpu_transfer_predict(), ...
+One can also directly test the presence of a data handle with starpu_data_is_on_node(). Prefetches can be triggered by calling starpu_prefetch_task_input_for(). 
+starpu_get_prefetch_flag() is a convenient helper for checking the value of the 
+STARPU_PREFETCH environment variable.
 
 Usual functions can be used on tasks, for instance one can use the following to
 get the data size for a task.
@@ -144,6 +147,15 @@ and picks it. If the task was pushed on a shared queue, one may want to only
 wake one idle worker. An example doing this is available in
 <c>src/sched_policies/eager_central_policy.c</c>.
 
+
+A pointer to one data structure specific to the scheduler can be set with
+starpu_sched_ctx_set_policy_data() and fetched with
+starpu_sched_ctx_get_policy_data(). Per-worker data structures can then be
+store in it by allocating a STARPU_NMAXWORKERS-sized array of structures indexed
+by workers.
+
+Access to the hwloc topology is available with starpu_worker_get_hwloc_obj()
+
 A variety of examples of
 advanced schedulers can be read in <c>src/sched_policies</c>, for
 instance <c>random_policy.c</c>, <c>eager_central_policy.c</c>,
@@ -248,29 +260,38 @@ All modularized schedulers are named following the RE <c>tree-*</c>
 Each Scheduling Component must follow the following pre-defined Interface
 to be able to interact with other Scheduling Components.
 
-	- Push (Caller_Component, Child_Component, Task) \n
+	- push_task (child_component, Task) \n
 	The calling Scheduling Component transfers a task to its
 	Child Component. When the Push function returns, the task no longer
 	belongs to the calling Component. The Modularized Schedulers'
 	model relies on this function to perform prefetching.
 	See starpu_sched_component::push_task for more details
 
-	- Pull (Caller_Component, Parent_Component)  ->  Task \n
+	- pull_task (parent_component, caller_component)  ->  Task \n
 	The calling Scheduling Component requests a task from
 	its Parent Component. When the Pull function ends, the returned
 	task belongs to the calling Component.
 	See starpu_sched_component::pull_task for more details
 
-	- Can_Push (Caller_Component, Parent_Component) \n
+	- can_push (caller_component, parent_component) \n
 	The calling Scheduling Component notifies its Parent Component that
 	it is ready to accept new tasks.
 	See starpu_sched_component::can_push for more details
 
-	- Can_Pull (Caller_Component, Child_Component) \n
+	- can_pull (caller_component, child_component) \n
 	The calling Scheduling Component notifies its Child Component
 	that it is ready to give new tasks.
 	See starpu_sched_component::can_pull for more details
 
+The components also provide the following useful methods:
+
+        - starpu_sched_component::estimated_load provides an estimated load of
+        the component
+        - starpu_sched_component::estimated_end provides an estimated date of
+        availability of workers behind the component, after processing tasks in
+        the component and below.
+        This is computed only if the estimated field of the tasks have been set
+        before passing it to the component.
 
 \subsection BuildAModularizedScheduler Building a Modularized Scheduler
 

doc/doxygen/chapters/api/modularized_scheduler.doxy

@@ -186,7 +186,7 @@ The actual scheduler
 	 allocate and initialize component 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 children
+	.estimated_end return the minimum of recursive call on children
 	.add_child is starpu_sched_component_add_child
 	.remove_child is starpu_sched_component_remove_child
 	.notify_change_workers does nothing
@@ -296,7 +296,7 @@ todo
 \ingroup API_Modularized_Scheduler
 	 Return a struct starpu_sched_component with a fifo. A stable sort is performed according to tasks priorities.
 	 A push_task call on this component does not perform recursive calls, underlying components will have to call pop_task to get it.
-	 starpu_sched_component::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.
+	 starpu_sched_component::estimated_end function compute the estimated length by dividing the sequential length by the number of underlying workers.
 
 \fn int starpu_sched_component_is_fifo(struct starpu_sched_component *component)
 \ingroup API_Modularized_Scheduler

doc/doxygen/chapters/api/workers.doxy

@@ -2,7 +2,7 @@
  *
  * Copyright (C) 2011-2013,2017                           Inria
  * Copyright (C) 2010-2017                                CNRS
- * Copyright (C) 2009-2011,2014,2016-2018                 Université de Bordeaux
+ * Copyright (C) 2009-2011,2014,2016-2019                 Université de Bordeaux
  *
  * StarPU is free software; you can redistribute it and/or modify
  * it under the terms of the GNU Lesser General Public License as published by
@@ -358,6 +358,11 @@ hwloc cpuset associated with the worker \p workerid. The returned cpuset is obta
 from a \c hwloc_bitmap_dup() function call. It must be freed by the caller
 using \c hwloc_bitmap_free().
 
+\fn hwloc_obj_t starpu_worker_get_hwloc_obj(int workerid)
+\ingroup API_Workers_Properties
+If StarPU was compiled with hwloc support, returns the HWLOC object corresponding to 
+the worker \p workerid.
+
 \fn void starpu_worker_set_going_to_sleep_callback(void (*callback)(unsigned workerid))
 \ingroup API_Workers_Properties
 If StarPU was compiled with blocking drivers support and worker callbacks support

include/starpu_worker.h

@@ -2,7 +2,7 @@
  *
  * Copyright (C) 2013-2017                                Inria
  * Copyright (C) 2010-2015,2017                           CNRS
- * Copyright (C) 2009-2014,2016,2017                      Université de Bordeaux
+ * Copyright (C) 2009-2014,2016,2017,2019                 Université de Bordeaux
  * Copyright (C) 2013                                     Thibaut Lambert
  * Copyright (C) 2016                                     Uppsala University
  *
@@ -175,6 +175,7 @@ void starpu_worker_set_waking_up_callback(void (*callback)(unsigned workerid));
 
 #ifdef STARPU_HAVE_HWLOC
 hwloc_cpuset_t starpu_worker_get_hwloc_cpuset(int workerid);
+hwloc_obj_t starpu_worker_get_hwloc_obj(int workerid);
 #endif
 
 #ifdef __cplusplus

src/core/combined_workers.c

@@ -1,7 +1,7 @@
 /* StarPU --- Runtime system for heterogeneous multicore architectures.
  *
  * Copyright (C) 2013-2015,2017                           Inria
- * Copyright (C) 2010-2015,2018                           Université de Bordeaux
+ * Copyright (C) 2010-2015,2018-2019                      Université de Bordeaux
  * Copyright (C) 2010,2011,2013-2017                      CNRS
  * Copyright (C) 2013                                     Simon Archipoff
  * Copyright (C) 2013                                     Thibaut Lambert

src/core/topology.c

@@ -2878,6 +2878,7 @@ static void _starpu_init_workers_binding_and_memory(struct _starpu_machine_confi
 		if (workerarg->bindid == -1)
 		{
 			workerarg->hwloc_cpu_set = hwloc_bitmap_alloc();
+			workerarg->hwloc_obj = NULL;
 		}
 		else
 		{
@@ -2893,6 +2894,7 @@ static void _starpu_init_workers_binding_and_memory(struct _starpu_machine_confi
 
 			/* Clear the cpu set and set the cpu */
 			workerarg->hwloc_cpu_set = hwloc_bitmap_dup(worker_obj->cpuset);
+			workerarg->hwloc_obj = worker_obj;
 		}
 #endif
 		if (workerarg->bindid != -1)

src/core/workers.c

@@ -1,7 +1,7 @@
 /* StarPU --- Runtime system for heterogeneous multicore architectures.
  *
  * Copyright (C) 2010-2018                                Inria
- * Copyright (C) 2008-2018                                Université de Bordeaux
+ * Copyright (C) 2008-2019                                Université de Bordeaux
  * Copyright (C) 2010-2018                                CNRS
  * Copyright (C) 2013                                     Thibaut Lambert
  * Copyright (C) 2011                                     Télécom-SudParis
@@ -618,7 +618,7 @@ void _starpu_worker_init(struct _starpu_worker *workerarg, struct _starpu_machin
 	workerarg->state_unblock_in_parallel_ack = 0;
 	workerarg->block_in_parallel_ref_count = 0;
 
-	/* cpu_set/hwloc_cpu_set initialized in topology.c */
+	/* cpu_set/hwloc_cpu_set/hwloc_obj initialized in topology.c */
 }
 
 static void _starpu_worker_deinit(struct _starpu_worker *workerarg)
@@ -2530,6 +2530,11 @@ hwloc_cpuset_t starpu_worker_get_hwloc_cpuset(int workerid)
 	struct _starpu_worker *worker = _starpu_get_worker_struct(workerid);
 	return hwloc_bitmap_dup(worker->hwloc_cpu_set);
 }
+hwloc_obj_t starpu_worker_get_hwloc_obj(int workerid)
+{
+	struct _starpu_worker *worker = _starpu_get_worker_struct(workerid);
+	return worker->hwloc_obj;
+}
 #endif
 
 /* Light version of _starpu_wake_worker_relax, which, when possible,

src/core/workers.h

@@ -1,7 +1,7 @@
 /* StarPU --- Runtime system for heterogeneous multicore architectures.
  *
  * Copyright (C) 2011-2017                                Inria
- * Copyright (C) 2008-2018                                Université de Bordeaux
+ * Copyright (C) 2008-2019                                Université de Bordeaux
  * Copyright (C) 2010-2018                                CNRS
  * Copyright (C) 2013                                     Thibaut Lambert
  * Copyright (C) 2016                                     Uppsala University
@@ -197,6 +197,7 @@ LIST_TYPE(_starpu_worker,
 #endif /* __GLIBC__ */
 #ifdef STARPU_HAVE_HWLOC
 	hwloc_bitmap_t hwloc_cpu_set;
+	hwloc_obj_t hwloc_obj;
 #endif
 );