INCLUDE: clap/ext/thread-check.h: briefly describe different host thread models
@@ -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]
