*: pivot to til_module_context_t

- modules now allocate their contexts using
  til_module_context_new() instead of [cm]alloc().

- modules simply embed til_module_context_t at the start of their
  respective private context structs, if they do anything with
  contexts

- modules that do nothing with contexts (lack a create_context()
  method), will now *always* get a til_module_context_t supplied
  to their other methods regardless of their create_context()
  presence.  So even if you don't have a create_context(), your
  prepare_frame() and/or render_fragment() methods can still
  access seed and n_cpus from within the til_module_context_t
  passed in as context, *always*.

- modules that *do* have a create_context() method, implying they
  have their own private context type, will have to cast the
  til_module_context_t supplied to the other methods to their
  private context type.  By embedding the til_module_context_t at
  the *start* of their private context struct, a simple cast is
  all that's needed.  If it's placed somewhere else, more
  annoying container_of() style macros are needed - this is
  strongly discouraged, just put it at the start of struct.

- til_module_create_context() now takes n_cpus, which may be set
  to 0 for automatically assigning the number of threads in its
  place.  Any non-zero value is treated as an explicit n_cpus,
  primarily intended for setting it to 1 for single-threaded
  contexts necessary when embedded within an already-threaded
  composite module.

- modules like montage which open-coded a single-threaded render
  are now using the same til_module_render_fragment() as
  everything else, since til_module_create_context() is accepting
  n_cpus.

- til_module_create_context() now produces a real type, not void
  *, that is til_module_context_t *.  All the other module
  context functions now operate on this type, and since
  til_module_context_t.module tracks the module this context
  relates to, those functions no longer require both the module
  and context be passed in.  This is especially helpful for
  compositing modules which do a lot of module context creation
  and destruction; the module handle is now only needed to create
  the contexts.  Everything else operating on that context only
  needs the single context pointer, not module+context pairs,
  which was unnecessarily annoying.

- if your module's context can be destroyed with a simple free(),
  without any deeper knowledge or freeing of nested pointers, you
  can now simply omit destroy_context() altogether.  When
  destroy_context() is missing, til_module_context_free() will
  automatically use libc's free() on the pointer returned from
  your create_context() (or on the pointer that was automatically
  created if you omitted create_context() too, for the
  bare til_module_context_t that got created on your behalf
  anyways).

For the most part, these changes don't affect module creation.

In some ways this eases module creation by making it more
convenient access seed and n_cpus if you had no further
requirement for a context struct.

In other ways it's slightly annoying to have to do type-casts
when you're working with your own context type, since before it
was all void* and didn't require casts when assigning to your
typed context variables.

The elimination for requiring a destroy_context() method in
simple free() of private context scenarios removes some
boilerplate in simple cases.

I think it's a wash for module writers, or maybe a slight win for
the simple cases.

1 files changed, 18 insertions, 17 deletions

diff --git a/src/til.h b/src/til.h
index 91ed157..ab8f6b8 100644
--- a/src/til.h
+++ b/src/til.h
@@ -2,11 +2,12 @@
 #define _TIL_H
 
 #include "til_fb.h"
+#include "til_module_context.h"
 #include "til_setup.h"
 
 /* til_fragmenter produces fragments from an input fragment, num being the desired fragment for the current call.
  * return value of 1 means a fragment has been produced, 0 means num is beyond the end of fragments. */
-typedef int (*til_fragmenter_t)(void *context, unsigned n_cpus, const til_fb_fragment_t *fragment, unsigned number, til_fb_fragment_t *res_fragment);
+typedef int (*til_fragmenter_t)(til_module_context_t *context, const til_fb_fragment_t *fragment, unsigned number, til_fb_fragment_t *res_fragment);
 
 typedef struct til_settings_t settings;
 typedef struct til_setting_desc_t til_setting_desc_t;
@@ -15,17 +16,17 @@ typedef struct til_knob_t til_knob_t;
 #define TIL_MODULE_OVERLAYABLE	1u
 
 typedef struct til_module_t {
-	void *		(*create_context)(unsigned seed, unsigned ticks, unsigned n_cpus, til_setup_t *setup);
-	void		(*destroy_context)(void *context);
-	void		(*prepare_frame)(void *context, unsigned ticks, unsigned n_cpus, til_fb_fragment_t *fragment, til_fragmenter_t *res_fragmenter);
-	void		(*render_fragment)(void *context, unsigned ticks, unsigned cpu, til_fb_fragment_t *fragment);
-	void		(*finish_frame)(void *context, unsigned ticks, til_fb_fragment_t *fragment);
-	int		(*setup)(const til_settings_t *settings, til_setting_t **res_setting, const til_setting_desc_t **res_desc, til_setup_t **res_setup);
-	size_t		(*knobs)(void *context, til_knob_t **res_knobs);
-	char		*name;
-	char		*description;
-	char		*author;
-	unsigned	flags;
+	til_module_context_t *	(*create_context)(unsigned seed, unsigned ticks, unsigned n_cpus, til_setup_t *setup);
+	void			(*destroy_context)(til_module_context_t *context);
+	void			(*prepare_frame)(til_module_context_t *context, unsigned ticks, til_fb_fragment_t *fragment, til_fragmenter_t *res_fragmenter);
+	void			(*render_fragment)(til_module_context_t *context, unsigned ticks, unsigned cpu, til_fb_fragment_t *fragment);
+	void			(*finish_frame)(til_module_context_t *context, unsigned ticks, til_fb_fragment_t *fragment);
+	int			(*setup)(const til_settings_t *settings, til_setting_t **res_setting, const til_setting_desc_t **res_desc, til_setup_t **res_setup);
+	size_t			(*knobs)(til_module_context_t *context, til_knob_t **res_knobs);
+	char			*name;
+	char			*description;
+	char			*author;
+	unsigned		flags;
 } til_module_t;
 
 int til_init(void);
@@ -33,12 +34,12 @@ void til_quiesce(void);
 void til_shutdown(void);
 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);
-void til_module_render(const til_module_t *module, void *context, unsigned ticks, til_fb_fragment_t *fragment);
-int til_module_create_context(const til_module_t *module, unsigned seed, unsigned ticks, til_setup_t *setup, void **res_context);
-void * til_module_destroy_context(const til_module_t *module, void *context);
+void til_module_render(til_module_context_t *context, unsigned ticks, til_fb_fragment_t *fragment);
+int til_module_create_context(const til_module_t *module, 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);
 int til_module_setup(til_settings_t *settings, til_setting_t **res_setting, const til_setting_desc_t **res_desc, til_setup_t **res_setup);
 int til_module_randomize_setup(const til_module_t *module, til_setup_t **res_setup, char **res_arg);
-int til_fragmenter_slice_per_cpu(void *context, unsigned n_cpus, const til_fb_fragment_t *fragment, unsigned number, til_fb_fragment_t *res_fragment);
-int til_fragmenter_tile64(void *context, unsigned n_cpus, const til_fb_fragment_t *fragment, unsigned number, til_fb_fragment_t *res_fragment);
+int til_fragmenter_slice_per_cpu(til_module_context_t *context, const til_fb_fragment_t *fragment, unsigned number, til_fb_fragment_t *res_fragment);
+int til_fragmenter_tile64(til_module_context_t *context, const til_fb_fragment_t *fragment, unsigned number, til_fb_fragment_t *res_fragment);
 
 #endif