{"id":34538160,"url":"https://github.com/sebyx07/json-asm","last_synced_at":"2026-05-03T18:35:34.416Z","repository":{"id":329453051,"uuid":"1119674969","full_name":"sebyx07/json-asm","owner":"sebyx07","description":"⚡ The fastest JSON parser/serializer - hand-optimized x86-64 \u0026 ARM64 assembly with C API. AVX-512/AVX2/NEON SIMD, 24-byte nodes, zero-copy parsing","archived":false,"fork":false,"pushed_at":"2025-12-19T17:06:09.000Z","size":71,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-28T20:29:17.754Z","etag":null,"topics":["arm64","assembly","avx2","avx512","c","high-performance","json","neon","parser","performance","serializer","simd","x86-64"],"latest_commit_sha":null,"homepage":"https://github.com/sebyx07/json-asm","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sebyx07.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-19T16:51:58.000Z","updated_at":"2025-12-19T17:06:13.000Z","dependencies_parsed_at":"2025-12-22T07:03:14.534Z","dependency_job_id":null,"html_url":"https://github.com/sebyx07/json-asm","commit_stats":null,"previous_names":["sebyx07/json-asm"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sebyx07/json-asm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebyx07%2Fjson-asm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebyx07%2Fjson-asm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebyx07%2Fjson-asm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebyx07%2Fjson-asm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sebyx07","download_url":"https://codeload.github.com/sebyx07/json-asm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebyx07%2Fjson-asm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32580096,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T06:36:36.687Z","status":"ssl_error","status_checked_at":"2026-05-03T06:36:09.306Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arm64","assembly","avx2","avx512","c","high-performance","json","neon","parser","performance","serializer","simd","x86-64"],"created_at":"2025-12-24T06:10:45.018Z","updated_at":"2026-05-03T18:35:34.411Z","avatar_url":"https://github.com/sebyx07.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# json-asm\n\nThe fastest JSON parser and serializer, written in hand-optimized assembly (x86-64 \u0026 ARM64) with a clean C API.\n\n## Overview\n\n**json-asm** is a high-performance JSON library that pushes the boundaries of parsing and serialization speed through hand-optimized assembly. It leverages every available SIMD instruction set and CPU feature for maximum throughput.\n\n### Key Features\n\n- **Multi-architecture assembly** - Hand-optimized for x86-64 (AVX-512/AVX2/SSE4.2) and ARM64 (NEON/SVE/SVE2)\n- **Maximum SIMD utilization** - 512-bit vector operations where available\n- **Branch prediction optimization** - Computed gotos, branchless algorithms, cmov usage\n- **Cache hierarchy optimization** - Prefetching, cache-line alignment, TLB-friendly allocation\n- **Zero-copy parsing** - Minimal memory allocations during parse operations\n- **Lock-free data structures** - Wait-free progress on multi-threaded access\n- **Simple C API** - Easy to integrate, no C++ runtime dependencies\n\n### Supported Architectures\n\n| Architecture | SIMD Support                        | Status |\n|--------------|-------------------------------------|--------|\n| x86-64       | AVX-512, AVX2, SSE4.2, BMI2, POPCNT | Full   |\n| ARM64        | SVE2, SVE, NEON                     | Full   |\n\n## Performance\n\nPreliminary benchmark results on available hardware:\n\n### Development System (AMD EPYC 7282 @ AVX2)\n\nTested with 399-byte JSON document (44 values, nested objects/arrays):\n\n| Operation  | Throughput | Time per operation | Memory per value |\n|------------|------------|-------------------|------------------|\n| Parse      | ~290 MB/s  | 1.38 μs           | 24 bytes         |\n| Stringify  | ~275 MB/s  | 1.45 μs           | 24 bytes         |\n\n**Test Environment:**\n- CPU: AMD EPYC 7282 16-Core Processor\n- SIMD: AVX2 (256-bit vectors)\n- Compiler: GCC with -O3 -march=native\n- Test data: Small JSON with mixed types\n\n**Note:** These are preliminary results from development hardware. Performance will vary significantly based on:\n- CPU architecture and generation\n- Available SIMD instructions (SSE4.2 vs AVX2 vs AVX-512)\n- JSON document size and structure\n- Memory bandwidth and cache characteristics\n\nThe library automatically selects the best SIMD implementation for your CPU at runtime.\n\n*Comprehensive benchmarks comparing against other JSON libraries coming soon.*\n\n## Quick Start\n\n```c\n#include \u003cjson_asm.h\u003e\n\nint main(void) {\n    const char *json = \"{\\\"name\\\": \\\"json-asm\\\", \\\"fast\\\": true}\";\n\n    // Parse JSON\n    json_doc *doc = json_parse(json, strlen(json));\n    if (!doc) {\n        fprintf(stderr, \"Parse error\\n\");\n        return 1;\n    }\n\n    // Access values\n    json_val *root = json_doc_root(doc);\n    json_val *name = json_obj_get(root, \"name\");\n    printf(\"Name: %s\\n\", json_get_str(name));\n\n    // Cleanup\n    json_doc_free(doc);\n    return 0;\n}\n```\n\n## Building\n\n```bash\n# Requirements:\n#   x86-64: NASM 2.15+, GCC 10+/Clang 12+\n#   ARM64:  GCC 10+/Clang 12+ (uses inline assembly)\n\nmake\nmake install  # installs to /usr/local by default\n\n# Run tests\nmake test\n\n# Run benchmarks\nmake bench\n```\n\nSee [docs/building.md](docs/building.md) for detailed build instructions.\n\n## Documentation\n\n- [API Reference](docs/api.md) - Complete C API documentation\n- [Architecture](docs/architecture.md) - Internal design, SIMD optimizations, CPU features\n- [Benchmarks](docs/benchmarks.md) - Performance methodology and comparisons\n- [Building](docs/building.md) - Build instructions for x86-64 and ARM64\n- [Examples](docs/examples.md) - Usage examples and patterns\n\n## Why Assembly?\n\nModern compilers are excellent, but JSON parsing has predictable patterns that benefit from manual optimization:\n\n### x86-64 Optimizations\n- **AVX-512 masked operations** - Process 64 bytes with predicated loads/stores\n- **AVX2 string scanning** - Find structural chars across 32 bytes simultaneously\n- **BMI2 PEXT/PDEP** - Branchless bit manipulation for escape handling\n- **POPCNT/LZCNT/TZCNT** - O(1) bit counting for mask processing\n\n### ARM64 Optimizations\n- **SVE/SVE2 variable-length vectors** - Scalable from 128 to 2048 bits\n- **NEON 128-bit operations** - Parallel character classification\n- **AdvSIMD dot product** - Fast numeric accumulation\n- **Load/store pair instructions** - Efficient memory access patterns\n\n### Micro-architectural Optimizations\n- **Branchless number parsing** - Eliminates misprediction penalties (~15 cycles)\n- **Computed goto dispatch** - O(1) state machine transitions\n- **Explicit prefetching** - Hide memory latency for sequential access\n- **Register pressure optimization** - Keep hot data in registers\n- **Instruction-level parallelism** - Maximize superscalar execution\n\nSee [docs/architecture.md](docs/architecture.md) for technical details.\n\n## Design Approach\n\njson-asm uses hand-optimized assembly to achieve high performance:\n\n| Aspect              | json-asm                         |\n|---------------------|----------------------------------|\n| Implementation      | Native assembly (x86-64 + ARM64) |\n| SIMD x86-64         | AVX-512/AVX2/SSE4.2 hand-written |\n| SIMD ARM64          | NEON/SVE/SVE2 hand-written       |\n| String scanning     | Custom SIMD routines             |\n| Number parsing      | Branchless assembly algorithms   |\n| Memory layout       | Compact 24 bytes/value           |\n\nBy controlling every instruction in hot paths, assembly allows for:\n- Explicit SIMD instruction selection\n- Branchless algorithms to avoid misprediction penalties\n- Cache-line alignment and prefetching control\n- Register allocation optimization\n\n## CPU Feature Detection\n\njson-asm automatically detects and uses the best available instructions:\n\n```\nx86-64 dispatch (best to worst):\n  AVX-512 + BMI2 → AVX2 + BMI2 → AVX2 → SSE4.2 → Scalar\n\nARM64 dispatch (best to worst):\n  SVE2 → SVE → NEON → Scalar\n```\n\nRuntime detection ensures optimal performance on any conforming CPU.\n\n## API Overview\n\n```c\n// Parsing\njson_doc *json_parse(const char *json, size_t len);\njson_doc *json_parse_file(const char *path);\n\n// Document access\njson_val *json_doc_root(json_doc *doc);\nvoid json_doc_free(json_doc *doc);\n\n// Value inspection\njson_type json_get_type(json_val *val);\nconst char *json_get_str(json_val *val);\ndouble json_get_num(json_val *val);\nint64_t json_get_int(json_val *val);\nbool json_get_bool(json_val *val);\n\n// Object/Array access\njson_val *json_obj_get(json_val *obj, const char *key);\njson_val *json_arr_get(json_val *arr, size_t index);\n\n// Serialization\nchar *json_stringify(json_val *val);\n```\n\nSee [docs/api.md](docs/api.md) for the complete API reference.\n\n## Requirements\n\n### x86-64\n- **CPU**: x86-64-v2 minimum (SSE4.2), x86-64-v4 recommended (AVX-512)\n- **OS**: Linux, macOS, Windows, FreeBSD\n- **Build**: NASM 2.15+, GCC 10+ or Clang 12+\n\n### ARM64\n- **CPU**: ARMv8-A minimum, ARMv9-A recommended (SVE2)\n- **OS**: Linux, macOS (Apple Silicon), Android\n- **Build**: GCC 10+ or Clang 12+\n\n## License\n\nMIT License. See [LICENSE](LICENSE) for details.\n\n## Contributing\n\nContributions welcome! Performance improvements should include benchmark results. Please read the architecture docs before working on assembly code.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsebyx07%2Fjson-asm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsebyx07%2Fjson-asm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsebyx07%2Fjson-asm/lists"}