Add hybrid plugin system

[feltech]

Description

Closes #1202.

OpenAssetIO currently supports two different manager plugin backends in the core library, Python and C++. We expect more backends to be added in the future. For example, there has been active investigation into a gRPC backend.

By "backend" we specifically mean an implementation of the abstract base class ManagerImplementationFactoryInterface. The host application chooses an implementation, then injects it into a ManagerFactory, which is then responsible for producing Manager instances that the host application can use.

The idea of a hybrid plugin system is to allow multiple backend plugin providers to be composed, such that API calls can be routed to the most appropriate plugin. For example, performance-critical API requests could route to a C++ plugin, whilst less critical requests route to a Python plugin.

As an added bonus, having a built-in facility to compose multiple backends reduces boilerplate for hosts that wish to support multiple plugin system backends.

So add a HybridPluginSystemManagerImplementationFactory, which implements the ManagerImplementationFactoryInterface interface, and takes a list of child ManagerImplementationFactoryInterface implementations during construction. The host application can then provide an instance of a hybrid factory to their ManagerFactory, taking care of the boilerplate of managing multiple plugin systems.

When a host application attempts to load a plugin with a particular unique identifier, then all child plugin systems are searched. If a match is found in a single plugin system, then its manager implementation is returned directly. If a match is found in multiple plugin systems, then a proxy manager is constructed that routes calls to the appropriate manager implementation.

The "appropriate" manager implementation to route to varies. In most cases, the highest priority implementation that advertises the capability associated with the API call is chosen (i.e. it is routed based on the response of the manager(s) to hasCapability(...)).

The priority order of implementations corresponds to the order of the child factories in the list that was provided to the hybrid factory on construction.

Some API methods don't have an associated capability. For these, routing is "common sense":

For initialize, all implementations are provided with all the settings. For example, if using a .toml OpenAssetIO config file (see OPENASSETIO_DEFAULT_CONFIG), then the settings in that file will be provided to all the matching manager implementations. This could cause problems if two plugins use the same settings key but require different values. Future work may look at ways to disambiguate.

For identifier and displayName the highest priority manager implementation is chosen.

For info and settings, the results of all manager implementations are merged, with the highest priority manager taking precedence if any dictionary keys conflict.

For flushCaches all manager implementations are flushed.

• I have updated the release notes.
• I have updated all relevant user documentation.

Reviewer Notes

See Jupyter Notebook for illustration in OpenAssetIO/OpenAssetIO-MediaCreation#99

[feltech]

Set to Draft state pending #1348

[feltech]

For reference, output of "ABI diff check" CI job, before I update the ABI snapshot...

TLDR: it's just saying there's a new class, so there's no need to flag a breaking change in the release notes.

===== Checking ABI of libopenassetio.so.1.0.0 =====

Leaf changes summary: 8 artifacts changed
Changed leaf types summary: 0 leaf type changed
Removed/Changed/Added functions summary: 0 Removed, 0 Changed, 4 Added functions
Removed/Changed/Added variables summary: 0 Removed, 0 Changed, 0 Added variable
Function symbols changes summary: 0 Removed, 0 Added function symbol not referenced by debug info
Variable symbols changes summary: 0 Removed, 4 Added variable symbols not referenced by debug info
Errors while running CTest

4 Added functions:

  [A] 'method openassetio::v1::pluginSystem::HybridPluginSystemManagerImplementationFactory::HybridPluginSystemManagerImplementationFactory(openassetio::v1::pluginSystem::HybridPluginSystemManagerImplementationFactory::ManagerImplementationFactoryInterfaces, openassetio::v1::log::LoggerInterfacePtr)'    {_ZN11openassetio2v112pluginSystem46HybridPluginSystemManagerImplementationFactoryC2ESt6vectorISt10shared_ptrINS0_7hostApi37ManagerImplementationFactoryInterfaceEESaIS7_EES4_INS0_3log15LoggerInterfaceEE, aliases _ZN11openassetio2v112pluginSystem46HybridPluginSystemManagerImplementationFactoryC1ESt6vectorISt10shared_ptrINS0_7hostApi37ManagerImplementationFactoryInterfaceEESaIS7_EES4_INS0_3log15LoggerInterfaceEE}
  [A] 'method virtual openassetio::v1::Identifiers openassetio::v1::pluginSystem::HybridPluginSystemManagerImplementationFactory::identifiers()'    {_ZN11openassetio2v112pluginSystem46HybridPluginSystemManagerImplementationFactory11identifiersEv}
    note that this adds a new entry to the vtable of class openassetio::v1::pluginSystem::HybridPluginSystemManagerImplementationFactory
  [A] 'method virtual openassetio::v1::managerApi::ManagerInterfacePtr openassetio::v1::pluginSystem::HybridPluginSystemManagerImplementationFactory::instantiate(const openassetio::v1::Identifier&)'    {_ZN11openassetio2v112pluginSystem46HybridPluginSystemManagerImplementationFactory11instantiateERKSs}
    note that this adds a new entry to the vtable of class openassetio::v1::pluginSystem::HybridPluginSystemManagerImplementationFactory
  [A] 'method openassetio::v1::pluginSystem::HybridPluginSystemManagerImplementationFactoryPtr openassetio::v1::pluginSystem::HybridPluginSystemManagerImplementationFactory::make(openassetio::v1::log::LoggerInterfacePtr)'    {_ZN11openassetio2v112pluginSystem46HybridPluginSystemManagerImplementationFactory4makeESt6vectorISt10shared_ptrINS0_7hostApi37ManagerImplementationFactoryInterfaceEESaIS7_EES4_INS0_3log15LoggerInterfaceEE}

4 Added variable symbols not referenced by debug info:

  [A] _ZTIN11openassetio2v112pluginSystem46HybridPluginSystemManagerImplementationFactoryE
  [A] _ZTSN11openassetio2v112pluginSystem46HybridPluginSystemManagerImplementationFactoryE
  [A] _ZTSSt23_Sp_counted_ptr_inplaceIN11openassetio2v112pluginSystem46HybridPluginSystemManagerImplementationFactoryESaIS3_ELN9__gnu_cxx12_Lock_policyE2EE
  [A] _ZTVN11openassetio2v112pluginSystem46HybridPluginSystemManagerImplementationFactoryE

[foundry-markf]

The "appropriate" manager implementation to route to varies. In most cases, the highest priority implementation that advertises the capability associated with the API call is chosen (i.e. it is routed based on the response of the manager(s) to hasCapability(...)).

The priority order of implementations corresponds to the order of the child factories in the list that was provided to the hybrid factory on construction.

Taken from the PR description above.
I get that 'priority order' is the order of the factories passed to the ctor as in your walk-through earlier.

But 'In most cases', what do you mean? Is there another mechanism?

EDIT: reading further, is it

For info and settings, the results of all manager implementations are merged, with the highest priority manager taking precedence if any dictionary keys conflict.

that as a merging process different from choosing from the order in the ctor, that you meant?

[feltech]

The "appropriate" manager implementation to route to varies. In most cases, the highest priority implementation that advertises the capability associated with the API call is chosen (i.e. it is routed based on the response of the manager(s) to hasCapability(...)).

The priority order of implementations corresponds to the order of the child factories in the list that was provided to the hybrid factory on construction.

Taken from the PR description above. I get that 'priority order' is the order of the factories passed to the ctor as in your walk-through earlier.

But 'In most cases', what do you mean? Is there another mechanism?

EDIT: reading further, is it

For info and settings, the results of all manager implementations are merged, with the highest priority manager taking precedence if any dictionary keys conflict.

that as a merging process different from choosing from the order in the ctor, that you meant?

Yes exactly. Most of the methods have a similar pattern - choose the "first" plugin that satisfies the capability, where "first" corresponds to the order the child factories were passed in the ctor.

But for some methods that doesn't make sense or isn't possible, such as displayName() or settings().

[foundry-markf]

The pybind11 question is open for me, but otherwise, I don't see anything outstanding.

[feltech]

The pybind11 question is open for me, but otherwise, I don't see anything outstanding.

Thanks! Squashed it all down and pushed. Let's see if there's any takers for pybind stuff. At least its only a tiny part of the PR.