From 2896549b9dc5327c6d90c449f549bc143c2e0610 Mon Sep 17 00:00:00 2001 From: Peter Bridgman Date: Tue, 3 Dec 2024 19:21:29 +0000 Subject: [PATCH] ext/draft/scratch-memory: Specify `num_concurrent_buffers` This commit adds a new parameter to the `reserve()` method of the draft `scratch-memory` extension which allows a plugin to indicate to the host whether its `thread-pool` tasks need to access scratch memory buffers or not, and if so, how many of them the host must accommodate. --- include/clap/ext/draft/scratch-memory.h | 42 ++++++++++++++++++++++--- 1 file changed, 38 insertions(+), 4 deletions(-) diff --git a/include/clap/ext/draft/scratch-memory.h b/include/clap/ext/draft/scratch-memory.h index bbfa61a6..39d54039 100644 --- a/include/clap/ext/draft/scratch-memory.h +++ b/include/clap/ext/draft/scratch-memory.h @@ -53,12 +53,27 @@ typedef struct clap_host_scratch_memory { // the "thread-pool" extension, scratch memory is assumed // to be "thread-local". The plugin should request the maximum // amount of scratch memory that it will need on a single - // thread. Accordingly, the host must ensure that each - // thread can independently provide the requested amount - // of scratch memory. + // thread. + // + // The `num_concurrent_buffers` allows the host to ensure it can + // provide the requested amount of scratch memory when the + // `thread-pool` extension is used by indicating the maximum number + // of tasks that the plugin expects to run in parallel, and + // therefore how many different "thread-local" scratch buffers are + // required. + // + // - If `num_concurrent_buffers` = 0, then thread pool tasks do not + // require access to scratch memory, and calls to `access()` in a + // `thread_pool.exec()` context may return NULL. + // - If `num_concurrent_buffers` = N > 0, then the host must ensure + // that up to N thread-pool tasks can subsequently call `access()` + // to receive a thread-local scratch buffer during a + // `thread_pool.exec()` context. // // [main-thread & being-activated] - bool(CLAP_ABI *reserve)(const clap_host_t *host, uint32_t scratch_size_bytes); + bool(CLAP_ABI *reserve)(const clap_host_t *host, + uint32_t scratch_size_bytes, + uint32_t num_concurrent_buffers); // Asks the host for the previously reserved scratch memory. // If the host returned "true" when scratch memory was requested, @@ -67,6 +82,25 @@ typedef struct clap_host_scratch_memory { // when scratch memory was requested, then this method must not // be called, and will return NULL. // + // If this method is called from the `thread_pool.exec()` callback, then: + // - if the `num_concurrent_buffers` parameter passed to + // `reserve()` was zero, then this method may return NULL. + // - if the `task_index` of the current task is greater than or + // equal to the value passed to `num_concurrent_buffers`, then this + // method may return NULL. + // + // When called from the `thread_pool.exec()` callback, the returned + // scratch buffer is "thread-local", that is, no two concurrent + // executions of this method from different tasks will return the + // same non-NULL pointer. Non-concurrent executions on different + // tasks may return the same non-NULL pointer. + // + // The buffer returned in the `thread_pool.exec()` callback context + // might not be the same one as returned in the `process()` context; + // if a plugin wishes to uses the same scratch buffer everywhere, + // call `access()` in the `process()` context and share the returned + // pointer with the thread pool tasks. + // // 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