Skip to main content

Crate cujson

Crate cujson 

Source
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-reference feature), kept in its own module and never called by parse/parse_lines/parse_file — so that nobody benchmarks this path while believing it’s the GPU one. Its tape is bit-for-bit what tape/FORMAT.md documents 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§

CudaInfo
CUDA runtime/device info, returned by cuda_info.
DeviceInfo
LinesOptions
Options for parse_lines.
PinnedBuffer
A byte buffer in page-locked (pinned) host memory when built with the cuda feature, and in ordinary memory otherwise.

Enums§

Error
Errors from the GPU-parsing entry points (crate::parse and friends) and crate::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.cu reject size >= INT32_MAX - 8 at 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 cuda feature, always Err(Error::CudaNotCompiled). On a machine with no NVIDIA driver installed, Err(Error::Cuda { .. }) (the driver call itself failed) or Err(Error::NoDevice) (the driver responded but reports zero devices) — never a panic.
device_memory
Free/total device memory in bytes (cudaMemGetInfo, after a cudaDeviceSynchronize). Used by cujson verify’s memory-growth heuristic (task 07); not called by parse/parse_lines.
driver_version
The driver’s supported CUDA version (cudaDriverGetVersion’s encoding), or 0 if no driver responds. Unlike cuda_info, this never errors on a driverless/deviceless host — it’s meant to be called after cuda_info or a parse* 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() > 0 but below CudaInfo::runtime_version) when building a hint message.
parse
Parse input as standard JSON on the GPU. Borrows input for the lifetime of the returned Document.
parse_file
Read path and parse it as standard JSON on the GPU.
parse_lines
Parse input as JSON Lines (newline-delimited JSON) on the GPU. See tape/FORMAT.md §5 for the tape this produces — every top-level value is reachable via Document::lines().
parse_lines_owned
Parse owned input as JSON Lines on the GPU, returning a 'static Document that owns its bytes (mirrors parse_owned for parse_lines).
parse_owned
Parse owned input as standard JSON on the GPU, returning a 'static Document that 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 with driver_version to build a hint message when cuda_info fails.
set_max_concurrent_parses
Let up to n parses 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 keep n + 2 buffers (n being built, one queued, one being read), so a pipeline stops allocating pinned memory. No-op without the cuda feature.
trim_pinned_cache
Release the pinned host buffers kept for later parses. After a parse, dropping its Document keeps the tape’s pinned buffer for reuse, up to a limit of one buffer by default (set_max_concurrent_parses raises it to n + 2), so the next parse skips cudaMallocHost; call this to give that memory back. No-op without the cuda feature.