clap

CLAP Audio Plugin API
Log | Files | Refs | README | LICENSE

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:
Minclude/clap/ext/params.h | 5++++-
Minclude/clap/ext/thread-check.h | 19++++++++++++++++++-
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]