add some doc for the ctxs

doc/doxygen/chapters/api/scheduling_contexts.doxy

@@ -1,4 +1,4 @@
-*
+/*
  * This file is part of the StarPU Handbook.
  * Copyright (C) 2009--2011  Universit@'e de Bordeaux 1
  * Copyright (C) 2010, 2011, 2012, 2013  Centre National de la Recherche Scientifique

doc/doxygen/chapters/api/scheduling_policy.doxy

@@ -27,7 +27,7 @@ starpu_init().
         Insert a task into the scheduler.
 \var starpu_sched_policy::push_task_notify
         Notify the scheduler that a task was pushed on a given worker.
-	This method is called when a task that was explicitely
+	This method is called when a task that was explicitly
 	assigned to a worker becomes ready and is about to be executed
 	by the worker. This method therefore permits to keep the state
 	of the scheduler coherent even when StarPU bypasses the

doc/doxygen/chapters/scheduling_contexts.doxy

@@ -1,6 +1,6 @@
 /*
  * This file is part of the StarPU Handbook.
- * Copyright (C) 2009--2011  Universit@'e de Bordeaux 1
+//  * Copyright (C) 2009--2011  Universit@'e de Bordeaux 1
  * Copyright (C) 2010, 2011, 2012, 2013  Centre National de la Recherche Scientifique
  * Copyright (C) 2011, 2012 Institut National de Recherche en Informatique et Automatique
  * See the file version.doxy for copying conditions.
@@ -19,34 +19,44 @@ to minimize interferences between the execution of multiple parallel
 kernels, by partitioning the underlying pool of workers using
 contexts.
 
+
 \section CreatingAContext Creating A Context
 
 By default, the application submits tasks to an initial context, which
-disposes of all the computation ressources available to StarPU (all
+disposes of all the computation resources available to StarPU (all
 the workers). If the application programmer plans to launch several
-parallel kernels simultaneusly, by default these kernels will be
+parallel kernels simultaneously, by default these kernels will be
 executed within this initial context, using a single scheduler
 policy(see \ref TaskSchedulingPolicy). Meanwhile, if the application
 programmer is aware of the demands of these kernels and of the
 specificity of the machine used to execute them, the workers can be
 divided between several contexts. These scheduling contexts will
 isolate the execution of each kernel and they will permit the use of a
-scheduling policy proper to each one of them. In order to create the
-contexts, you have to know the indentifiers of the workers running
-within StarPU. By passing a set of workers together with the
-scheduling policy to the function starpu_sched_ctx_create(), you will
-get an identifier of the context created which you will use to
+scheduling policy proper to each one of them. 
+
+Scheduling Contexts may be created in two ways: either the programmers indicates
+the set of workers corresponding to each context (providing he knows the 
+identifiers of the workers running within StarPU), or the programmer
+does not provide any worker list and leaves the Hypervisor assign
+workers to each context according to their needs (\ref SchedulingContextHypervisor)
+
+Both cases require a call to the function <c>starpu_sched_ctx_create</c>, which 
+requires as input the worker list (the exact list or a NULL pointer) and the scheduling
+policy. The latter one can be a character list corresponding to the name of a StarPU
+predefined policy or the pointer to a custom policy. The function returns 
+an identifier of the context created which you will use to
 indicate the context you want to submit the tasks to.
 
+
 \code{.c}
-/* the list of ressources the context will manage */
+/* the list of resources the context will manage */
 int workerids[3] = {1, 3, 10};
 
 /* indicate the scheduling policy to be used within the context, the list of
    workers assigned to it, the number of workers, the name of the context */
 int id_ctx = starpu_sched_ctx_create("dmda", workerids, 3, "my_ctx");
 
-/* let StarPU know that the folowing tasks will be submitted to this context */
+/* let StarPU know that the following tasks will be submitted to this context */
 starpu_sched_ctx_set_task_context(id);
 
 /* submit the task to StarPU */
@@ -77,19 +87,32 @@ starpu_sched_ctx_add_workers(workerids, 3, sched_ctx2);
 starpu_sched_ctx_remove_workers(workerids, 3, sched_ctx1);
 \endcode
 
+\section SubmittingTasksToAContext Submitting Tasks To A Context
+The application may submit tasks to several contexts either 
+simultaneously or sequnetially. If several threads of submission
+are used the function <c>starpu_sched_ctx_set_context</c> may be called just
+before <c>starpu_task_submit</c>. Thus StarPU considers that 
+the current thread will submit tasks to the coresponding context.
+ 
+When the application may not assign a thread of submission to each
+context, the id of the context must be indicated by using the
+function <c>starpu_task_submit_to_ctx</c> or the field <c>STARPU_SCHED_CTX</c> 
+for <c>starpu_insert_task</c>.
+
 \section DeletingAContext Deleting A Context
 
 When a context is no longer needed it must be deleted. The application
 can indicate which context should keep the resources of a deleted one.
-All the tasks of the context should be executed before doing this. If
-the application need to avoid a barrier before moving the resources
-from the deleted context to the inheritor one, the application can
-just indicate when the last task was submitted. Thus, when this last
-task was submitted the resources will be move, but the context should
-still be deleted at some point of the application.
+All the tasks of the context should be executed before doing this. 
+Thus, the programmer may use either a barrier and then delete the context 
+directly, or just indicate
+that other tasks will not be submitted later on to the context (such that when 
+the last task is executed its workers will be moved to the inheritor)
+and delete the context at the end of the execution (when a barrier will
+be used eventually).
 
 \code{.c}
-/* when the context 2 will be deleted context 1 will be keep its resources */
+/* when the context 2 is deleted context 1 inherits its resources */
 starpu_sched_ctx_set_inheritor(sched_ctx2, sched_ctx1);
 
 /* submit tasks to context 2 */
@@ -98,7 +121,7 @@ for (i = 0; i < ntasks; i++)
 
 /* indicate that context 2 finished submitting and that */
 /* as soon as the last task of context 2 finished executing */
-/* its workers can be mobed to the inheritor context */
+/* its workers can be moved to the inheritor context */
 starpu_sched_ctx_finished_submit(sched_ctx1);
 
 /* wait for the tasks of both contexts to finish */
@@ -120,7 +143,7 @@ of tasks pending to be executed is kept and when workers are added to
 the contexts the tasks are submitted. However, if no resources are
 allocated the program will not terminate. If these tasks have not much
 priority the programmer can forbid the application to submitted them
-by calling the function starpu_sched_ctx_stop_task_submission().
+by calling the function <c>starpu_sched_ctx_stop_task_submission()</c>.
 
 \section ContextsSharingWorkers Contexts Sharing Workers
 
@@ -129,7 +152,7 @@ efficiently enough alone on these workers or when the application
 decides to express a hierarchy of contexts. The workers apply an
 alogrithm of ``Round-Robin'' to chose the context on which they will
 ``pop'' next. By using the function
-starpu_sched_ctx_set_turn_to_other_ctx(), the programmer can impose
+<c>starpu_sched_ctx_set_turn_to_other_ctx</c>, the programmer can impose
 the <c>workerid</c> to ``pop'' in the context <c>sched_ctx_id</c>
 next.