Ship::Scripting::LibraryLoader Class Reference

Loads and manages a single shared library (DLL / .so / .dylib) at runtime. More...

#include <LibraryLoader.h>

Public Member Functions
	LibraryLoader ()
	Constructs an unloaded LibraryLoader with no associated library.
std::string	GenerateTempFile ()
	Creates a temporary file path suitable for holding a library copy.
void	WriteToTempFile (const std::vector< uint8_t > &data)
	Writes raw library bytes to the temp file created by GenerateTempFile().
void	Init (const std::string &path)
	Loads the shared library already written at path via the platform dynamic linker.
void	InitInMemory (void *tccState)
	Relocates an in-memory TCC compilation unit and takes ownership of it.
void *	GetFunction (const std::string &name)
	Resolves an exported symbol from the loaded library.
void	Unload ()
	Unloads the library from memory and cleans up platform resources.

Detailed Description

Loads and manages a single shared library (DLL / .so / .dylib) at runtime.

LibraryLoader loads a compiled library from a caller-supplied path via the platform's dynamic-linker API, and resolves exported symbols by name.

Typical usage:

1. Call GenerateTempFile() to allocate a writable temp path. 2a. Call WriteToTempFile() to populate it from raw bytes, OR 2b. Have an external tool (e.g. TCC) write the library to the path returned by GenerateTempFile() directly.
2. Call Init() with that path to load the library into the process.

This is used by the scripting subsystem to hot-reload compiled script modules.

Constructor & Destructor Documentation

LibraryLoader()

Ship::Scripting::LibraryLoader::LibraryLoader ( )

inline

Constructs an unloaded LibraryLoader with no associated library.

Member Function Documentation

GenerateTempFile()

std::string Ship::Scripting::LibraryLoader::GenerateTempFile

(

)

Creates a temporary file path suitable for holding a library copy.

Returns

Absolute path to the generated temporary file.

GetFunction()

void * Ship::Scripting::LibraryLoader::GetFunction

(

const std::string &

name

)

Resolves an exported symbol from the loaded library.

Parameters

name	The symbol name to look up.

Returns

Pointer to the symbol, or nullptr if not found or no library is loaded.

Init()

void Ship::Scripting::LibraryLoader::Init

(

const std::string &

path

)

Loads the shared library already written at path via the platform dynamic linker.

Parameters

path	Filesystem path to the shared library to load. The file must already exist on disk (written by WriteToTempFile() or an external tool such as TCC); Init() does not copy or create it.

Note

On Linux and macOS the file at path is unlinked from the filesystem immediately after a successful dlopen() call so that the temporary file is removed without waiting for Unload(). The library remains mapped in memory until Unload() is called.

On Windows the file is kept on disk and is deleted by Unload().

Exceptions

std::runtime_error

if the library cannot be loaded.

InitInMemory()

void Ship::Scripting::LibraryLoader::InitInMemory

(

void *

tccState

)

Relocates an in-memory TCC compilation unit and takes ownership of it.

Used for scripts compiled from source at runtime: instead of writing a shared library to disk and handing it to the platform dynamic linker (the "drop and load" pattern that antivirus heuristics flag), the code is JIT-relocated in-process directly from the TCCState via tcc_relocate(). Nothing is written to disk and neither dlopen() nor LoadLibrary() is called.

Parameters

tccState

An opaque TCCState* that has already had its sources compiled (tcc_compile_string). This LibraryLoader takes ownership: the state is kept alive because it owns the executable memory, and freed (tcc_delete) by Unload().

Exceptions

std::runtime_error

if relocation fails.

Note

Only available when built with the TCC compiler (not DISABLE_TCC_COMPILER).

Unload()

void Ship::Scripting::LibraryLoader::Unload

(

)

Unloads the library from memory and cleans up platform resources.

Note

On Windows, FreeLibrary() is called and the associated temporary file is deleted from disk.

On Linux and macOS, dlclose() is not called (the handle is simply cleared); the temporary file was already unlinked by Init(), so no filesystem cleanup is needed here.

WriteToTempFile()

void Ship::Scripting::LibraryLoader::WriteToTempFile

(

const std::vector< uint8_t > &

data

)

Writes raw library bytes to the temp file created by GenerateTempFile().

Parameters

data	Raw bytes of the shared library to write to disk.

Exceptions

std::runtime_error

if the temp file cannot be opened for writing.

Note

GenerateTempFile() must be called before this method.

---

The documentation for this class was generated from the following file:

• include/ship/scripting/LibraryLoader.h