Skip to content

Commit

Permalink
fixup! [Docs] Add hybrid plugin system notebook
Browse files Browse the repository at this point in the history 
Focus initially on the primary use-case in the "How it works" section.

Signed-off-by: David Feltell <[email protected]>
  • Loading branch information
@feltech
feltech committed Sep 2, 2024
1 parent 41baa5d commit 5171e5b
Showing 1 changed file with 33 additions and 29 deletions.
62 changes: 33 additions & 29 deletions examples/hybrid_plugin_system.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,15 +10,21 @@
"\n",
"The primary use-case for this feature is to allow performance critical functionality to be written in performant C++, whilst less performance critical functionality can be written in more flexible Python.\n",
"\n",
"The hybrid plugin system also provides a more convenient abstraction for working with multiple plugin systems in general.\n",
"The hybrid plugin system also provides a more convenient abstraction for working with multiple plugin systems in general. It should be the default choice by most host applications (i.e. where a Python environment is available).\n",
"\n",
"## How it works\n",
"\n",
"The hybrid plugin system allows a manager to split its implementation between multiple languages. Under the hood, each language is loaded using its own plugin system (currently, C++ and Python are supported). It combines plugins that share the same identifier so they can be used by a host as if they were a single implementation. Calls are routed to one of the underlying implementations based on capabilities and the language priority set when the factory is made.\n",
"\n",
"This allows high call count methods such as `resolve` to be implemented in C++ to ensure maximum performance, whilst less frequently used methods such as `register` remain in more flexible Python.\n",
"\n",
"The following subsection dives into some more detail of how this works.\n",
"\n",
"### Details\n",
"\n",
"OpenAssetIO manager plugins must advertise a unique identifier. An OpenAssetIO plugin system (e.g. C++ or Python) maps unique identifiers to a plugin instance. A consequence of this is if multiple plugins advertise the same unique identifier, only one of those plugins can be chosen _by that plugin system_. However, if multiple plugin systems are in use,\n",
"then each plugin system has their own mapping of unique identifier to plugin instance. This means there _can_ be multiple plugins with the same identifier, as long as they are discovered by different plugin systems.\n",
"\n",
"As a motivating example, a manager plugin developed in Python, loaded by the Python plugin system, could advertise the same identifier as a manager plugin developed in C++, loaded by the C++ plugin system.\n",
"\n",
"This is the essence of how the hybrid plugin system discovers plugins. If two (or more) plugins from two (or more) different plugin systems advertise the same unique identifier, then we assume they are related and can be composed.\n",
"\n",
"The hybrid plugin system therefore wraps a list of child plugin systems, such that they present as a single plugin system to the host.\n",
Expand All @@ -33,9 +39,7 @@
"\n",
"All the OpenAssetIO _required_ capabilities (i.e. `\"entityReferenceIdentification\"`, `\"managementPolicyQueries\"`, `\"entityTraitIntrospection\"`) must be satisfied by at least one of the composed plugins.\n",
"\n",
"If only one child factory locates a plugin with the desired identifier, then that plugin is used directly (i.e. the plugin is not wrapped). In this way, host applications making use of the hybrid plugin system don't lose out on any functionality or performance. \n",
"\n",
"This leads to an important point: _the hybrid plugin system should be used by default by most hosts_, even if they don't make use of all of its functionality."
"If only one child factory locates a plugin with the desired identifier, then that plugin is used directly (i.e. the plugin is not wrapped). In this way, host applications making use of the hybrid plugin system don't lose out on any functionality or performance. "
],
"id": "6ebc020b4c31f1b8"
},
Expand Down Expand Up @@ -71,8 +75,8 @@
{
"metadata": {
"ExecuteTime": {
"end_time": "2024-09-02T12:12:53.612688Z",
"start_time": "2024-09-02T12:12:53.610119Z"
"end_time": "2024-09-02T12:26:34.161690Z",
"start_time": "2024-09-02T12:26:34.155916Z"
}
},
"cell_type": "code",
Expand All @@ -85,7 +89,7 @@
],
"id": "e3a94c5be66ad34e",
"outputs": [],
"execution_count": 8
"execution_count": 1
},
{
"metadata": {},
Expand All @@ -100,8 +104,8 @@
{
"metadata": {
"ExecuteTime": {
"end_time": "2024-09-02T12:12:53.657856Z",
"start_time": "2024-09-02T12:12:53.655328Z"
"end_time": "2024-09-02T12:26:34.202882Z",
"start_time": "2024-09-02T12:26:34.200517Z"
}
},
"cell_type": "code",
Expand All @@ -111,7 +115,7 @@
],
"id": "6c95ee177f2a9028",
"outputs": [],
"execution_count": 9
"execution_count": 2
},
{
"metadata": {},
Expand All @@ -128,8 +132,8 @@
{
"metadata": {
"ExecuteTime": {
"end_time": "2024-09-02T12:12:53.721990Z",
"start_time": "2024-09-02T12:12:53.717801Z"
"end_time": "2024-09-02T12:26:34.413131Z",
"start_time": "2024-09-02T12:26:34.374740Z"
}
},
"cell_type": "code",
Expand Down Expand Up @@ -168,7 +172,7 @@
],
"id": "db2739c3f0a96d70",
"outputs": [],
"execution_count": 10
"execution_count": 3
},
{
"metadata": {},
Expand All @@ -185,8 +189,8 @@
{
"metadata": {
"ExecuteTime": {
"end_time": "2024-09-02T12:12:53.779852Z",
"start_time": "2024-09-02T12:12:53.767734Z"
"end_time": "2024-09-02T12:26:34.449434Z",
"start_time": "2024-09-02T12:26:34.427167Z"
}
},
"cell_type": "code",
Expand Down Expand Up @@ -237,7 +241,7 @@
"output_type": "display_data"
}
],
"execution_count": 11
"execution_count": 4
},
{
"metadata": {},
Expand All @@ -258,8 +262,8 @@
{
"metadata": {
"ExecuteTime": {
"end_time": "2024-09-02T12:12:53.823385Z",
"start_time": "2024-09-02T12:12:53.819311Z"
"end_time": "2024-09-02T12:26:34.481292Z",
"start_time": "2024-09-02T12:26:34.477619Z"
}
},
"cell_type": "code",
Expand All @@ -278,7 +282,7 @@
],
"id": "87c3d7e701b095d9",
"outputs": [],
"execution_count": 12
"execution_count": 5
},
{
"metadata": {},
Expand All @@ -294,8 +298,8 @@
{
"metadata": {
"ExecuteTime": {
"end_time": "2024-09-02T12:12:53.871757Z",
"start_time": "2024-09-02T12:12:53.868064Z"
"end_time": "2024-09-02T12:26:34.532696Z",
"start_time": "2024-09-02T12:26:34.528549Z"
}
},
"cell_type": "code",
Expand All @@ -314,13 +318,13 @@
"outputs": [
{
"data": {
"text/markdown": "> **Result:**\n> `{'openassetio-mediacreation:twoDimensional.Image', 'openassetio-mediacreation:usage.Entity', 'openassetio-mediacreation:identity.DisplayName'}`"
"text/markdown": "> **Result:**\n> `{'openassetio-mediacreation:identity.DisplayName', 'openassetio-mediacreation:usage.Entity', 'openassetio-mediacreation:twoDimensional.Image'}`"
},
"metadata": {},
"output_type": "display_data"
}
],
"execution_count": 13
"execution_count": 6
},
{
"metadata": {},
Expand All @@ -343,8 +347,8 @@
{
"metadata": {
"ExecuteTime": {
"end_time": "2024-09-02T12:12:53.933275Z",
"start_time": "2024-09-02T12:12:53.918641Z"
"end_time": "2024-09-02T12:26:34.598874Z",
"start_time": "2024-09-02T12:26:34.584335Z"
}
},
"cell_type": "code",
Expand All @@ -366,13 +370,13 @@
"outputs": [
{
"data": {
"text/markdown": "> **Result:**\n> `{'openassetio-mediacreation:usage.Entity', 'openassetio-mediacreation:timeDomain.FrameRanged', 'openassetio-mediacreation:twoDimensional.Image', 'openassetio-mediacreation:lifecycle.Version', 'openassetio-mediacreation:content.LocatableContent', 'openassetio-mediacreation:identity.DisplayName'}`"
"text/markdown": "> **Result:**\n> `{'openassetio-mediacreation:timeDomain.FrameRanged', 'openassetio-mediacreation:lifecycle.Version', 'openassetio-mediacreation:content.LocatableContent', 'openassetio-mediacreation:twoDimensional.Image', 'openassetio-mediacreation:identity.DisplayName', 'openassetio-mediacreation:usage.Entity'}`"
},
"metadata": {},
"output_type": "display_data"
}
],
"execution_count": 14
"execution_count": 7
},
{
"metadata": {},
Expand Down

0 comments on commit 5171e5b

Please sign in to comment.