< Engine Instantiation System¶

Module: 08_02_00_engine_instantiation Purpose: Factory-based DSP engine creation and lifecycle management Status: Complete

= Overview¶

This module provides the foundation for creating, managing, and pooling DSP engines in the AudioLab framework. It implements:

EngineFactory: Dynamic registration and creation of engine types
EnginePool: Object pooling for efficient reuse
EngineLifecycleManager: State machine for engine lifecycle
EngineDescriptor: Metadata about engine capabilities

< Architecture¶


                    Engine Instantiation                  

           
     Factory      Engine         Pool     
   (Registry)        (Instance)        (Reuse)    
           

      
           EngineLifecycleManager                      
    [Created]  [Prepared]  [Active]  [Destroyed]

= Quick Start¶

1. Register an Engine Type¶

// In your engine's .cpp file
#include "EngineFactory.hpp"

class MyCompressor : public IAudioEngine {
    // ... implementation ...
};

// Register at static initialization
REGISTER_ENGINE("Compressor", MyCompressor);

2. Create Engine Instance¶

#include "EngineFactory.hpp"

// Simple creation
auto& factory = EngineFactory::getInstance();
auto compressor = factory.createEngine("Compressor");

// With configuration
auto filter = factory.createEngine("BiquadFilter",
    R"({"type": "lowpass", "cutoff": 1000})");

3. Use Engine Pool¶

#include "EnginePool.hpp"

// Create pool with 4 pre-allocated instances
EnginePool compPool("Compressor", 4);

// Acquire from pool (fast!)
auto comp1 = compPool.acquire();
auto comp2 = compPool.acquire();

// Use engines...
comp1->processBlock(buffer);

// Return to pool
compPool.release(std::move(comp1));

4. Manage Lifecycle¶

#include "EngineLifecycleManager.hpp"

// Create and manage engine
auto engine = EngineFactory::getInstance().createEngine("Reverb");
EngineLifecycleManager manager(std::move(engine));

// Lifecycle: Created  Prepared  Active
manager.prepare(48000.0, 512, 2);
manager.activate();

// Process audio
while (isPlaying) {
    if (manager.isActive()) {
        manager.getEngine()->processBlock(buffer);
        manager.notifyBlockProcessed();
    }
}

// Pause and resume
manager.suspend();
manager.activate();

// Cleanup
manager.destroy();

= Components¶

EngineFactory¶

Purpose: Central registry for dynamic engine creation

Features: - Thread-safe registration - Runtime engine discovery - REGISTER_ENGINE macro for auto-registration - Configuration string support

API:

void registerEngine(const std::string& type, EngineCreator creator);
bool isRegistered(const std::string& type) const;
std::unique_ptr<IAudioEngine> createEngine(const std::string& type,
                                           const std::string& config);
std::vector<std::string> getRegisteredEngines() const;

EnginePool¶

Purpose: Object pool for efficient engine reuse

Features: - Pre-allocation to avoid RT allocations - Bounded pool size - Automatic engine reset on release - Thread-safe acquire/release

API:

EnginePool(const std::string& engineType, size_t initialSize = 4,
           const std::string& engineConfig = "");
std::unique_ptr<IAudioEngine> acquire();
void release(std::unique_ptr<IAudioEngine> engine);
void setMaxSize(size_t maxSize);
void preallocate(size_t count);
size_t getActiveCount() const;
size_t getPoolSize() const;

Performance: - Acquire: ~0.01ms (from pool) vs ~1-5ms (new allocation) - Release: ~0.01ms - Zero allocations after pre-warming

EngineLifecycleManager¶

Purpose: State machine for engine lifecycle

State Transitions:

[Created] prepare() [Prepared] activate() [Active]

                            suspend()

                           destroy()  [Destroyed]

API:

bool prepare(double sampleRate, uint32_t blockSize, uint32_t numChannels);
bool activate();
bool suspend();
bool destroy();
State getState() const;
bool isActive() const;
IAudioEngine* getEngine();
uint64_t getProcessedBlocks() const;
double getUptimeSeconds() const;

Features: - State validation (prevents invalid transitions) - Uptime tracking - Block counter - Thread-safe queries

EngineDescriptor¶

Purpose: Metadata about engine capabilities

Builder Pattern:

auto desc = EngineDescriptor()
    .setName("Biquad Filter")
    .setCategory(EngineCategory::Filter)
    .setVersion(2, 1, 0)
    .setAuthor("AudioLab")
    .setDescription("Second-order IIR filter")
    .setChannelConfig(1, 8, 1, 8)  // 1-8 in, 1-8 out
    .setLatency(0)
    .setSupportsSidechain(false)
    .addTag("linear")
    .addTag("biquad");

Categories: - Generator, Filter, Dynamics, Modulation - TimeEffect, Distortion, Utility, Analysis, Spatial

> Testing¶

Build Tests¶

cd 4 - INTEGRATION/08_PLUGINS/08_02_dsp_integration_layer/08_02_00_engine_instantiation
mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build .

Run Tests¶

./test_engine_instantiation.exe

Test Coverage¶

Factory registration and creation
Pool acquire/release cycles
Pool pre-allocation
Lifecycle state transitions
Invalid transition handling
Uptime tracking
Descriptor validation
Thread safety (basic)

= Performance Characteristics¶

Operation	Time	Notes
Register engine	~1s	Static init only
Create engine (factory)	1-5ms	Includes allocation
Acquire from pool	~10s	Pre-allocated
Release to pool	~10s	Includes reset()
State transition	~1s	Atomic operations

=' Integration¶

Include in CMake¶

add_subdirectory(08_02_00_engine_instantiation)

target_link_libraries(your_target
    PRIVATE engine_instantiation
)

Dependencies¶

Required: - 08_00_plugin_infrastructure (IAudioEngine interface) - 04_CORE/04_01_core_interfaces (IAudioProcessor, IActivatable)

Optional: - Catch2 3.x (for tests)

< Use Cases¶

L4 Plugins (Simple)¶

// Single compressor instance
auto comp = EngineFactory::getInstance().createEngine("Compressor");
EngineLifecycleManager manager(std::move(comp));
manager.prepare(sampleRate, blockSize, numChannels);
manager.activate();

L5 Suite Plugins (Complex)¶

// Pool for multi-band processor (8 slots)
EnginePool compPool("Compressor", 8);
std::vector<std::unique_ptr<IAudioEngine>> bands;

for (int i = 0; i < numBands; ++i) {
    bands.push_back(compPool.acquire());
    bands[i]->prepareToPlay(sampleRate, blockSize, 2);
}

// Process each band
for (auto& band : bands) {
    band->processBlock(bandBuffer);
}

// Release all
for (auto& band : bands) {
    compPool.release(std::move(band));
}

= Further Reading¶

= Troubleshooting¶

Engine Type Not Found¶

Error: EngineFactory::createEngine - Unknown engine type: Foo

Solution: Ensure REGISTER_ENGINE("Foo", FooClass); is in a .cpp file that's linked.

Pool Empty¶

If acquire() takes long time: - Pre-allocate more engines: pool.preallocate(10); - Increase max size: pool.setMaxSize(20);

Invalid State Transition¶

manager.activate();  // Returns false

Solution: Check current state with manager.getState(). Ensure correct sequence: prepare() activate() suspend() destroy()

Version: 1.0.0 Last Updated: 2025-10-09 Status: Production Ready

< Engine Instantiation System¶

= Overview¶

< Architecture¶

= Quick Start¶

1. Register an Engine Type¶

2. Create Engine Instance¶

3. Use Engine Pool¶

4. Manage Lifecycle¶

= Components¶

EngineFactory¶

EnginePool¶

EngineLifecycleManager¶

EngineDescriptor¶

> Testing¶

Build Tests¶

Run Tests¶

Test Coverage¶

= Performance Characteristics¶

=' Integration¶

Include in CMake¶

Dependencies¶

< Use Cases¶

L4 Plugins (Simple)¶

L5 Suite Plugins (Complex)¶

= Further Reading¶

= Troubleshooting¶

Engine Type Not Found¶

Pool Empty¶

Invalid State Transition¶

< Architecture¶

= Troubleshooting¶