Skip to content

Commit

Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
draft scratch-memory extension
Browse files Browse the repository at this point in the history
jatinchowdhury18 authored and abique committed Nov 1, 2024
1 parent bcbf761 commit dbf7513
Showing 2 changed files with 92 additions and 0 deletions.
91 changes: 91 additions & 0 deletions include/clap/ext/draft/scratch-memory.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
#pragma once

#include "../../plugin.h"

// This extension lets the plugin request "scratch" memory
// from the host. Scratch memory can be accessed during the
// `process()` callback, but its content 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 three plugins
// in sequence, and each plugin requires 10K of scratch memory.
// If each plugin pre-allocates its own scratch memory, then 30K
// 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
// three 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 for certain amount of scratch memory.
// If the host is unable to provide the memory, it should
// return "false".
//
// 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
// final call determines the actual amount of scratch memory
// that will be available to the plugin. If the final call
// returns false then no scratch memory will be provided,
// regardless of any previous calls to `reserve()`.
//
// When the plugin is de-activated, the scratch memory
// is invalidated, and the host may free the memory if
// appropriate. The plugin will need to reserve scratch
// memory again the next time it is activated.
//
// In the context of plugins and hosts that implement
// 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.
//
// [main-thread & being-activated]
bool(CLAP_ABI *reserve)(const clap_host_t *host, uint32_t scratch_size_bytes);

// Asks the host for the previously reserved scratch memory.
// If the host returned "true" when scratch memory was requested,
// then this method must return a pointer to a memory block at least
// as large as the reserved size. If the host returned "false"
// when scratch memory was requested, then this method must not
// be called, and will return NULL.
//
// 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 should not
// attempt to free the memory.
//
// [audio-thread]
void*(CLAP_ABI *access)(const clap_host_t *host);
} clap_host_scratch_memory_t;

#ifdef __cplusplus
}
#endif
1 change: 1 addition & 0 deletions include/clap/plugin.h
Original file line number Diff line number Diff line change
@@ -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]

0 comments on commit dbf7513

Please sign in to comment.