parser_fork.h File Reference

Parser State Cloning for Fork-Resolve Disambiguation. More...

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

Go to the source code of this file.

Data Structures
struct	ClonedParserState
	Deep copy of a grammar-specific parser state. More...
struct	ParseFork
	A forked parser instance. More...
struct	ParseForkSet
	A set of active forks being evaluated in parallel. More...

Macros
#define	PARSER_FORK_LAYOUT_PARAMS(ParserType, StackEntryType)
	Produce the layout parameters expected by clone_parser_state() and fork_parser().

Enumerations
enum	ParseForkStatus {   FORK_PENDING = 0 , FORK_RUNNING , FORK_COMPLETED , FORK_FAILED ,   FORK_ABANDONED }
	Status of a forked parse attempt. More...

Functions
bool	clone_parser_state (const void *parser, size_t parser_size, size_t stack_entry_size, size_t inline_stack_offset, uint32_t inline_stack_count, size_t stack_field_offset, size_t tos_field_offset, size_t stack_end_offset, ClonedParserState *out)
	Clone the parser state from an opaque parser handle.
void	cloned_parser_state_destroy (ClonedParserState *cloned)
	Free a cloned parser state.
ParseFork *	fork_parser (const void *parser, size_t parser_size, size_t stack_entry_size, size_t inline_stack_offset, uint32_t inline_stack_count, size_t stack_field_offset, size_t tos_field_offset, size_t stack_end_offset, struct ParserSnapshot *snapshot, int priority)
	Create a new fork from a base parser state.
void	free_parse_fork (ParseFork *fork)
	Destroy a fork and release all resources.
void	parse_fork_abandon (ParseFork *fork)
	Mark a fork as abandoned (pruned).
void	parse_fork_complete (ParseFork *fork, void *result, void(*free_fn)(void *))
	Mark a fork as completed with the given semantic result.
void	parse_fork_fail (ParseFork *fork)
	Mark a fork as failed.
void *	parse_fork_get_parser (ParseFork *fork)
	Get a mutable pointer to the cloned yyParser inside a fork.
struct ParserSnapshot *	parse_fork_get_snapshot (const ParseFork *fork)
	Get the snapshot associated with a fork.
uint32_t	parse_fork_set_active_count (const ParseForkSet *set)
	Return the number of forks still active.
bool	parse_fork_set_add (ParseForkSet *set, ParseFork *fork)
	Add a fork to the set.
ParseFork *	parse_fork_set_best (const ParseForkSet *set)
	Find the best completed fork.
ParseForkSet *	parse_fork_set_create (uint32_t max_forks)
	Create a fork set with the given maximum fork count.
void	parse_fork_set_destroy (ParseForkSet *set)
	Destroy a fork set and all forks it contains.
uint32_t	parse_fork_set_prune (ParseForkSet *set)
	Remove and destroy all failed or abandoned forks.
uint64_t	parser_fork_next_id (void)
	Return a globally unique fork ID.

Detailed Description

Parser State Cloning for Fork-Resolve Disambiguation.

Provides deep-copy mechanisms for parser state, enabling the fork-resolve disambiguation strategy. When the parser encounters an ambiguity (e.g., multiple grammars could handle the current input), the parser state is forked: each fork receives an independent copy of the parser stack and continues parsing with a different grammar. After all forks complete (or fail), the results are compared and the best parse is selected.

The yyParser struct (defined in limpar.c) contains:

• yytos: pointer to top of stack
• yyerrcnt: error recovery counter
• yystack: the parser stack (may be heap-allocated if grown)
• yystk0: initial inline stack storage
• yystackEnd: pointer to last valid stack slot
• extra_argument / extra_context: user-supplied data

Cloning handles:

1. Deep copy of the stack entries (state + semantic values)
2. Correct pointer fixup (yytos, yystackEnd relative to new stack)
3. Shared immutable tables are reference-counted via snapshots
4. The inline yystk0[] buffer vs heap-allocated yystack distinction

Thread Safety

ParseFork structs are not thread-safe. Each fork should be used by a single thread (or externally synchronized). The underlying ParserSnapshot is thread-safe (refcounted).

See also

disambiguation.h for the fork-resolve strategy.

snapshot.h for ParserSnapshot reference counting.

Definition in file parser_fork.h.