From ad76eb5cc44154055ce8060e5df9281cfadde6e2 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Mon, 8 Jan 2024 09:29:26 +0100 Subject: [PATCH] Update the documentation according to the latest discussions --- include/clap/entry.h | 51 ++++++++++++++++++-------------------------- 1 file changed, 21 insertions(+), 30 deletions(-) diff --git a/include/clap/entry.h b/include/clap/entry.h index 877dc941..44747224 100644 --- a/include/clap/entry.h +++ b/include/clap/entry.h @@ -31,42 +31,33 @@ extern "C" { // Each directory should be recursively searched for files and/or bundles as appropriate in your OS // ending with the extension `.clap`. // -// As detailed in the respective functions' documentations below, the host is forbidden from calling -// either init() or deinit() multiple times, without calling the other first. This is to enforce -// a "normal" initialization pattern, where one can't construct or destroy an object multiple times. +// init and deinit in most cases are called once, in a matched pair, when the dso is loaded / unloaded. +// In some rare situations it may be called multiple times in a process, so the functions must be defensive, +// mutex locking and counting calls if undertaking non trivial non idempotent actions. // -// However, there are a few cases where the host may not be able to reliably prevent this from -// happening, such as when multiple, separate hosts co-exist within the same address space (e.g. -// Meta-Plugins, plugins that can host other plugins inside them). It may also happen when a VST -// compatibility layer is used to wrap a CLAP plugin, for instance. +// Rationale: // -// In those cases, the init() and deinit() pair of functions can happen to be called multiple times, -// either in a row or even simultaneously, from different threads, by multiple non-synchronized -// hosts, or by a single host that is presented multiple interfaces to a same DSO. This can happen -// even though this is forbidden behavior from the host by this specification, and despite a -// compliant host's best efforts. +// The intent of the init() and deinit() functions is to provide a "normal" initialization patterh +// which occurs when the shared object is loaded or unloaded. As such, hosts will call each once and +// in matched pairs. In clap specifications prior to 1.1.11, this single-call was documented as a +// requirement. // -// Despite those issues, hosts *must* ensure that each successful call to init() is only followed by -// a single call to deinit() at most. As long as a single successful init() call did not have its -// matching deinit() called, the DSO *must* remain in a fully operational state, as if deinit() had -// not yet been called. +// We realized, though, that this is not a requirement hosts can meet. If hosts load a plugin +// which itself wraps another CLAP for instance, while also loading that same clap in its memory +// space, both the host and the wrapper will call init() and deinit() and have no means to communicate +// the state. // -// Therefore, init() and deinit() functions *should* be implemented in a way that allows for init() -// to be called any number of times in a row (possibly simultaneously, from multiple threads), and -// for deinit() to be called at most that same number of times (also simultaneously, from multiple, -// possibly different threads from the init() called). As of CLAP 1.11, this *must* be the case for -// all plugin implementations. +// With clap 1.1.11 and beyond we are changing the spec to indicate that a host should make an +// absolute best effort to call init() and deinit() once, and always in matched pairs (for every +// init() which returns true, one deinit() should be called). // -// This is already trivially the case if there is no (de)initialization work in the entry at all, -// or if the initialization work is thread safe and idempotent, and there is no de-initialization -// work to be done. Those implementations already are and remain valid, and require no additional -// consideration. +// This takes the de-facto burden on plugin writers to deal with multiple calls into a hard requirement. // -// If that is not the case, then using a global, refcount-like locked initialization counter can be -// used to keep track of init() and deinit() calls. Then the initialization work can be done only -// when the counter goes from 0 to 1 in init(), and de-initialization can be done when the counter -// goes to 0 in deinit(). Any subsequent calls to init() and deinit() can just increase or decrease -// the counter, respectively. +// Most init() / deinit() pairs we have seen are the relatively trivial {return true;} and {}. But +// if your init() function does non-trivial one time work, the plugin author must maintain a counter +// and must manage a mutex lock. The most obvious implementation will maintain a static counter and a +// global mutex, increment the counter on each init, decrement it on each deinit, and only undertake +// the init or deinit action when the counter is zero. typedef struct clap_plugin_entry { clap_version_t clap_version; // initialized to CLAP_VERSION