commit 74b36854d9c3ef0df0a9e0a6070aa08d7f5524de
parent e60671bec244f794e52c4d2c13a374c79883c51b
Author: Tim Janik <timj@gnu.org>
Date: Thu, 7 Jul 2022 01:10:13 +0200
INCLUDE: clap/ext/thread-check.h: briefly describe different host thread models
Signed-off-by: Tim Janik <timj@gnu.org>
Diffstat:
1 file changed, 16 insertions(+), 1 deletion(-)
diff --git a/include/clap/ext/thread-check.h b/include/clap/ext/thread-check.h
@@ -8,9 +8,24 @@ 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,
+ * bascially anything a reasonably performing program could do.
+ *
+ * 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, [main-thread] and [audio-thread] may or may not map to the same
+ * system thread. So while plugins should 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]
