intro for monolithic vs modular, and simple modular scheduler assembly example

doc/doxygen/chapters/350_scheduling_policy_definition.doxy

@@ -21,9 +21,23 @@
 
 \section Introduction Introduction
 
-presentation of both types of schedulers: the basic and the modular.
-
-Explain why it is easier to define a new scheduler by using the modular approach
+StarPU provides two ways of defining a scheduling policy, a basic monolithic
+way, and a modular way.
+
+The basic monolithic way is directly connected with the core of StarPU, which
+means that the policy then has to handle all performance details, such as data
+prefetching, task performance model calibration, worker locking, etc.
+<c>examples/scheduler/dummy_sched.c</c> is a trivial example which does not
+handle this, and thus e.g. does not achieve any data prefetching or smart
+scheduling.
+
+The modular way allows to implement just one component, and
+reuse existing components to cope with all these details.
+<c>examples/scheduler/dummy_modular_sched.c</c> is a trivial example very
+similar to <c>dummy_sched.c</c>, but implemented as a component, which allows to
+assemble it with other components, and notably get data prefetching support for
+free, and task performance model calibration is properly performed, which allows
+to easily extend it into taking task duration into account, etc.
 
 \section DefiningANewBasicSchedulingPolicy Defining A New Basic Scheduling Policy
 
@@ -302,7 +316,50 @@ Scheduler :
 \subsubsection ImplementAModularizedScheduler Implementing a Modularized Scheduler
 
 The following code shows how the Tree-Eager-Prefetching Scheduler
-shown in Section \ref ExampleTreeEagerPrefetchingStrategy is implemented :
+shown in Section \ref ExampleTreeEagerPrefetchingStrategy can be implemented :
+
+\code{.c}
+static void initialize_eager_prefetching_center_policy(unsigned sched_ctx_id)
+{
+  /* The eager component will decide for each task which worker will run it,
+   * and we want fifos both above and below the component */
+  starpu_sched_component_initialize_simple_scheduler(
+    starpu_sched_component_eager_create, NULL,
+    STARPU_SCHED_SIMPLE_DECIDE_WORKERS |
+    STARPU_SCHED_SIMPLE_FIFO_ABOVE |
+    STARPU_SCHED_SIMPLE_FIFOS_BELOW,
+    sched_ctx_id);
+}
+
+/* Properly destroy the Scheduling Tree and all its Components */
+static void deinitialize_eager_prefetching_center_policy(unsigned sched_ctx_id)
+{
+  struct starpu_sched_tree * tree = (struct starpu_sched_tree*)starpu_sched_ctx_get_policy_data(sched_ctx_id);
+  starpu_sched_tree_destroy(tree);
+}
+
+/* Initializing the starpu_sched_policy struct associated to the Modularized
+ * Scheduler : only the init_sched and deinit_sched needs to be defined to
+ * implement a Modularized Scheduler */
+struct starpu_sched_policy _starpu_sched_tree_eager_prefetching_policy =
+{
+  .init_sched = initialize_eager_prefetching_center_policy,
+  .deinit_sched = deinitialize_eager_prefetching_center_policy,
+  .add_workers = starpu_sched_tree_add_workers,
+  .remove_workers = starpu_sched_tree_remove_workers,
+  .push_task = starpu_sched_tree_push_task,
+  .pop_task = starpu_sched_tree_pop_task,
+  .pre_exec_hook = starpu_sched_component_worker_pre_exec_hook,
+  .post_exec_hook = starpu_sched_component_worker_post_exec_hook,
+  .pop_every_task = NULL,
+  .policy_name = "tree-eager-prefetching",
+  .policy_description = "eager with prefetching tree policy"
+};
+\endcode
+
+
+starpu_sched_component_initialize_simple_scheduler is a helper function which
+makes it very trivial to assemble a modular scheduler. The modular scheduler can also be built by hand in the following way:
 
 \code{.c}
 #define _STARPU_SCHED_NTASKS_THRESHOLD_DEFAULT 2