pheon/docs/native-api.md
Jan Petykiewicz 8efeb04aab Simplify and speed up GDSII diffs
Summarize added and removed cells, group references, and keep replacement pairs together at text display limits. Trim hierarchy labels and summarize long unmatched paths.

Stream JSON object evidence and reduce parsing and comparison allocations. Parse large revisions concurrently and adaptively reuse matching cell bodies when most of the layout is shared.
2026-11-18 10:58:19 -08:00

92 lines
4.5 KiB
Markdown

# Rust and C integration
Use the Rust library or C API to read GDSII into Arrow without Python. For the
returned data layout, see the [Arrow reference](arrow-schema.md).
## Rust
Add `pheon` as a dependency. The library readers accept GDSII byte slices:
```rust
use pheon::library::read_library;
let bytes = std::fs::read("chip.gds").expect("read layout");
let (_remainder, layout) = read_library(&bytes).expect("parse layout");
println!("{layout:?}");
```
`read_library` reads geometry; `scan_library` returns metadata, references, and
cell ranges. Pass `(start, end)` ranges from a scan to `read_selected_library`
to load only those cells. Each range must span one complete cell. Readers return
`(remainder, StructArray)` on success. The selected reader returns the original
input as its remainder, since selection is random access.
Layout-review APIs live in `pheon::review`, with layer-name helpers in
`pheon::review::names` and scope/display selectors in `pheon::review::selection`.
`Comparison::between(&old, &new)` captures an owned result with revision metadata,
changes, and structured diagnostics. Use `outcome()` for completeness, equality,
and exit status. Its renderers work after the source documents and byte buffers
are dropped. `json_report` returns a JSON value, and `write_json_report` writes
object evidence incrementally to a writer. `Document::hierarchy` inspects a
single revision. A comparison captures reference counts and analyzes the union
graph and ancestors when a hierarchy is requested.
`TextComparison::between` captures the data needed for text and hierarchy
reports. Layered objects in added and removed cells contribute to the cell's
object count.
Use `RevisionPair::parse(&old_bytes, &new_bytes)` for an unscoped comparison
that can reuse matching cells. Its `compare` and `compare_text` methods return
the corresponding owned comparison.
The `record`, `records`, and `basic` modules also provide low-level GDSII record
writing. There is no high-level writer for the Arrow layout. REAL8 writing is
exact for representable in-range `f64` values: magnitudes below `2^-260`
underflow to zero; magnitudes at least `2^252` and nonfinite values are rejected.
Record writes check payload sizes before emitting bytes. Header packing returns
an `io::Result`, including an error when the total size exceeds the format limit.
Arrow readers return parse errors for invalid UTF-8 strings and timestamp years
that exceed the Int16 range after conversion from the 1900 epoch.
## C API
Build the shared library with `cargo build --release --locked`. The
[header](https://mpxd.net/code/jan/pheon/src/branch/master/pheon/_ffi.h) defines the functions and Arrow C Data structures.
The library is `libpheon.so`, `libpheon.dylib`, or `pheon.dll` on Linux, macOS,
or Windows respectively.
| Function | Input | Result |
| --- | --- | --- |
| `read_path` | NUL-terminated path | Full layout. |
| `read_bytes` | Byte pointer and size | Full layout. |
| `scan_bytes` | Byte pointer and size | Metadata, references, and cell ranges. |
| `read_cells_bytes` | Bytes and cell ranges | Full layout for selected cells. |
`read_path` accepts UTF-8 paths on Windows and filesystem bytes on Unix. It reads
uncompressed GDSII; Python's `read_path` adds gzip handling.
For `read_cells_bytes`, `ranges` points to alternating uint64 start/end offsets
and `range_count` is the number of cells, not the number of offsets. Ranges are
half-open, from BGNSTR through the end of ENDSTR. Range values must be aligned,
native-endian uint64 values. Input buffers must remain readable for the call.
Null buffer pointers are allowed only when their corresponding length is zero.
### Status and ownership
Each reader returns 0 on success and -1 on failure. Call `last_error_message()`
on the same thread after a failure. It returns a borrowed NUL-terminated message;
copy it before the next parser call or thread exit. It returns null after a
successful parser call.
Supply valid, writable, initialized `ArrowArray` and `ArrowSchema` structures
without live allocations to overwrite. A failed call leaves them unchanged.
Successful outputs own their storage independently of the input buffer. Transfer
ownership to an Arrow importer, or call each non-null release callback exactly
once. Do not release structures again after an importer takes ownership.
`pheon_abi_version()` and `pheon_arrow_schema_version()` both currently return 1.
Check both before using the API. The C calling/ownership contract and Arrow
layout have separate versions; neither is the package version or the
[JSON report schema](diff-reports.md).