Expand description
Safe Rust bindings to cuJSON — a GPU JSON parser
from the paper cuJSON: A GPU-Accelerated JSON Parser (ASPLOS ’26,
cited in the workspace Cargo.toml description). This crate calls the
upstream CUDA kernels through the plain C ABI in
crates/cujson-sys/cuda/cujson_capi.h and exposes the resulting tape
(tape::Tape) through a Document/Node navigator
(crates/cujson/src/tape/document.rs).
§The cuda feature
Without it (the default), every parsing function returns
Err(Error::CudaNotCompiled) — the crate still builds and its
navigator/CPU-reference code (cpu-reference feature) still works, but
no FFI declarations exist to call. With it, build.rs
(crates/cujson-sys/build.rs) compiles upstream’s CUDA sources with
nvcc and links cudart_static, so the resulting binary depends only
on the NVIDIA driver (libcuda.so.1, loaded at runtime) — no CUDA
shared libraries need to be installed or bundled. CUJSON_CUDA_ARCHS
(an env var read by that build script) overrides the default compiled
architecture list, e.g. CUJSON_CUDA_ARCHS=80 for a fast local build
targeting one GPU generation.
§Limits
cuJSON uses int-sized token counts internally. Inputs within 8 bytes
of i32::MAX (see MAX_INPUT_LEN) are rejected by this crate with
Error::InputTooLarge before ever reaching C++.
§Example
let doc = cujson::parse(br#"{"a": [1, 2, 3]}"#)?;
let a = doc.root().get("a").unwrap();
assert_eq!(a.index(1).unwrap().as_i64(), Ok(2));Re-exports§
pub use tape::Document;
Modules§
- cpu
- The CPU reference parser (
cpu-referencefeature), kept in its own module and never called byparse/parse_lines/parse_file— so that nobody benchmarks this path while believing it’s the GPU one. Its tape is bit-for-bit whattape/FORMAT.mddocuments the GPU as producing, but that equivalence is a hypothesis until confirmed by a real GPU (tape::diff_tapes, task 10). - tape
- Tape format, CPU reference builder, and navigator.
Structs§
- Cuda
Info - CUDA runtime/device info, returned by
cuda_info. - Device
Info - Lines
Options - Options for
parse_lines. - Pinned
Buffer - A byte buffer in page-locked (pinned) host memory when built with the
cudafeature, and in ordinary memory otherwise.
Enums§
- Error
- Errors from the GPU-parsing entry points (
crate::parseand friends) andcrate::cuda_info.
Constants§
- MAX_
INPUT_ LEN - Largest input length this crate will pass to cuJSON. cuJSON pads its
input up to a 4-byte boundary and works in
int-sized token counts;capi_standard.cu/capi_lines.curejectsize >= INT32_MAX - 8at the FFI boundary, and this constant mirrors that check so an oversized input is rejected on the Rust side with a typed error instead of reaching C++.
Functions§
- cuda_
info - CUDA runtime version, visible devices, and this build’s compiled
architecture list. Without the
cudafeature, alwaysErr(Error::CudaNotCompiled). On a machine with no NVIDIA driver installed,Err(Error::Cuda { .. })(the driver call itself failed) orErr(Error::NoDevice)(the driver responded but reports zero devices) — never a panic. - device_
memory - Free/total device memory in bytes (
cudaMemGetInfo, after acudaDeviceSynchronize). Used bycujson verify’s memory-growth heuristic (task 07); not called byparse/parse_lines. - driver_
version - The driver’s supported CUDA version (
cudaDriverGetVersion’s encoding), or0if no driver responds. Unlikecuda_info, this never errors on a driverless/deviceless host — it’s meant to be called aftercuda_infoor aparse*call has already failed, so a caller (e.g.cujson verify) can distinguish “no driver at all” (driver_version() == 0) from “driver present but too old for this binary’s CUDA runtime” (driver_version() > 0but belowCudaInfo::runtime_version) when building a hint message. - parse
- Parse
inputas standard JSON on the GPU. Borrowsinputfor the lifetime of the returnedDocument. - parse_
file - Read
pathand parse it as standard JSON on the GPU. - parse_
lines - Parse
inputas JSON Lines (newline-delimited JSON) on the GPU. Seetape/FORMAT.md§5 for the tape this produces — every top-level value is reachable viaDocument::lines(). - parse_
lines_ owned - Parse owned
inputas JSON Lines on the GPU, returning a'staticDocumentthat owns its bytes (mirrorsparse_ownedforparse_lines). - parse_
owned - Parse owned
inputas standard JSON on the GPU, returning a'staticDocumentthat owns its bytes. - runtime_
version - The CUDA runtime version this binary was built against
(
cudaRuntimeGetVersion’s encoding), independent of whether a device or driver is present — pairs withdriver_versionto build a hint message whencuda_infofails. - set_
max_ concurrent_ parses - Let up to
nparses run on the GPU at once (default 1). Parses from different threads then overlap: one’s input copy with another’s kernels and tape copy back. Each in-flight parse needs its own device memory, and the pinned tape cache is resized to keepn + 2buffers (nbeing built, one queued, one being read), so a pipeline stops allocating pinned memory. No-op without thecudafeature. - trim_
pinned_ cache - Release the pinned host buffers kept for later parses. After a parse,
dropping its
Documentkeeps the tape’s pinned buffer for reuse, up to a limit of one buffer by default (set_max_concurrent_parsesraises it ton + 2), so the next parse skipscudaMallocHost; call this to give that memory back. No-op without thecudafeature.