doc and example for submitting tasks to empty contexts

ChangeLog

@@ -133,6 +133,12 @@ Small changes:
     scheduler context
   * Fonction starpu_is_initialized() is moved to the public API.
 
+StarPU 1.2.7 (git revision xxx)
+==============================================
+
+Small changes:
+  * Fix code to allow to submit tasks to empty contexts
+
 StarPU 1.2.6 (git revision 23049adea01837479f309a75c002dacd16eb34ad)
 ==============================================
 

doc/doxygen/chapters/330_scheduling_contexts.doxy

@@ -74,7 +74,7 @@ the context */
 int id_ctx = starpu_sched_ctx_create(workerids, 3, "my_ctx", STARPU_SCHED_CTX_POLICY_NAME, "dmda", 0);
 
 /* let StarPU know that the following tasks will be submitted to this context */
-starpu_sched_ctx_set_task_context(id);
+starpu_sched_ctx_set_context(id);
 
 /* submit the task to StarPU */
 starpu_task_submit(task);
@@ -209,13 +209,34 @@ starpu_sched_ctx_delete(sched_ctx1);
 \section EmptyingAContext Emptying A Context
 
 A context may have no resources at the begining or at a certain
-moment of the execution. Task can still be submitted to these contexts
+moment of the execution. Tasks can still be submitted to these contexts
 and they will be executed as soon as the contexts will have resources. A list
-of tasks pending to be executed is kept and when workers are added to
-the contexts these tasks start being submitted. However, if resources
-are never allocated to the context the program will not terminate.
-If these tasks have low
-priority the programmer can forbid the application to submit them
-by calling the function starpu_sched_ctx_stop_task_submission().
+of tasks pending to be executed is kept and will be submitted when
+workers are added to the contexts.
+
+\code{.c}
+/* create a empty context */
+unsigned sched_ctx_id = starpu_sched_ctx_create(NULL, 0, "ctx", 0);
+
+/* submit a task to this context */
+starpu_sched_ctx_set_context(&sched_ctx_id);
+ret = starpu_task_insert(&codelet, 0);
+STARPU_CHECK_RETURN_VALUE(ret, "starpu_task_insert");
+
+/* add CPU workers to the context */
+int procs[STARPU_NMAXWORKERS];
+int nprocs = starpu_cpu_worker_get_count();
+starpu_worker_get_ids_by_type(STARPU_CPU_WORKER, procs, nprocs);
+starpu_sched_ctx_add_workers(procs, nprocs, sched_ctx_id);
+
+/* and wait for the task termination */
+starpu_task_wait_for_all();
+\endcode
+
+However, if resources are never allocated to the context, the
+application will not terminate. If these tasks have low priority, the
+application can inform StarPU to not submit them by calling the
+function starpu_sched_ctx_stop_task_submission().
+
 
 */

examples/Makefile.am

@@ -247,6 +247,7 @@ STARPU_EXAMPLES +=				\
 	profiling/profiling			\
 	scheduler/heteroprio_test		\
 	sched_ctx/sched_ctx			\
+	sched_ctx/sched_ctx_empty		\
 	sched_ctx/two_cpu_contexts		\
 	sched_ctx/dummy_sched_with_ctx		\
 	worker_collections/worker_tree_example  \

examples/sched_ctx/sched_ctx_empty.c

@@ -0,0 +1,67 @@
+/* StarPU --- Runtime system for heterogeneous multicore architectures.
+ *
+ * Copyright (C) 2012-2014,2017-2018                      Inria
+ * Copyright (C) 2010-2018                                CNRS
+ * Copyright (C) 2010-2014                                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
+ * the Free Software Foundation; either version 2.1 of the License, or (at
+ * your option) any later version.
+ *
+ * StarPU is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ *
+ * See the GNU Lesser General Public License in COPYING.LGPL for more details.
+ */
+
+#include <starpu.h>
+
+#define FPRINTF(ofile, fmt, ...) do { if (!getenv("STARPU_SSILENT")) {fprintf(ofile, fmt, ## __VA_ARGS__); }} while(0)
+
+static void cpu_func(void *descr[], void *arg)
+{
+	(void)descr;
+	(void)arg;
+	FPRINTF(stdout, "Hello world\n");
+}
+
+static struct starpu_codelet codelet =
+{
+	.cpu_funcs = {cpu_func},
+	.nbuffers = 0,
+	.name = "codelet"
+};
+
+int main(void)
+{
+	int ret;
+	int nprocs = 0;
+	int procs[STARPU_NMAXWORKERS];
+	unsigned sched_ctx_id;
+
+	ret = starpu_init(NULL);
+	if (ret == -ENODEV) return 77;
+	STARPU_CHECK_RETURN_VALUE(ret, "starpu_init");
+
+	nprocs = starpu_cpu_worker_get_count();
+	// if there is no cpu, skip
+	if (nprocs == 0) goto enodev;
+
+	sched_ctx_id = starpu_sched_ctx_create(NULL, 0, "ctx", 0);
+	starpu_sched_ctx_set_context(&sched_ctx_id);
+
+	ret = starpu_task_insert(&codelet, 0);
+	STARPU_CHECK_RETURN_VALUE(ret, "starpu_task_insert");
+
+	starpu_worker_get_ids_by_type(STARPU_CPU_WORKER, procs, nprocs);
+	starpu_sched_ctx_add_workers(procs, nprocs, sched_ctx_id);
+	starpu_task_wait_for_all();
+
+	starpu_sched_ctx_delete(sched_ctx_id);
+
+enodev:
+	starpu_shutdown();
+	return nprocs == 0 ? 77 : 0;
+}