commit c258e8bfb8841cb4e07eba0c1dab2af1d2454644
parent 2e48649ea2dd49e82b0b260be4c5314d07c89bfc
Author: jatin <jatinchowdhury18@gmail.com>
Date: Tue, 8 Oct 2024 11:52:26 -0700
draft scratch-memory extension
Diffstat:
3 files changed, 92 insertions(+), 0 deletions(-)
diff --git a/include/clap/all.h b/include/clap/all.h
@@ -11,3 +11,4 @@
#include "ext/draft/triggers.h"
#include "ext/draft/tuning.h"
#include "ext/draft/undo.h"
+#include "ext/draft/scratch-memory.h"
diff --git a/include/clap/ext/draft/scratch-memory.h b/include/clap/ext/draft/scratch-memory.h
@@ -0,0 +1,90 @@
+#pragma once
+
+#include "../../plugin.h"
+
+// This extension lets the plugin request "scratch" memory from the host.
+//
+// The scratch memory is thread-local, and can be accessed during
+// `clap_plugin->process()` and `clap_plugin_thread_pool->exec()`;
+// its content is not persistent between callbacks.
+//
+// The motivation for this extension is to allow the plugin host
+// to "share" a single scratch buffer across multiple plugin
+// instances.
+//
+// For example, imagine the host needs to process N plugins
+// in sequence, and each plugin requires 10K of scratch memory.
+// If each plugin pre-allocates its own scratch memory, then N * 10K
+// of memory is being allocated in total. However, if each plugin
+// requests 10K of scratch memory from the host, then the host can
+// allocate a single 10K scratch buffer, and make it available to all
+// plugins.
+//
+// This optimization may allow for reduced memory usage and improved
+// CPU cache usage.
+
+static CLAP_CONSTEXPR const char CLAP_EXT_SCRATCH_MEMORY[] = "clap.scratch-memory/1";
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct clap_host_scratch_memory {
+ // Asks the host to reserve scratch memory.
+ //
+ // The plugin may call this method multiple times (for
+ // example, gradually decreasing the amount of scratch
+ // being asked for until the host returns true), however,
+ // the plugin should avoid calling this method un-neccesarily
+ // since the host implementation may be relatively expensive.
+ // If the plugin calls `reserve()` multiple times, then the
+ // last call invalidates all previous calls.
+ //
+ // De-activating the plugin releases the scratch memory.
+ //
+ // `max_concurrency_hint` is an optional hint which indicates
+ // the maximum number of threads concurrently accessing the scratch memory.
+ // Set to 0 if unspecified.
+ //
+ // Returns true on success.
+ //
+ // [main-thread & being-activated]
+ bool(CLAP_ABI *reserve)(const clap_host_t *host,
+ uint32_t scratch_size_bytes,
+ uint32_t max_concurrency_hint);
+
+ // Returns a pointer to the "thread-local" scratch memory.
+ //
+ // If the scratch memory wasn't successfully reserved, returns NULL.
+ //
+ // If the plugin crosses `max_concurrency_hint`, then the return value
+ // is either NULL or a valid scratch memory pointer.
+ //
+ // This method may only be called by the plugin from the audio thread,
+ // (i.e. during the process() or thread_pool.exec() callback), and
+ // the provided memory is only valid until the plugin returns from
+ // that callback. The plugin must not hold any references to data
+ // that lives in the scratch memory after returning from the callback,
+ // as that data will likely be over-written by another plugin using
+ // the same scratch memory.
+ //
+ // The provided memory is not initialized, and may have been used
+ // by other plugin instances, so the plugin must correctly initialize
+ // the memory when using it.
+ //
+ // The provided memory is owned by the host, so the plugin must not
+ // free the memory.
+ //
+ // If the plugin wants to share the same scratch memory pointer with
+ // many threads, it must access the the scratch at the beginning of the
+ // `process()` callback, cache the returned pointer before calling
+ // `clap_host_thread_pool->request_exec()` and clear the cached pointer
+ // before returning from `process()`.
+ //
+ // [audio-thread]
+ void *(CLAP_ABI *access)(const clap_host_t *host);
+} clap_host_scratch_memory_t;
+
+#ifdef __cplusplus
+}
+#endif
diff --git a/include/clap/plugin.h b/include/clap/plugin.h
@@ -61,6 +61,7 @@ typedef struct clap_plugin {
// In this call the plugin may allocate memory and prepare everything needed for the process
// call. The process's sample rate will be constant and process's frame count will included in
// the [min, max] range, which is bounded by [1, INT32_MAX].
+ // In this call the plugin may call host-provided methods marked [being-activated].
// Once activated the latency and port configuration must remain constant, until deactivation.
// Returns true on success.
// [main-thread & !active]
