72 lines
3.6 KiB
C
72 lines
3.6 KiB
C
|
#pragma once
|
||
|
|
|
||
|
|
#include "../plugin.h"
|
||
|
|
|
||
|
|
static CLAP_CONSTEXPR const char CLAP_EXT_THREAD_CHECK[] = "clap.thread-check";
|
||
|
|
|
||
|
|
#ifdef __cplusplus
|
||
|
|
extern "C" {
|
||
|
|
#endif
|
||
|
|
|
||
|
|
/// @page thread-check
|
||
|
|
///
|
||
|
|
/// CLAP defines two symbolic threads:
|
||
|
|
///
|
||
|
|
/// main-thread:
|
||
|
|
/// This is the thread in which most of the interaction between the plugin and host happens.
|
||
|
|
/// This will be the same OS thread throughout the lifetime of the plug-in.
|
||
|
|
/// On macOS and Windows, this must be the thread on which gui and timer events are received
|
||
|
|
/// (i.e., the main thread of the program).
|
||
|
|
/// It isn't a realtime thread, yet this thread needs to respond fast enough to allow responsive
|
||
|
|
/// user interaction, so it is strongly recommended plugins run long,and expensive or blocking
|
||
|
|
/// tasks such as preset indexing or asset loading in dedicated background threads started by the
|
||
|
|
/// plugin.
|
||
|
|
///
|
||
|
|
/// audio-thread:
|
||
|
|
/// This thread can be used for realtime audio processing. Its execution should be as
|
||
|
|
/// deterministic as possible to meet the audio interface's deadline (can be <1ms). There are a
|
||
|
|
/// known set of operations that should be avoided: malloc() and free(), contended locks and
|
||
|
|
/// mutexes, I/O, waiting, and so forth.
|
||
|
|
///
|
||
|
|
/// The audio-thread is symbolic, there isn't one OS thread that remains the
|
||
|
|
/// audio-thread for the plugin lifetime. A host is may opt to have a
|
||
|
|
/// thread pool and the plugin.process() call may be scheduled on different OS threads over time.
|
||
|
|
/// However, the host must guarantee that single plugin instance will not be two audio-threads
|
||
|
|
/// at the same time.
|
||
|
|
///
|
||
|
|
/// Functions marked with [audio-thread] **ARE NOT CONCURRENT**. The host may mark any OS thread,
|
||
|
|
/// including the main-thread as the audio-thread, as long as it can guarantee that only one OS
|
||
|
|
/// thread is the audio-thread at a time in a plugin instance. The audio-thread can be seen as a
|
||
|
|
/// concurrency guard for all functions marked with [audio-thread].
|
||
|
|
///
|
||
|
|
/// The real-time constraint on the [audio-thread] interacts closely with the render extension.
|
||
|
|
/// If a plugin doesn't implement render, then that plugin must have all [audio-thread] functions
|
||
|
|
/// meet the real time standard. If the plugin does implement render, and returns true when
|
||
|
|
/// render mode is set to real-time or if the plugin advertises a hard realtime requirement, it
|
||
|
|
/// must implement realtime constraints. Hosts also provide functions marked [audio-thread].
|
||
|
|
/// These can be safely called by a plugin in the audio thread. Therefore hosts must either (1)
|
||
|
|
/// implement those functions meeting the real-time constraints or (2) not process plugins which
|
||
|
|
/// advertise a hard realtime constraint or don't implement the render extension. Hosts which
|
||
|
|
/// provide [audio-thread] functions outside these conditions may experience inconsistent or
|
||
|
|
/// inaccurate rendering.
|
||
|
|
///
|
||
|
|
/// Clap also tags some functions as [thread-safe]. Functions tagged as [thread-safe] can be called
|
||
|
|
/// from any thread unless explicitly counter-indicated (for instance [thread-safe, !audio-thread])
|
||
|
|
/// and may be called concurrently.
|
||
|
|
|
||
|
|
// This interface is useful to do runtime checks and make
|
||
|
|
// sure that the functions are called on the correct threads.
|
||
|
|
// 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]
|
||
|
|
bool(CLAP_ABI *is_main_thread)(const clap_host_t *host);
|
||
|
|
|
||
|
|
// Returns true if "this" thread is one of the audio threads.
|
||
|
|
// [thread-safe]
|
||
|
|
bool(CLAP_ABI *is_audio_thread)(const clap_host_t *host);
|
||
|
|
} clap_host_thread_check_t;
|
||
|
|
|
||
|
|
#ifdef __cplusplus
|
||
|
|
}
|
||
|
|
#endif
|