thread-check.h (3708B)
1 #pragma once 2 3 #include "../plugin.h" 4 5 static CLAP_CONSTEXPR const char CLAP_EXT_THREAD_CHECK[] = "clap.thread-check"; 6 7 #ifdef __cplusplus 8 extern "C" { 9 #endif 10 11 /// @page thread-check 12 /// 13 /// CLAP defines two symbolic threads: 14 /// 15 /// main-thread: 16 /// This is the thread in which most of the interaction between the plugin and host happens. 17 /// This will be the same OS thread throughout the lifetime of the plug-in. 18 /// On macOS and Windows, this must be the thread on which gui and timer events are received 19 /// (i.e., the main thread of the program). 20 /// It isn't a realtime thread, yet this thread needs to respond fast enough to allow responsive 21 /// user interaction, so it is strongly recommended plugins run long,and expensive or blocking 22 /// tasks such as preset indexing or asset loading in dedicated background threads started by the 23 /// plugin. 24 /// 25 /// audio-thread: 26 /// This thread can be used for realtime audio processing. Its execution should be as 27 /// deterministic as possible to meet the audio interface's deadline (can be <1ms). There are a 28 /// known set of operations that should be avoided: malloc() and free(), contended locks and 29 /// mutexes, I/O, waiting, and so forth. 30 /// 31 /// The audio-thread is symbolic, there isn't one OS thread that remains the 32 /// audio-thread for the plugin lifetime. A host is may opt to have a 33 /// thread pool and the plugin.process() call may be scheduled on different OS threads over time. 34 /// However, the host must guarantee that single plugin instance will not be two audio-threads 35 /// at the same time. 36 /// 37 /// Functions marked with [audio-thread] **ARE NOT CONCURRENT**. The host may mark any OS thread, 38 /// including the main-thread as the audio-thread, as long as it can guarantee that only one OS 39 /// thread is the audio-thread at a time in a plugin instance. The audio-thread can be seen as a 40 /// concurrency guard for all functions marked with [audio-thread]. 41 /// 42 /// The real-time constraint on the [audio-thread] interacts closely with the render extension. 43 /// If a plugin doesn't implement render, then that plugin must have all [audio-thread] functions 44 /// meet the real time standard. If the plugin does implement render, and returns true when 45 /// render mode is set to real-time or if the plugin advertises a hard realtime requirement, it 46 /// must implement realtime constraints. Hosts also provide functions marked [audio-thread]. 47 /// These can be safely called by a plugin in the audio thread. Therefore hosts must either (1) 48 /// implement those functions meeting the real-time constraints or (2) not process plugins which 49 /// advertise a hard realtime constraint or don't implement the render extension. Hosts which 50 /// provide [audio-thread] functions outside these conditions may experience inconsistent or 51 /// inaccurate rendering. 52 /// 53 /// Clap also tags some functions as [thread-safe]. Functions tagged as [thread-safe] can be called 54 /// from any thread unless explicitly counter-indicated (for instance [thread-safe, !audio-thread]) 55 /// and may be called concurrently. 56 57 // This interface is useful to do runtime checks and make 58 // sure that the functions are called on the correct threads. 59 // It is highly recommended that hosts implement this extension. 60 typedef struct clap_host_thread_check { 61 // Returns true if "this" thread is the main thread. 62 // [thread-safe] 63 bool(CLAP_ABI *is_main_thread)(const clap_host_t *host); 64 65 // Returns true if "this" thread is one of the audio threads. 66 // [thread-safe] 67 bool(CLAP_ABI *is_audio_thread)(const clap_host_t *host); 68 } clap_host_thread_check_t; 69 70 #ifdef __cplusplus 71 } 72 #endif