clap

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

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