til: introduce til_module_create_contexts() variant

checkers::fill_module is presently implemented via creating
n_cpus identical module contexts, each having n_cpus=1.
Establishing a set of cloned per-cpu contexts, allowing threaded
rendering using any fill_module, regardless of if that module
internally implements threaded rendering.

This works fine, but creates some awkwardness for a future where
contexts are registered and discoverable within the stream at
their respective setup's path.  In the checkers::fill_module
case, there would be n_cpus contexts at the same path since they
share the same til_setup_t.  Those need to be dealt with
gracefully, ideally making the clones available to another
potentially clone-needing module (imagine a checkers::fill_module
transitionining to another checkers::fill_module situation, where
the transitioned-to fill_module refers to the context by path, it
should get all the contexts out of the stream as-is)

In this commit I'm adding a more formalized method of creating
multiple contexts from the same set of parameters, in preparation
for a future where module contexts get registered on the stream
at their til_setup_t.path.  By putting the cloned creates behind
the til API it should at least be relatively trivial to get the
on-stream context registration to capture the multiple contexts.

2 files changed, 26 insertions, 10 deletions

diff --git a/src/til.c b/src/til.c
index cfb7095..e62fb8e 100644
--- a/src/til.c
+++ b/src/til.c
@@ -266,31 +266,46 @@ void til_module_render(til_module_context_t *context, til_stream_t *stream, unsi
  * the purpose of explicitly constraining rendering parallelization to less than n_threads,
  * if n_cpus is specified > n_threads it won't increase n_threads...
  */
-int til_module_create_context(const til_module_t *module, til_stream_t *stream, unsigned seed, unsigned ticks, unsigned n_cpus, til_setup_t *setup, til_module_context_t **res_context)
+int til_module_create_contexts(const til_module_t *module, til_stream_t *stream, unsigned seed, unsigned ticks, unsigned n_cpus, til_setup_t *setup, size_t n_contexts, til_module_context_t **res_contexts)
 {
-	til_module_context_t	*context;
 
 	assert(module);
 	assert(setup); /* we *always* want a setup, even if the module has no setup() method - for the path */
-	assert(res_context);
+	assert(n_contexts > 0);
+	assert(res_contexts);
 
 	if (!n_cpus)
 		n_cpus = til_threads_num_threads(til_threads);
 
-	if (!module->create_context)
-		context = til_module_context_new(module, sizeof(til_module_context_t), stream, seed, ticks, n_cpus, setup);
-	else
-		context = module->create_context(module, stream, seed, ticks, n_cpus, setup);
+	for (size_t i = 0; i < n_contexts; i++) {
+		til_module_context_t	*context;
+
+		if (!module->create_context)
+			context  = til_module_context_new(module, sizeof(til_module_context_t), stream, seed, ticks, n_cpus, setup);
+		else
+			context = module->create_context(module, stream, seed, ticks, n_cpus, setup);
+
+		if (!context) {
+			for (size_t j = 0; j < i; j++)
+				res_contexts[j] = til_module_context_free(res_contexts[j]);
 
-	if (!context)
-		return -ENOMEM;
+			return -ENOMEM;
+		}
 
-	*res_context = context;
+		res_contexts[i] = context;
+	}
 
 	return 0;
 }
 
 
+/* convenience single-context wrapper around til_module_create_contexts(), as most callers need just one. */
+int til_module_create_context(const til_module_t *module, til_stream_t *stream, unsigned seed, unsigned ticks, unsigned n_cpus, til_setup_t *setup, til_module_context_t **res_context)
+{
+	return til_module_create_contexts(module, stream, seed, ticks, n_cpus, setup, 1, res_context);
+}
+
+
 /* select module if not yet selected, then setup the module. */
 int til_module_setup(const til_settings_t *settings, til_setting_t **res_setting, const til_setting_desc_t **res_desc, til_setup_t **res_setup)
 {
diff --git a/src/til.h b/src/til.h
index d45e2ad..318f1b6 100644
--- a/src/til.h
+++ b/src/til.h
@@ -44,6 +44,7 @@ const til_module_t * til_lookup_module(const char *name);
 void til_get_modules(const til_module_t ***res_modules, size_t *res_n_modules);
 char * til_get_module_names(unsigned flags_excluded, const char **exclusions);
 void til_module_render(til_module_context_t *context, til_stream_t *stream, unsigned ticks, til_fb_fragment_t **fragment_ptr);
+int til_module_create_contexts(const til_module_t *module, til_stream_t *stream, unsigned seed, unsigned ticks, unsigned n_cpus, til_setup_t *setup, size_t n_contexts, til_module_context_t **res_contexts);
 int til_module_create_context(const til_module_t *module, til_stream_t *stream, unsigned seed, unsigned ticks, unsigned n_cpus, til_setup_t *setup, til_module_context_t **res_context);
 til_module_context_t * til_module_destroy_context(til_module_context_t *context, til_stream_t *stream);
 int til_module_setup(const til_settings_t *settings, til_setting_t **res_setting, const til_setting_desc_t **res_desc, til_setup_t **res_setup);