parser_manager.h File Reference

Parser Manager – runtime parser plugin management system. More...

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdio.h>

Go to the source code of this file.

Data Structures
struct	LimeParserPlugin
	The plugin interface struct – the contract between the manager and a parser implementation. More...
struct	LimePluginInfo
	Plugin information returned by enumeration functions. More...
struct	LimePluginVersion
	Semantic version for a plugin. More...
struct	ParserManagerConfig
	Configuration for creating a ParserManager. More...

Macros
#define	LIME_PLUGIN_ABI_VERSION_MAJOR   1
	ABI major version of the plugin interface.
#define	LIME_PLUGIN_ABI_VERSION_MINOR   0
	ABI minor version of the plugin interface.
#define	LIME_PLUGIN_ENTRY_SYMBOL   "lime_plugin_entry"
	Symbol name looked up by the manager after dlopen().
#define	LIME_PLUGIN_EXPORT   __declspec(dllexport)
	Macro for declaring the plugin entry point with proper visibility.
#define	LIME_PLUGIN_HANDLE_INVALID   ((LimePluginHandle)0)
	Sentinel value representing an invalid or unset plugin handle.

Typedefs
typedef const LimeParserPlugin *(*	LimePluginEntryFn) (void)
	Function signature for the dynamic plugin entry point.
typedef uint32_t	LimePluginHandle
	Opaque handle identifying a loaded parser plugin within a manager.
typedef struct ParserManager	ParserManager
	Opaque parser manager handle.

Enumerations
enum	LimePluginCaps {   LIME_CAP_SNAPSHOT = (1u << 0) , LIME_CAP_EXTENSIBLE = (1u << 1) , LIME_CAP_JIT = (1u << 2) , LIME_CAP_INCREMENTAL = (1u << 3) ,   LIME_CAP_SERIALIZABLE = (1u << 4) }
	Bit flags describing what a plugin supports. More...
enum	ParserManagerStatus {   PM_OK = 0 , PM_ERR_INVALID_ARG , PM_ERR_ALLOC , PM_ERR_PLUGIN_NOT_FOUND ,   PM_ERR_DUPLICATE_NAME , PM_ERR_ABI_MISMATCH , PM_ERR_INIT_FAILED , PM_ERR_DLOPEN_FAILED ,   PM_ERR_NO_ENTRY_POINT , PM_ERR_SNAPSHOT_FAILED , PM_ERR_VALIDATION_FAILED , PM_ERR_PLUGIN_IN_USE ,   PM_ERR_NO_ACTIVE_PLUGIN , PM_ERR_CAPABILITY_MISSING }
	Status codes returned by ParserManager operations. More...

Functions
char *	lime_plugin_capabilities_string (uint32_t caps, char *buf, size_t buflen)
	Format a capability bitmask as a comma-separated string of names.
const char *	lime_plugin_capability_name (LimePluginCaps cap)
	Return a human-readable name for a single capability flag.
void	lime_plugin_dump (const LimeParserPlugin *plugin, FILE *out)
	Print a diagnostic summary of a plugin to a file stream.
bool	lime_plugin_has_all_capabilities (const LimeParserPlugin *plugin, uint32_t required_caps)
	Check if a plugin has all of the specified capabilities.
bool	lime_plugin_has_capability (const LimeParserPlugin *plugin, LimePluginCaps cap)
	Check if a plugin has a specific capability.
ParserManagerStatus	lime_plugin_validate (const LimeParserPlugin *plugin)
	Validate that a plugin struct has all required callbacks and a compatible ABI version.
int	lime_plugin_version_compare (LimePluginVersion a, LimePluginVersion b)
	Compare two plugin versions.
bool	lime_plugin_version_satisfies (LimePluginVersion actual, LimePluginVersion required)
	Check if a plugin version satisfies a minimum requirement.
char *	lime_plugin_version_string (LimePluginVersion v, char *buf, size_t buflen)
	Format a version as a string.
ParserManager *	parser_manager_create (const ParserManagerConfig *config)
	Create a new parser manager.
void	parser_manager_destroy (ParserManager *mgr)
	Destroy a parser manager and release all resources.
LimePluginHandle	parser_manager_find_by_name (const ParserManager *mgr, const char *name)
	Look up a plugin by name.
LimePluginHandle	parser_manager_get_active (const ParserManager *mgr)
	Get the handle of the currently active plugin.
ParserManagerStatus	parser_manager_get_plugin_info (const ParserManager *mgr, LimePluginHandle handle, LimePluginInfo *info)
	Get information about a specific plugin.
ParserSnapshot *	parser_manager_get_snapshot (ParserManager *mgr)
	Get the current active snapshot.
ParserManagerStatus	parser_manager_hot_swap (ParserManager *mgr, LimePluginHandle new_handle, const char *grammar_file)
	Atomically replace the active plugin and snapshot.
ParserManagerStatus	parser_manager_list_plugins (const ParserManager *mgr, LimePluginInfo *infos, uint32_t max_count, uint32_t *actual_count)
	Enumerate all loaded plugins.
ParserManagerStatus	parser_manager_load (ParserManager *mgr, const char *path, void *user_data, LimePluginHandle *handle_out)
	Load a parser plugin from a shared library.
uint32_t	parser_manager_plugin_count (const ParserManager *mgr)
	Get the number of loaded plugins.
ParserManagerStatus	parser_manager_register (ParserManager *mgr, const LimeParserPlugin *plugin, void *user_data, LimePluginHandle *handle_out)
	Register a statically linked parser plugin.
ParserManagerStatus	parser_manager_set_active (ParserManager *mgr, LimePluginHandle handle, const char *grammar_file)
	Set the active parser plugin.
ParserManagerStatus	parser_manager_set_snapshot (ParserManager *mgr, ParserSnapshot *snap)
	Provide or replace the active snapshot directly.
const char *	parser_manager_status_string (ParserManagerStatus status)
	Return a human-readable string for a status code.
ParserManagerStatus	parser_manager_unload (ParserManager *mgr, LimePluginHandle handle)
	Unload a previously loaded or registered plugin.

Detailed Description

Parser Manager – runtime parser plugin management system.

Provides a unified interface for dynamically loading, registering, and switching between parser implementations at runtime. Parsers are packaged as plugins (shared libraries or statically linked modules) that conform to the LimeParserPlugin interface.

The ParserManager maintains a thread-safe registry of loaded parsers, supports hot-swapping of parser versions, and provides session-level isolation so that in-flight parse operations are never disrupted by plugin changes.

Architecture

+-------------------+
| ParserManager     |  (singleton or per-application)
|  - plugin registry|
|  - active parser  |
+--------+----------+
         |
+--------v----------+     +------------------+
| LimeParserPlugin  |<--->| ParserSnapshot   |
|  (loaded .so or   |     | (action tables,  |
|   static module)  |     |  symbols, rules) |
+-------------------+     +------------------+

Thread Safety

The registry is protected by a pthread_rwlock_t. Multiple threads can look up and use plugins concurrently; mutations (register, unregister, set_active) acquire exclusive access.

Parse sessions (via parse_begin/parse_token/parse_end from parser.h) pin a snapshot, so they are not affected by concurrent plugin changes.

Plugin load/unload callbacks are called under the write lock. Implementations must not call back into the ParserManager from these callbacks (deadlock).

Usage Example

ParserManager *mgr = parser_manager_create(NULL);
 
// Load a plugin from a shared library
LimePluginHandle h;
parser_manager_load(mgr, "/usr/lib/lime/sql_parser.so", NULL, &h);
 
// Or register a statically linked plugin
parser_manager_register(mgr, &my_static_plugin, NULL, &h);
 
// Set it as the active parser
parser_manager_set_active(mgr, h, "grammar.y");
 
// Get a snapshot for parsing
ParserSnapshot *snap = parser_manager_get_snapshot(mgr);
ParseContext *ctx = parse_begin(snap);
// ... parse tokens ...
parse_end(ctx);
lemon_snapshot_release(snap);
 
parser_manager_destroy(mgr);

See also

parser.h for the core parse session API.

snapshot.h for ParserSnapshot internals.

Definition in file parser_manager.h.