logos-messaging/nim-ffi
1
0
Fork 0
mirror of https://github.com/logos-messaging/nim-ffi.git synced 2026-06-20 16:29:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(examples): make clear the CBOR ABI is for IPC only

Browse Source 
Every generated library exports both ABIs side by side; spell out the choice in
the example READMEs: the native (pure-C) ABI is the default for same-process /
local calls (flat C structs, zero serialization), while the CBOR ABI exists
solely for inter-process communication (different process or machine). In a
shared address space CBOR is pure overhead, so prefer native locally.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Ivan FB 2026-05-31 12:31:50 +02:00
parent 0bba42d2a2
commit 2ec514cf9f
No known key found for this signature in database
GPG Key ID: DF0C67A04C543270
3 changed files with 25 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
examples/timer/README.md
View File

@ -2,6 +2,17 @@
This example is a self-contained Nimble project demonstrating how to import `nim-ffi` and use the `.ffiCtor.` / `.ffi.` abstraction.
## Two ABIs, one library
Every generated library exports **two ABIs side by side**, and you choose per call site:
| ABI | Header / symbols | Use it for |
|-----|------------------|------------|
| **Native (pure C)** | `<lib>.h` / `<name>` | **Same-process / local** calls. Flat C structs by value, zero serialization. |
| **CBOR** | `<lib>_cbor.h` / `<name>_cbor` | **Inter-process communication only** — a different process or machine, where the request must be serialized to cross the boundary. |
In a shared address space the CBOR round-trip is pure overhead, so **default to the native ABI locally and reach for CBOR only when you actually cross a process/machine boundary** (see [`ipc/`](ipc)). The per-language examples below: native C ([`c_bindings/`](c_bindings)), native Go ([`go_bindings/`](go_bindings)), native/CBOR C++ ([`cpp_bindings/`](cpp_bindings)), CBOR Rust ([`rust_client/`](rust_client)), and CBOR-over-socket IPC ([`ipc/`](ipc)).
## Usage
1. Change into the example directory:

9
examples/timer/c_bindings/README.md
View File

@ -3,6 +3,15 @@
Generated C headers for the timer library plus a small driver that links the
library directly and calls the **native** (zero-serialization) ABI.
> **Which ABI?** The library exports **both** ABIs from the same shared object,
> side by side: the native `<name>` symbols and the CBOR `<name>_cbor` symbols.
> Use the **native (pure-C) ABI for same-process / local calls** — it passes
> flat C structs with zero serialization. Use the **CBOR ABI only for
> inter-process communication** (a different process, or a different machine),
> where the data has to be serialized to cross the boundary anyway. In one
> address space, CBOR is pure overhead — prefer native. See [`../ipc`](../ipc)
> for the CBOR/IPC path.
## Files
| File | Description |

5
examples/timer/ipc/README.md
View File

@ -6,6 +6,11 @@ library **in the same process**. When the caller lives in a *different process*
request has to be serialized. That is exactly what the **CBOR ABI**
(`<name>_cbor`, declared in `my_timer_cbor.h`) is for.
> **The CBOR ABI exists solely for inter-process communication.** If you are in
> the same process as the library, use the native ABI instead — serializing to
> CBOR and decoding it on a sibling thread is pure overhead when you already
> share memory. Both ABIs ship in the same library; pick per call site.
This example wires that ABI across a socket:
- **`server`** links `libmy_timer`, creates one timer context at startup, and