Scan json_view strings with SIMD and index large objects by nlohmann · Pull Request #5628 · nlohmann/json

nlohmann · 2026-09-29T14:20:12Z

Scans string bytes with NEON/SSE2, validates non-ASCII text with simdjson's vector UTF-8 check, and adds a hash index for large objects to the view's parser; part of the zero-copy view stack for #5295, on top of #5624.

Summary

SIMD scanning

Long runs of string bytes are scanned 16 bytes at a time with NEON (AArch64, GCC and Clang) and SSE2 (x86-64). Both belong to the baseline instruction sets. SSE2 and <cpuid.h> are only used on x86 targets, so other targets that define __SSE2__ (such as Emscripten) use the portable code.
Keys and values: keys keep 16 table checks before the vector loop, because their lengths repeat from record to record. String values get 8, because their lengths vary more.
Strings vector-first on x86-64: with SSE2, string runs are checked 16 bytes at a time from their first byte. One compare finds the end of most keys and short values, which is faster than a branch per byte. AArch64 keeps the byte-wise steps: a NEON mask costs more there and the branches predict well.
Non-ASCII text is validated 16 bytes at a time with simdjson's "lookup4" check (Keiser and Lemire, 2021), with NEON on AArch64 and with SSSE3 on x86-64.
- SSSE3 is not part of baseline x86-64. The check is compiled for SSSE3 with a function attribute (GCC 4.9 and later, Clang; MSVC compiles the intrinsics anyway) and used where CPUID reports SSSE3, which all x86-64 CPUs since about 2011 do.
- The answer is cached in a std::atomic<int> initialized at compile time, so there is no guard of a local static and no global constructor (-Wglobal-constructors). The definitions do not depend on compiler flags, so translation units with different flags cannot violate the ODR.
- JSON_VIEW_USE_SSSE3 only skips the CPU check; the same input is accepted either way.
Opt-out: JSON_VIEW_NO_SIMD selects the portable code.
No stall when entering or leaving an object or array: open() stores the parent's frame field by field instead of building it on the stack and copying it. The copy was read back by loads wider than its stores, which waited until the stores retired (failed store forwarding). Apple M1 forwards such stores and does not change.
GCC modules: GCC ignores the target attribute in modules, so src/modules/json.cppm defines NLOHMANN_VIEW_NO_TARGET_ATTRIBUTE there; the check stays portable and the SSE2 code stays on.
Credit: simdjson is credited in the SPDX block of simd.hpp, in the README and in license.md.

Object index

Lookups in objects are linear, as for ordered_json. Objects with 128 members or more now get a hash table after parsing (detail/view/object_index.hpp):

open addressing; of duplicate keys, the first is kept, as for the linear search;
operator[], at(), find(), contains(), count(), value() and JSON pointers take constant time on average in such objects;
probe cap of 64: a key may sit at most 64 slots from its home slot, and a lookup visits at most 65 slots. The hash is not seeded; if crafted keys would exceed the cap, the table is dropped and that object is searched linearly, so parsing cannot become quadratic;
the parser notes a large object when it closes it, out of line, so the parse loop only has a call for it (inline, it made canada.json 37% slower). The object node stores the number of its table in extra;
shrink_to_fit() trims the spare capacity of the index tables, memory_usage() counts them, and the list of noted objects is released after parsing;
the idea of switching to a hash table for large objects comes from Boost.JSON.

Docs, build files and other touched areas

New pages JSON_VIEW_NO_SIMD and JSON_VIEW_USE_SSSE3; the architecture page describes the tables and what extra holds for objects; the lookup pages and the "Duplicate keys" section note that the index leads to the first member.
read() notes that reusing a document avoids the page faults of a fresh node index (about 40% of the parse time of a 55 MB document on x86-64 Linux).
include/nlohmann/json_view.hpp, BUILD.bazel, src/modules/json.cppm, tests/CMakeLists.txt (the builder tests run again with JSON_VIEW_NO_SIMD, and on x86-64 with JSON_VIEW_USE_SSSE3 -mssse3), README.md, docs/mkdocs/docs/home/license.md, .gitignore (GCC module cache).

Performance

Measured on Apple M1 Max (Apple clang -O2) and an x86-64 KVM VPS (GCC 13 / Clang 18 -O2, pinned to one core, about ±5-10% noise), µs, best of 3 interleaved rounds of 15 runs; files from nativejson-benchmark.

json_document::parse, previous PR → this PR:

	Apple M1	x86-64 GCC	x86-64 Clang
twitter	245 → 187 (-24%)	560 → 333 (-41%)	529 → 357 (-33%)
citm_catalog	389 → 374 (-4%)	967 → 786 (-19%)	916 → 816 (-11%)
canada	1019 → 1027 (+1%)	1972 → 1827 (-7%)	2282 → 2028 (-11%)

Object index: looking up every key of an object with 10,000 members takes 59.8 ms linearly and 0.16 ms with the index. Parsing stays within noise for documents without large objects.

The core library (json::parse / dump) is unaffected: the changes are inside include/nlohmann/detail/view/ and json_view.hpp, plus the module file and build files; no file the core lexer or serializer uses is touched.

Tests

Every two-byte sequence, and three- and four-byte sequences with continuation bytes at the edges of their ranges, each placed at every offset around the vector blocks of keys and values, and also cut short; long runs of text with a damaged byte. All are compared with json::accept and json::parse.
CMake builds the builder tests again with JSON_VIEW_NO_SIMD, and on x86-64 with JSON_VIEW_USE_SSSE3 -mssse3.
Large objects: 127, 128, 129 and 10,000 members; duplicate keys (the first wins, with and without a table); escaped, empty and missing keys; colliding keys, which get no table and are searched linearly; shrink_to_fit() releasing the tables' spare capacity; nested large objects, objects in arrays, and documents reused with read().

Public API

No breaking changes. The view API is new in this stack, so nothing here changes a released interface.

Two new configuration macros, documented under Macros: JSON_VIEW_NO_SIMD (portable scanning) and JSON_VIEW_USE_SSSE3 (skip the CPU check; without it, x86-64 builds use SSSE3 when the CPU has it, and the same inputs are accepted or rejected either way). JSON_VIEW_USE_SSSE3 must be defined identically in every translation unit that includes the header.
Lookups in large objects are faster and return the same member as before (the first of duplicate keys); no new members.

Written by Claude Code.

🤖 Generated with Claude Code

github-actions · 2026-09-30T10:54:56Z

🔴 Amalgamation check failed! 🔴

The source code has not been amalgamated and/or formatted correctly, or BUILD.bazel is out of date.

gregmarr · 2026-10-18T03:52:08Z

 1. Linear in the number of members: as for [`ordered_json`](../ordered_json.md), members are compared one after
   another, in document order, stopping at the first match. Each comparison first checks the
   key's length -- already known from the index, without reading the key bytes -- before comparing its content.
+   Objects with 128 or more members get a hash index while parsing, so that a lookup in them takes constant time
