Repository navigation
Performance
This page shows how fast rustyon is, how it compares to Go's encoding/json, and how every operation scales with input size.
Short version: every operation is linear in the size of the input. Typed Unmarshal decodes straight from the text and is on par with encoding/json (about 7 percent faster on this payload). Parse into a dynamic tree is about 2.3 times faster than encoding/json decoding into any. Typed Marshal is about 2.3 times slower than encoding/json, which is one of the most optimized packages in the Go standard library. A 100 item inventory file (13 KB) encodes in 0.13 ms, decodes in 0.09 ms and formats in 0.18 ms.
| Machine | Apple M2, macOS, darwin/arm64
|
| Go | 1.27.1 |
| Method |
go test -run '^$' -bench . -benchmem -count 8, median of 8 runs |
| Payload | an inventory with 100 items, each with an id, name, weight, 3 tags, a 2 entry map and an optional owner |
| Payload size | 13.0 KB as compact RON, 13.8 KB as compact JSON |
The same Go values are used for both libraries, so the numbers compare like for like. The benchmarks live in bench_test.go. Run them yourself with:
make bench
# or
go test -run '^$' -bench . -benchmem -count 8 .Absolute numbers depend on your machine. The ratios between rustyon and encoding/json are what to look at. With 8 samples the median is the mean of the two middle ones. The first Marshal samples of the full run were disturbed (132 to 213 us), so the Marshal figures come from a second run of the Marshal benchmark alone, which was stable (128 to 138 us).
Lower is better. Microseconds per operation on the 100 item payload.
xychart-beta horizontal
title "Time per operation, 100 items (us, lower is better)"
x-axis ["Marshal ron", "Marshal json", "Unmarshal ron", "Unmarshal json", "Parse ron", "Parse json", "Format ron", "Indent json"]
y-axis "microseconds" 0 --> 250
bar [130, 56, 94, 101, 98, 221, 177, 33]
| Operation | rustyon | encoding/json | Ratio |
|---|---|---|---|
| Marshal (Go struct to text) | 130 us | 56 us | 2.3x slower |
| Unmarshal (text to Go struct) | 94 us | 101 us | 1.08x faster |
Parse into a dynamic tree (Parse vs Unmarshal into any) |
98 us | 221 us | 2.3x faster |
Pretty print (Format vs json.Indent) |
177 us | 33 us | 5.3x slower |
Higher is better. Megabytes of input (or output) per second, each library measured on its own text.
xychart-beta horizontal
title "Throughput, 100 items (MB/s, higher is better)"
x-axis ["Marshal ron", "Marshal json", "Unmarshal ron", "Unmarshal json", "Parse ron", "Parse json", "Format ron", "Indent json"]
y-axis "MB/s" 0 --> 450
bar [100, 247, 138, 136, 132, 62, 73, 415]
Allocations per operation. Fewer allocations mean less garbage collector work.
xychart-beta horizontal
title "Allocations per operation, 100 items (lower is better)"
x-axis ["Marshal ron", "Marshal json", "Unmarshal ron", "Unmarshal json", "Parse ron", "Parse json", "Format ron", "Indent json"]
y-axis "allocations" 0 --> 3500
bar [2380, 403, 1011, 879, 3018, 3340, 1317, 0]
| Operation | rustyon | encoding/json |
|---|---|---|
| Marshal | 107 KB, 2380 allocs | 18 KB, 403 allocs |
| Unmarshal | 74 KB, 1011 allocs | 63 KB, 879 allocs |
| Parse (dynamic) | 121 KB, 3018 allocs | 119 KB, 3340 allocs |
| Format / Indent | 327 KB, 1317 allocs | 7 B, 0 allocs |
-
Unmarshal streams.
UnmarshalandDecoderread the text once and write straight into your Go values, likeencoding/json. NoValuetree is built, so the cost is close to one allocation per string, slice or map that you asked for. A tree is built only for the parts of the input that need one: values going intoanyor arustyon.Value, registered enums, and types withUnmarshalRONorUnmarshalText. -
Parsing is fast. When both libraries build a dynamic tree, rustyon is about 2.3 times faster than
encoding/jsonand allocates less. -
Marshal still goes through a tree. rustyon converts Go values to a
Valuetree and prints it, whileencoding/jsonwrites bytes directly while walking the Go value. The tree costs one allocation per value but keeps the encoder,Raw,PrettyConfig, enum representations and theValueAPI consistent with each other. That is where the remaining 2.3x comes from. -
Formatdoes far more thanjson.Indent.json.Indentreindents bytes without understanding them.Formatfully validates the document (including literal ranges and extensions), keeps every comment in place, and decides layout per collection. It is not a like for like comparison; it is shown so you know what to expect. - RON is richer. Enum variants, struct names, raw strings, number bases and 128-bit integers all need handling that JSON does not have.
Inventories with 10, 100, 1,000 and 10,000 items (1.3 KB to 1.35 MB of RON). If an operation is linear, its throughput stays constant as the input grows.
xychart-beta
title "Throughput by input size (MB/s, flat means linear)"
x-axis ["10 items", "100 items", "1,000 items", "10,000 items"]
y-axis "MB/s" 0 --> 160
line [129.5, 137.0, 138.5, 130.0]
line [91.5, 96.0, 95.0, 93.5]
line [70.5, 77.5, 71.0, 63.5]
Lines from top to bottom: Unmarshal, Marshal, Format.
| Items | RON size | Marshal | Unmarshal | Format |
|---|---|---|---|---|
| 10 | 1.3 KB | 0.014 ms | 0.010 ms | 0.018 ms |
| 100 | 13 KB | 0.13 ms | 0.095 ms | 0.17 ms |
| 1,000 | 132 KB | 1.38 ms | 0.96 ms | 1.85 ms |
| 10,000 | 1.35 MB | 14.4 ms | 10.4 ms | 21.2 ms |
Each 10x increase in input gives about a 10x increase in time. Format shows the only drift: its throughput falls from 77 to 64 MB/s at 10,000 items, where it allocates 34 MB per call and the garbage collector and caches start to matter. That is a constant factor, not a change in complexity.
n is the size of the input in bytes, v the number of values, d the nesting depth, m the number of entries in a map, f the number of fields in a struct.
| Operation | Complexity | Notes |
|---|---|---|
| Lexing | O(n) | Single forward pass with at most 3 bytes of lookahead. Raw strings search for their closing delimiter once. |
Parse, ParseDocument, Valid
|
O(n) | Recursive descent with one token of lookahead. |
Unmarshal, Decoder.Decode
|
O(n) | One streaming pass over the text that fills the Go value as it reads. Struct fields are found with a hash lookup. Parts that need a tree (any, Value, enums, custom unmarshalers) are parsed into a small tree for just that part. |
Unmarshal on invalid input |
O(n) | The streaming decoder only reports that it failed. The input is then parsed once more to find the syntax error, or decoded through the tree into a scratch value to find the type error, so reporting an error costs extra passes over the input, still linear. |
Marshal, Encoder.Encode
|
O(n + sum of m log m) | One pass over the Go value plus sorting the keys of each Go map, so output is deterministic. |
MarshalWithConfig |
O(n + sum of m log m) | Same as Marshal. Layout options only change what the printer writes. |
Format, FormatIndent
|
O(n) | Lex, build a small syntax tree with comments, print. |
ToValue, FromValue
|
O(v) | Like Marshal and Unmarshal without the text step. |
Equal |
O(v) | Visits each value once. |
Struct.Get, Struct.Set
|
O(f) | Linear scan, fields keep their source order. |
Map.Get, Map.Set
|
O(m) | Linear scan, entries keep their source order and keys can be any value. |
| Enum and unit enum lookups | O(1) | Hash lookups on an immutable snapshot, no locks. An untagged enum tries its variants in order, so decoding it is O(variants) per value. |
RegisterEnum, RegisterEnumWith, RegisterUnitEnum
|
O(total registered variants) | Copy on write. Meant for program start. |
ronjson.ToJSON, ronjson.FromJSON
|
O(n) | One parse and one print. |
| Syntax error position | O(n) | Line and column are computed from the byte offset only when an error is reported, which keeps the happy path fast. |
The first time a Go type is encoded or decoded, its fields and interface methods are inspected with reflection, which is O(f). The result is cached for the lifetime of the program.
| Operation | Extra memory |
|---|---|
Parse |
O(n) for the tree, plus O(d) stack |
Unmarshal |
O(d) stack plus the Go values themselves, so O(output). No tree for the whole document. The tree for an any, Value or enum part is the size of that part. |
Marshal |
O(n) for the tree and the output buffer |
Format |
O(n): 12 bytes per token, plus one node per collection and item |
| Nesting |
Parse, Format and Unmarshal share the budget of ron-rs: 64 nested collections or 128 nested Some(. The encoder stops at 1000 levels. Deeper input is an error, so hostile input cannot exhaust the stack. |
The parser, decoder and formatter are fuzzed continuously in CI (FuzzParse, FuzzFormat, FuzzUnmarshal). Pathological inputs stay linear. Median of 21 runs on the same machine:
| Input | Size | Parse |
Format |
|---|---|---|---|
64 nested [ (the deepest allowed) |
128 B | 0.01 ms | 0.03 ms |
128 nested Some( (the deepest allowed) |
769 B | 0.01 ms | 0.05 ms |
| 100,000 nested block comments | 400 KB | 2.9 ms | 2.5 ms |
| 100,000 comments before a value | 700 KB | 1.5 ms | 9.5 ms |
| a list of 200,000 integers | 400 KB | 12 ms | 19 ms |
Inputs nested deeper than the budget are rejected, see Limits.
-
Decode into concrete types, not
any. Typed decoding skips buildingmap[string]anyand[]any. -
Use
Rawfor parts you decode later or never. It copies the text of the value instead of building anything. -
Reuse an
Encoderfor many values written to one stream. - Register enums once, at program start. Registration copies the registry; lookups are free after that.
-
Prefer the external enum representation (
RegisterEnum) on hot paths. Untagged enums try each variant in turn. -
Use compact output (
Marshal) for machine to machine data. Pretty printing costs a little more and produces larger files. -
Skip
Formaton hot paths. It is meant for files people edit, not for data you just produced withMarshalIndentorMarshalWithConfig, which is already formatted.
rustyon is licensed under the BSD-3-Clause license. It is an independent implementation of RON and is not affiliated with the ron-rs project.