Plugin

🟨 Compile source-delivered C++ extensions and reload them inside a running process (see Plugin for more details) More...

Classes
struct	SC::PluginFile
	Holds path to a given plugin source file. More...
struct	SC::PluginIdentity
	Represents the unique signature / identity of a Plugin. More...
struct	SC::PluginDefinition
	Plugin description, category, dependencies, files and directory location. More...
struct	SC::PluginScanner
	Scans a directory for PluginDefinition. More...
struct	SC::PluginCompiler
	Compiles a plugin to a dynamic library. More...
struct	SC::PluginSysroot
	Holds include and library paths for a system toolchain, used to let plugins link to libc and libc++. More...
struct	SC::PluginCompilerEnvironment
	Reads and holds CFLAGS and LDFLAGS environment variables, mainly to pass down sysroot location. More...
struct	SC::PluginDynamicLibrary
	A plugin dynamic library loaded from a SC::PluginRegistry. More...
struct	SC::PluginRegistry
	Holds a registry of plugins, loading and compiling them on the fly. More...
union	SC::PluginErrorContext
	A typed scalar payload for a Plugin error. Its interpretation is selected by PluginErrorContextKind. More...
struct	SC::ResultPlugin
	Plugin result retaining a stable operation detail and one scalar diagnostic context. More...

Enumerations
enum class	SC::PluginError : uint32_t {   PathNotNullTerminated = 1 ,   UnsupportedPathEncoding ,   InvalidDefinition ,   DynamicLibraryOperationUnsupported ,   PathCapacityExceeded ,   DefinitionCapacityExceeded ,   ScannerCapacityExceeded ,   RegistryCapacityExceeded ,   CompilerConfigurationCapacityExceeded ,   SysrootCapacityExceeded ,   ArgumentCapacityExceeded ,   FileOpenFailed ,   FileSizeQueryFailed ,   FileBufferCapacityExceeded ,   FileReadFailed ,   FileReadIncomplete ,   FileRemoveFailed ,   DirectoryOpenFailed ,   DirectoryReadFailed ,   CompilerNotFound ,   SysrootNotFound ,   CompilerEnvironmentReadFailed ,   CompilerExitedWithFailure ,   LinkerExitedWithFailure ,   DynamicLibraryAlreadyLoaded ,   DynamicLibraryLoadFailed ,   DynamicLibraryCloseFailed ,   DynamicLibraryNotLoaded ,   SymbolNameConversionFailed ,   SymbolNameCapacityExceeded ,   SymbolNotFound ,   InitializationEntryPointNotFound ,   CloseEntryPointNotFound ,   PluginNotFound ,   PluginInitializationFailed ,   PluginShutdownFailed ,   DebuggerUnlockFailed ,   ReloadUnsupported }
	Stable portable failures returned by the Plugin library. More...
enum class	SC::PluginErrorDetail : uint16_t {   None = 0 ,   PathAssign ,   PathAppend ,   MetadataName ,   MetadataVersion ,   MetadataDescription ,   MetadataCategory ,   MetadataDependency ,   MetadataBuildOption ,   ScannerDefinitionStorage ,   ScannerCandidatePath ,   ScannerCandidateFile ,   IteratorAssignDirectory ,   IteratorBuildSearchPath ,   IteratorBuildEntryPath ,   CompilerFindConfiguration ,   CompilerBuildArguments ,   CompilerWriteArguments ,   CompilerBuildObjectPath ,   LinkerBuildArguments ,   LinkerWriteArguments ,   LinkerBuildOutputPath ,   SysrootFindVersion ,   SysrootBuildIncludePath ,   SysrootBuildLibraryPath ,   RegistryUnloadList ,   RegistryStoreDefinition ,   RegistryFindPlugin ,   WindowsFileCreate ,   WindowsFileGetSize ,   WindowsFileRead ,   WindowsFileDelete ,   PosixFileOpen ,   PosixFileStat ,   PosixFileRead ,   PosixFileRemove ,   WindowsDirectoryFindFirst ,   WindowsDirectoryFindNext ,   PosixDirectoryOpen ,   PosixDirectoryRead ,   WindowsDynamicLibraryLoad ,   WindowsDynamicLibraryClose ,   WindowsDynamicLibraryGetSymbol ,   PosixDynamicLibraryLoad ,   PosixDynamicLibraryClose ,   PosixDynamicLibraryGetSymbol ,   WindowsSymbolNameConversion ,   PosixSymbolNameAssign ,   WindowsDebuggerUnlock ,   WindowsDebuggerDelete }
	Stable operation or backend stage retained for a Plugin failure. More...
enum class	SC::PluginErrorContextKind : uint16_t {   None = 0 ,   NativeError ,   ExitCode ,   RequiredBytes ,   RequiredElements }
	Kind of the scalar diagnostic context stored in ResultPlugin. More...

Detailed Description

🟨 Compile source-delivered C++ extensions and reload them inside a running process (see Plugin for more details)

#include "Libraries/Async/Async.h"
#include "Libraries/FileSystemWatcher/FileSystemWatcher.h"
 
namespace SC
{
//-----------------------------------------------------------------------------
// IPluginContract.h
//-----------------------------------------------------------------------------
// CLIENT - HOST Contract (Interface)
struct IPluginContract
{
    static constexpr auto InterfaceHash = PluginHash("IPluginContract");
 
    Function<void(void)> onDraw;
};
 
//-----------------------------------------------------------------------------
// PluginClient.cpp
//-----------------------------------------------------------------------------
// CLIENT Plugin (binds to contract functions)
struct PluginClient : public IPluginContract
{
    PluginClient()
    {
        IPluginContract::onDraw = []()
        {
            // Draw stuff...
        };
    }
 
    // Called when plugin is init
    bool init() { return true; }
 
    // Called when plugin is closed
    bool close() { return true; }
};
SC_PLUGIN_DEFINE(PluginClient);
SC_PLUGIN_EXPORT_INTERFACES(PluginClient, IPluginContract);
 
//-----------------------------------------------------------------------------
// PluginHost.cpp
//-----------------------------------------------------------------------------
// Plugin HOST (loads plugin, obtains interface and calls functions)
struct PluginHost
{
    // Fill directories before calling create
    StringPath executablePath;       // Where executable lives
    StringPath libraryRootDirectory; // Where Sane C++ Libraries live
    StringPath someLibraryDirectory; // Where 3rd party-lib headers live
    StringPath pluginsPath;          // Where Plugins live
 
    PluginRegistry registry;
 
    Result create(AsyncEventLoop& loop)
    {
        eventLoop = &loop;
 
        // Setup Compiler
        SC_TRY(PluginCompiler::findBestCompiler(compiler));
        SC_TRY(PluginSysroot::findBestSysroot(compiler.type, sysroot));
 
        // Add includes used by plugins...
        SC_TRY(compiler.includePaths.push_back(libraryRootDirectory));
        SC_TRY(compiler.includePaths.push_back(someLibraryDirectory));
 
        // Setup File System Watcher
        fileSystemWatcherRunner.init(*eventLoop);
        SC_TRY(fileSystemWatcher.init(fileSystemWatcherRunner));
        watcher.notifyCallback.bind<PluginHost, &PluginHost::onFileChanged>(*this);
        SC_TRY(fileSystemWatcher.watch(watcher, pluginsPath.view()));
        return Result(true);
    }
 
    Result close()
    {
        SC_TRY(fileSystemWatcher.close());
        eventLoop = nullptr;
        return Result(true);
    }
 
    Result syncRegistry()
    {
        // Max 16 definitions, but you can use heap allocation if you need an arbitrary limit
        PluginDefinition       definitions[16];
        Span<PluginDefinition> definitionsSpan;
        Buffer                 fileStorage;
        SC_TRY(PluginScanner::scanDirectory(pluginsPath.view(), definitions, fileStorage, definitionsSpan))
        SC_TRY(registry.replaceDefinitions(move(definitionsSpan)));
        return Result(true);
    }
 
    // Call this to load a plugin with a given identifier
    Result load(StringView identifier)
    {
        // Force reload of plugin if already loaded
        SC_TRY(registry.loadPlugin(identifier, compiler, sysroot, executablePath.view(),
                                   PluginRegistry::LoadMode::Reload));
 
        // Obtain contract
        const PluginDynamicLibrary* plugin = registry.findPlugin(identifier);
        SC_TRY(plugin->queryInterface(contract));
        return Result(true);
    }
 
    void draw()
    {
        if (contract)
        {
            contract->onDraw();
        }
    }
 
  private:
    AsyncEventLoop* eventLoop;
    PluginCompiler  compiler;
    PluginSysroot   sysroot;
 
    IPluginContract* contract = nullptr;
 
    FileSystemWatcher fileSystemWatcher;
 
    FileSystemWatcher::FolderWatcher watcher;
    FileSystemWatcherAsync           fileSystemWatcherRunner;
 
    void onFileChanged(const FileSystemWatcher::Notification& notification)
    {
        auto reload = [this](const PluginIdentifier& plugin) { (void)load(plugin.view()); };
        registry.getPluginsToReloadBecauseOf(notification.relativePath, Time::Milliseconds(500), reload);
    }
};
} // namespace SC

Enumeration Type Documentation

PluginError

enum class SC::PluginError : uint32_t

strong

#include <PluginError.h>

Stable portable failures returned by the Plugin library.

PluginErrorContextKind

enum class SC::PluginErrorContextKind : uint16_t

strong

#include <PluginError.h>

Kind of the scalar diagnostic context stored in ResultPlugin.

PluginErrorDetail

enum class SC::PluginErrorDetail : uint16_t

strong

#include <PluginError.h>

Stable operation or backend stage retained for a Plugin failure.