til: introduce til_module_context_t

Preparatory commit for embedding a til type in the module
contexts, similar to til_setup_t for the module setups.

This will provide a convenient way to embed seed and n_cpus in
every module context, without having to implement that yourself.
But it also makes it so modules with no need for a context can
continue not implementing those methods, without obstructing
libtil from transparently doing it anyways with a bare
til_module_context_t.

This is kind of important as the current architecture made it
difficult to do things like create contexts with explicit n_cpus,
like in composite/meta modules which are already threaded and
wish to run embedded modules with n_cpus=1.

With this addition, n_cpus could be specified at context create
time, and it will always become remembered in the
til_module_context_t regardless of what the module implements.
That way it can definitely be carried into the prepare/render
methods, with no opportunity for disconnect between what was
passed to context create and what goes to the render methods.

Nothing is functionally changed in this commit alone, subsequent
commits will actually make use of it and realize what I've said
above.

3 files changed, 77 insertions, 1 deletions

diff --git a/src/Makefile.am b/src/Makefile.am
index 0313a1a..1641711 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -1,7 +1,7 @@
 SUBDIRS = libs modules
 
 noinst_LTLIBRARIES = libtil.la
-libtil_la_SOURCES = til_args.c til_args.h til_fb.c til_fb.h til_knobs.h til.c til.h til_settings.h til_settings.c til_setup.c til_setup.h til_threads.c til_threads.h til_util.c til_util.h
+libtil_la_SOURCES = til_args.c til_args.h til_fb.c til_fb.h til_knobs.h til.c til.h til_module_context.c til_module_context.h til_settings.h til_settings.c til_setup.c til_setup.h til_threads.c til_threads.h til_util.c til_util.h
 libtil_la_CPPFLAGS = -I@top_srcdir@/src
 libtil_la_LIBADD = modules/blinds/libblinds.la modules/checkers/libcheckers.la modules/compose/libcompose.la modules/drizzle/libdrizzle.la modules/flui2d/libflui2d.la modules/julia/libjulia.la modules/meta2d/libmeta2d.la modules/montage/libmontage.la modules/pixbounce/libpixbounce.la modules/plasma/libplasma.la modules/plato/libplato.la modules/ray/libray.la modules/roto/libroto.la modules/rtv/librtv.la modules/shapes/libshapes.la modules/snow/libsnow.la modules/sparkler/libsparkler.la modules/spiro/libspiro.la modules/stars/libstars.la modules/submit/libsubmit.la modules/swab/libswab.la modules/swarm/libswarm.la modules/voronoi/libvoronoi.la libs/grid/libgrid.la libs/puddle/libpuddle.la libs/ray/libray.la libs/sig/libsig.la libs/txt/libtxt.la libs/ascii/libascii.la libs/din/libdin.la
 
diff --git a/src/til_module_context.c b/src/til_module_context.c
new file mode 100644
index 0000000..a029f37
--- /dev/null
+++ b/src/til_module_context.c
@@ -0,0 +1,60 @@
+#include <assert.h>
+#include <errno.h>
+#include <stdlib.h>
+
+#include "til.h"
+#include "til_module_context.h"
+
+
+/* Allocate and initialize a new til_module_context_t of size bytes.
+ * It'd be nice to assign module_context->module here as well, but since this gets called
+ * almost exclusively as a helper from within modules' create_context(), it'd make the
+ * frequently-written module code more annoying and verbose to do so, since their til_module_t is
+ * preferably at EOF.  So in the interests of preserving that clean/ergonomic layout for modules,
+ * assignment of the .module memeber occurs in the public til_module_create_context(), which seems
+ * like an OK compromise.
+ *
+ * If the assigned module's til_module_t->destroy_context is NULL, libc's free() will be used to
+ * free the context.  This should be fine as long as statically allocated contexts never become a
+ * thing, which seems unlikely.  Doing it this way permits modules to omit their destroy_context()
+ * altogether if it would simply free(context).
+ *
+ * Note this returns void * despite creating a til_module_context_t, this is for convenience
+ * as the callers are generally using it in place of calloc(), and assign it to a
+ * container struct of some other type but having an embedded til_module_context_t.
+ */
+void * til_module_context_new(size_t size, unsigned seed, unsigned n_cpus)
+{
+	til_module_context_t	*module_context;
+
+	assert(size >= sizeof(til_module_context_t));
+	assert(n_cpus > 0);
+
+	module_context = calloc(1, size);
+	if (!module_context)
+		return NULL;
+
+	module_context->seed = seed;
+	module_context->n_cpus = n_cpus;
+
+	return module_context;
+}
+
+
+/* Free the module_context when non-NULL, using module_context->module->destroy_context if non-NULL.
+ * Always returns NULL for uses like foo = til_module_context_free(foo);
+ *
+ * Note this replaces til_module_destroy_context(), which has been removed.
+ */
+void * til_module_context_free(til_module_context_t *module_context)
+{
+	if (!module_context)
+		return NULL;
+
+	if (module_context->module->destroy_context)
+		module_context->module->destroy_context(module_context);
+	else
+		free(module_context);
+
+	return NULL;
+}
diff --git a/src/til_module_context.h b/src/til_module_context.h
new file mode 100644
index 0000000..3751b84
--- /dev/null
+++ b/src/til_module_context.h
@@ -0,0 +1,16 @@
+#ifndef _TIL_MODULE_CONTEXT_H
+#define _TIL_MODULE_CONTEXT_H
+
+typedef struct til_module_context_t til_module_context_t;
+typedef struct til_module_t til_module_t;
+
+struct til_module_context_t {
+	const til_module_t	*module;
+	unsigned		seed;
+	unsigned		n_cpus;
+};
+
+void * til_module_context_new(size_t size, unsigned seed, unsigned n_cpus);
+void * til_module_context_free(til_module_context_t *module_context);
+
+#endif