commit b317f7b03b25e77f4f97b75c86ab43bcc7265790
parent f4ccab85192e28562709a107359ccea3be73d120
Author: Alexandre Bique <bique.alexandre@gmail.com>
Date: Fri, 15 Jul 2022 08:46:28 +0200
Merge pull request #131 from tim-janik/threading
Threading clarifications
Diffstat:
2 files changed, 22 insertions(+), 2 deletions(-)
diff --git a/include/clap/ext/params.h b/include/clap/ext/params.h
@@ -278,7 +278,10 @@ typedef struct clap_host_params {
void (*clear)(const clap_host_t *host, clap_id param_id, clap_param_clear_flags flags);
- // Request a parameter flush.
+ // Request a parameter flush. Note that this is not useful to call from an
+ // [audio-thread], because a plugin executing within any [audio-thread] is either:
+ // 1. within process() (which may include clap_plugin_thread_pool->exec)
+ // 2. within flush()
//
// The host will then schedule a call to either:
// - clap_plugin.process()
diff --git a/include/clap/ext/thread-check.h b/include/clap/ext/thread-check.h
@@ -8,9 +8,26 @@ static CLAP_CONSTEXPR const char CLAP_EXT_THREAD_CHECK[] = "clap.thread-check";
extern "C" {
#endif
+/* A note on threads as understood by CLAP:
+ *
+ * In the [main-thread], a CLAP plugin may carry out allocations, acquire a mutex and do IO,
+ * basically anything a reasonably performing program could do. Long running tasks such as
+ * indexing presets, should still be run in background threads to keep the [main-thread] responsive.
+ *
+ * Within an [audio-thread] (of which there may be many in a given host), plugins should strive
+ * to meet realtime requirements. I.e. only carry out sufficiently performant and time-bound
+ * operations. So mutexes, memory (de-)allocations, IO, UI rendering should generally be avoided.
+ *
+ * Depending on the host scheduler, the [audio-thread] may move from one OS thread to another,
+ * including the same OS thread as the [main-thread].
+ * So while plugins are encouraged to use the thread checking functions and may assert
+ * is_main_thread() == true or is_audio_thread() == true in a particular context, it should
+ * be avoided to assert that the current thread is *NOT* is_main_thread() or is_audio_thread().
+ */
+
// This interface is useful to do runtime checks and make
// sure that the functions are called on the correct threads.
-// It is highly recommended to implement this extension
+// It is highly recommended that hosts implement this extension.
typedef struct clap_host_thread_check {
// Returns true if "this" thread is the main thread.
// [thread-safe]
