mirror of
https://github.com/logos-messaging/nim-ffi.git
synced 2026-07-02 14:19:31 +00:00
73 lines
2.4 KiB
Markdown
73 lines
2.4 KiB
Markdown
# C Bindings for nim-timer
|
|
|
|
## Purpose
|
|
|
|
This folder contains **auto-generated C bindings** for the `my_timer` Nim
|
|
library. It is generated from `../timer.nim` and provides:
|
|
|
|
- `my_timer.h`: header-only C binding (`MyTimerCtx` + `my_timer_ctx_*` API)
|
|
- `main.c`: example executable demonstrating how to use the bindings
|
|
- `CMakeLists.txt`: build configuration that compiles the Nim library, the
|
|
vendored TinyCBOR, and the C example
|
|
|
|
The bindings speak CBOR on the wire (the same format as the Rust and C++
|
|
backends) using the TinyCBOR copy vendored at
|
|
`ffi/codegen/templates/cpp/vendor/tinycbor`.
|
|
|
|
## How It's Generated
|
|
|
|
Regenerate these bindings by running from the parent directory:
|
|
|
|
```sh
|
|
cd examples/timer
|
|
nimble genbindings_c
|
|
```
|
|
|
|
This invokes the Nim compiler with `-d:targetLang=c`, triggering
|
|
`genBindings(...)` in `timer.nim`, which reads the compile-time FFI registries
|
|
and emits the binding files.
|
|
|
|
## Building the Example
|
|
|
|
```sh
|
|
cd examples/timer/c_bindings
|
|
cmake -S . -B build
|
|
cmake --build build
|
|
./build/my_timer_example
|
|
```
|
|
|
|
## Asynchronous API
|
|
|
|
Every method and the constructor take a typed **result callback** and return
|
|
immediately. The callback fires exactly once — synchronously if the request
|
|
fails to even submit, otherwise from the Nim dispatch thread when the reply
|
|
arrives:
|
|
|
|
```c
|
|
static void on_echo(int err_code, const EchoResponse* reply,
|
|
const char* err_msg, void* user_data) {
|
|
if (err_code != 0) { /* err_msg is set, reply is NULL */ return; }
|
|
printf("echoed: %s\n", reply->echoed.data);
|
|
}
|
|
...
|
|
my_timer_ctx_echo(ctx, &req, on_echo, /*user_data=*/NULL);
|
|
```
|
|
|
|
See `main.c` for the full pattern, including a small `wait_done()` poll helper
|
|
that turns each async call back into a sequential step.
|
|
|
|
## Memory Ownership
|
|
|
|
- Request-side strings/sequences are *borrowed* — wrap C strings with
|
|
`nimffi_str(...)`; the binding never frees them.
|
|
- Reply values and error strings passed into a result callback are **owned by
|
|
the binding** and valid only for the duration of that callback. The caller
|
|
never frees them — copy out anything you need to keep before returning.
|
|
- A `MyTimerCtx*` delivered to the constructor callback is the exception:
|
|
ownership transfers to you, and you release it with `my_timer_ctx_destroy()`.
|
|
|
|
## Do Not Edit
|
|
|
|
The generated files in this folder are overwritten each time
|
|
`nimble genbindings_c` runs. Any manual changes will be lost.
|