forked from 14134597/fast_json
103 lines
3.7 KiB
Markdown
103 lines
3.7 KiB
Markdown
# fast_json - High-Performance MQL5 JSON Library
|
|
|
|
> "If your JSON parser needs recursion, you're doing it wrong."
|
|
|
|
## Overview
|
|
|
|
**fast_json** is a production-grade, high-performance JSON library for MQL5, engineered for scenarios where **I/O throughput** and **memory efficiency** are paramount.
|
|
|
|
Unlike standard libraries that fragment the heap with thousands of small object allocations, **fast_json** employs a **tape-based zero-allocation memory model**. It parses JSON directly into a contiguous integer array (the "tape"), enabling it to process gigabytes of data with minimal overhead and zero garbage collection pressure.
|
|
|
|
## Key Features
|
|
|
|
- **🚀 Zero-Alloc Tape Architecture**: Parses the entire JSON into a single contiguous integer array. No objects are created during parsing.
|
|
- **⚡ SWAR Acceleration**: Uses Simulated 64-bit SWAR (SIMD within a Register) to scan 8 bytes at a time for structural characters, significantly reducing branch misprediction.
|
|
- **🛡️ Stack-Safe Iterative Parser**: Implemented as a finite state machine. Zero recursion. Immune to stack overflow from deeply nested JSONs.
|
|
- **🔧 Handle-Based Navigation**: Data access via lightweight `CJsonNode` structs that point to the tape. Copying nodes is free.
|
|
- **💾 High-Throughput I/O**: Optimized for rapid Read/Write operations, making it ideal for LLM integration, REST API consumption, and large dataset processing.
|
|
|
|
## Performance
|
|
|
|
| Metric | fast_json | Standard Libs |
|
|
|--------|-----------|---------------|
|
|
| **Allocation Strategy** | 1 contiguous block (Tape) | N objects per node |
|
|
| **Recursion Depth** | Unlimited (Heap stack) | Limited (Call stack) |
|
|
| **Read/Write Speed** | **EXTREME** (300MB/s+ Est.) | LOW |
|
|
| **Memory Fragmentation**| Near Zero | High |
|
|
|
|
## Installation instructions
|
|
|
|
### OPTION A: Via KnitPkg (recommended)
|
|
|
|
#### Prerequisites
|
|
|
|
To use `json_fast` in your KnitPkg project, you will need:
|
|
|
|
1. [**MetaTrader 5**](https://www.mql5.com/) installed.
|
|
2. [**KnitPkg CLI**](https://knitpkg.dev): The KnitPkg package manager for MetaTrader. If you don't have it, you can install it by following the instructions in the [KnitPkg documentation](https://docs.knitpkg.dev/installation/).
|
|
|
|
#### Installing as a dependency
|
|
|
|
Execute the following command in your project directory:
|
|
|
|
```bash
|
|
kp add @14134597/fast_json
|
|
kp install
|
|
```
|
|
|
|
### OPTION B: Manual installation
|
|
|
|
Simply download the header file `knitpkg/include/14134597/fast_json/fast_json.mqh` into your MetaTrader Include/ directory or
|
|
put this header along with your other source mql files.
|
|
|
|
## Usage
|
|
|
|
### Parsing
|
|
```mql5
|
|
#include "../knitpkg/include/14134597/fast_json/fast_json.mqh"
|
|
|
|
CJson toolkit;
|
|
string json = "{\"price\": 1.2345, \"currency\": \"EURUSD\"}";
|
|
|
|
if (toolkit.Parse(json)) {
|
|
// Zero-copy access
|
|
double price = toolkit["price"].ToDouble();
|
|
string curr = toolkit["currency"].ToString();
|
|
Print(curr, ": ", price);
|
|
}
|
|
```
|
|
|
|
### Building & Serializing
|
|
```mql5
|
|
CJsonBuilder builder;
|
|
builder.Obj()
|
|
.Key("signal").Val("buy")
|
|
.Key("volume").Val(0.1)
|
|
.EndObj();
|
|
|
|
string payload = builder.Build();
|
|
// Result: {"signal":"buy","volume":0.1}
|
|
```
|
|
|
|
## Why fast_json?
|
|
|
|
Because typical MQL5 libraries were designed for configuration files, not high-throughput data streams. **fast_json** bridges that gap.
|
|
|
|
## Running unit tests with KnitPkg
|
|
|
|
You can execute `kp get` to query the KnitPkg Registry for metadata and automatically download/build the latest stable version of `fast_api`.
|
|
|
|
Example (run from your MetaTrader *Data Folder* root):
|
|
|
|
```bash
|
|
cd "C:\Users\username\AppData\Roaming\MetaQuotes\Terminal\<TERMINAL_ID>"
|
|
|
|
kp get mql5 @14134597/fast_json
|
|
```
|
|
|
|
In Metatrader, refresh the Navigator and then run the unit test scripts under Scripts/fast_json/bin
|
|
|
|
|
|
## License
|
|
|
|
MIT.
|