Initial commit

tests/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