Limiting Plugin Instance Creation

ManiVault supports limiting how many instances of a given plugin can be created. This is useful when:

A plugin is expensive (GPU/CPU/memory heavy) and should not be instantiated many times.
A plugin represents a singleton-like resource (e.g., a global service, exclusive device handle).
An application designer wants a curated workflow, where only a controlled set of plugin instances can be added.

This page documents the API for querying instance counts and configuring the maximum number of allowed instances.

Concepts

The API distinguishes between two counters and one limit:

Number of instances (loaded)
The number of plugin instances that are currently alive/loaded in the application.
Number of instances produced (lifetime total)
The total number of instances that have been created during the current application session (even if they were later closed/unloaded).
Maximum number of instances
The upper bound on how many instances may exist at the same time. If the maximum is reached, additional instances are not created.

Unlimited instances
If maximumNumberOfInstances == -1, there is no limit. Because the API uses std::uint32_t, this value is represented as:
static_cast<std::uint32_t>(-1)
// or equivalently
std::numeric_limits<std::uint32_t>::max()
In other words: the “no limit” sentinel is the maximum representable uint32_t value.

API

Querying the current number of loaded instances

std::uint32_t getNumberOfInstances() const;

Returns the number of plugin instances currently loaded.

Setting the current number of loaded instances

void setNumberOfInstances(std::uint32_t numberOfInstances);

Sets the number of plugin instances currently loaded.

In normal usage you should not need to call this directly. The core maintains these counters internally.

Querying the total number of instances produced

std::uint32_t getNumberOfInstancesProduced() const;

Returns the total number of instances produced during the current application session.

Setting the total number of instances produced

void setNumberOfInstancesProduced(std::uint32_t numberOfInstancesProduced);

Sets the total number of produced instances.

In normal usage you should not need to call this directly. The core maintains these counters internally.

Querying the maximum number of allowed instances

std::uint32_t getMaximumNumberOfInstances() const;

Returns the maximum number of instances allowed to exist simultaneously.

Setting the maximum number of allowed instances

void setMaximumNumberOfInstances(std::uint32_t maximumNumberOfInstances);

Sets the maximum number of instances allowed to exist simultaneously.

Signals

The API provides signals that allow the UI (or other observers) to react to changes.

Loaded instance count changed

void numberOfInstancesChanged(std::uint32_t numberOfInstances);

Emitted when the number of currently loaded instances changes.

Total produced instance count changed

void numberOfInstancesProducedChanged(std::uint32_t numberOfInstancesProduced);

Emitted when the total number of produced instances changes.

Recommended Usage

Typical usage is to set a maximum (or leave it unlimited) and let the core enforce and track the counters.

// Allow at most one instance (singleton-style)
plugin->setMaximumNumberOfInstances(1);

// Allow unlimited instances (this is the default)
plugin->setMaximumNumberOfInstances(static_cast<std::uint32_t>(-1));