jit-overview
Orientation to facet-format JIT deserialization (tiering, fallbacks, key types/entry points) and where to look when changing or debugging JIT code
Security Assessment
About jit-overview
The `jit-overview` skill provides an introduction to the facet-format JIT deserialization pipeline used in `facet-format`. It explains the design and implementation details behind the JIT mechanisms, focusing on optimizing deserialization performance through tiered approaches. This skill aims to assist developers in understanding the JIT code and offer insights into debugging and performance tuning for deserialization tasks, particularly in scenarios involving complex data formats like JSON, YAML, and TOML. The skill emphasizes the relationship between format parsers and the deserialization pipeline, outlining the role of JIT in accelerating the process.
The main capabilities of the `jit-overview` skill include an explanation of the two-tier architecture (shape JIT and format JIT), detailing the distinction between Tier 1 (shape JIT) and Tier 2 (format JIT). The skill also covers fallbacks in the system design, pointing out that tiered approaches are used based on the input shape and format compatibility. Furthermore, users are guided on how to enable and use JIT in format crates like `facet-json`, offering practical debugging advice for issues such as crashes and performance bottlenecks. Developers dealing with performance-related deserialization tasks or those needing to debug JIT code crashes will find this skill essential.
The target audience includes developers working on deserialization pipelines, especially those using `facet-format` and its associated format crates. This skill is particularly valuable for those involved in performance optimization, crash debugging, and anyone working on custom JIT code paths. Additionally, it's beneficial for developers who need to understand how the JIT deserialization system integrates with different data formats and how to debug or enhance its performance effectively.
FAQ
When should I read this skill?
You should read this skill when working with `facet-format/src/jit/`, enabling the `jit` feature, investigating performance changes in deserialization (especially tier2/JIT benchmarks), or debugging a JIT crash.
How do I enable JIT in a format crate like `facet-json`?
You can enable JIT in `facet-json` by adding the feature `jit = ["facet-format/jit"]` to the `Cargo.toml` file. You can also check the example at `facet-json/examples/profile_jit_vec` for further reference.
What should I do if a JIT crash occurs?
If a JIT crash occurs, try reproducing the issue with a minimal type and input. Run the failing test under `valgrind` or `Miri` to check for memory or undefined behavior issues. Additionally, isolate the smallest shape triggering the crash and look for tier selection diagnostics in the JIT code.
Are there any limitations with Tier 2 in JIT deserialization?
Yes, Tier 2 intentionally supports a performance-focused subset of shapes and may return 'unsupported' for shapes or inputs it cannot handle. This fallback mechanism ensures it doesn't interfere with the deserialization process when unsupported.
Install jit-overview
Quick Setup:
- Copy the skill folder to
.claude/skills/ - Claude will automatically detect and use the skill
Repository
facet-rs/facet