Objectives for the Runtime Libraries

• Separate between public and private APIs:

  • Public: Functionality for host applications to use & interact with Spicy’s parsers and their results (namespaces: {hilti,spicy}::rt)
  • Private: Functionality needed only by the HILTI code generator; by Spicy’s auto-generated parsing code; or purely internally inside the runtime system itself (namespaces: {hilti,spicy}::rt::detail.

• Follow standard semantics and best practices for C++ APIs, such as:

  • Compatibility with C++ standard library functionality wherever feasible (e.g., use standard types where we can; provide standard iterators for custom container classes).
  • Consistent API semantics, conventions, and documentation.
  • Consistent error/exception reporting & handling.

• Robustness:

  • Comprehensive validation of all inputs; do not trust anything that’s provided externally.
  • No undefined behavior (e.g., iterators must be safe against the container resizing or going away; integers must not overflow).
  • Unit tests covering all externally visible functionality (including everything used by the code generator).
  • Leverage static & dynamic analysis tools to spot trouble.

• Thread safety:

  • All functionality needs to be thread-safe.
  • Avoid globals, and think carefully about cases where we need them.

• Optimize runtime performance for Spicy’s use case:

  • Tune implementation for common cases, such as through inlining of hot-path functionality.
  • Reduce state to a minimum, avoid memory allocations where possible.

• Minimize compile times for client code (in particular for generated parsing code)

• Minimize complexity of the implementation; simpler is better.

• Minimize external dependencies; use only where they clearly bring value in terms of other objectives.