Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions uniffi/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,3 +14,7 @@
style, where an async call returns `uniffi::Future<T, E>`.
- Generated C: every type and function name starts with the crate's namespace, so a crate
whose items did not already start with it gets renamed C symbols.
- Generated C: type names are CamelCase, as in GLib: `app_my_object *` is now `AppMyObject *`,
`app_task` is `AppTask`, enum tags are `<Enum>Tag`, variant structs `<Enum><Variant>`, and
async callback types `<Function>Callback` (`app_my_object_do_thing_callback` is now
`AppMyObjectDoThingCallback`). Functions and enum constants keep their names.
23 changes: 14 additions & 9 deletions uniffi/cpp/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,27 +54,32 @@ and RTTI may be off) and include only `<namespace>.h` from C.
uniffi-bindgen-cpp --lang c --library your_rust_library.so --out-dir output_directory
```

Names are the uniffi names in snake case, prefixed with the namespace unless they already start
with it, since every crate's C API shares one scope: in namespace `app`, `MyObject.do_thing` is
`app_my_object_do_thing`, and its handle is `app_my_object *`, released with
`app_my_object_free`; `AppObject` is `app_object`. The rest follows from a few rules:
Names follow GLib: functions are snake_case and types CamelCase, both starting with the
namespace unless the uniffi name already does, since every crate's C API shares one scope. In
namespace `app`, `MyObject` is `AppMyObject *`, created with `app_my_object_new` and released
with `app_my_object_free`, and its method `do_thing` is `app_my_object_do_thing`, which a record
`MyObjectDoThing` (`AppMyObjectDoThing`) never meets. `AppObject` stays `AppObject`, and types are
re-cased from snake case, so `HTTPServer` is `AppHttpServer`. Two items that still render one
name, such as `AppObject` and `Object`, or a method `free` and the release function, are refused
with both named. The rest follows from a few rules:

* A call that can fail returns an error struct, or NULL on success, and writes its result to a
trailing `out` pointer. An error is a tagged union with a `message`; free it with `<error>_free`.
* Records are plain structs, data-carrying enums are a `tag` plus an anonymous union of
`<enum>_<variant>` structs (`shape->circle.radius`), and flat enums are C enums. A record
`<Enum><Variant>` structs (`shape->circle.radius`), and flat enums are C enums. A record
with `#[uniffi(default)]` fields gets `<record>_default()`.
* Arguments are borrowed for the call. Everything returned is owned by the caller and freed with
the matching `_free` (`<namespace>_string_free` for strings).
* Optional strings, objects, and structs are pointers that are NULL when absent; optional scalars
are `{ has_value, value }` structs. Bytes, lists, and maps are pointer and length structs.
* An async call takes a callback and `user_data` and returns a `<namespace>_task *`. The callback
runs once on the dispatcher with the result, which it owns, unless the dispatcher refuses the
work or has shut down, which abandons the call. Free every task: freeing a pending
* An async call takes a callback, typed as the function's name in CamelCase plus `Callback`
(`AppMyObjectDoThingCallback`), and `user_data`, and returns a `<Namespace>Task *`. The
callback runs once on the dispatcher with the result, which it owns, unless the dispatcher
refuses the work or has shut down, which abandons the call. Free every task: freeing a pending
one cancels the Rust future, and once `<namespace>_task_free` returns the callback has finished
or will never run.
* Callbacks run on the default dispatcher thread unless `<namespace>_set_dispatcher` installs a
host's own, which receives `<namespace>_work *` items to run with `<namespace>_work_run`.
host's own, which receives `<Namespace>Work *` items to run with `<namespace>_work_run`.
* A type from another crate keeps that crate's C name and `_free`, and its header is included.
Generate the C API of every crate involved (one `--crate` each, or all at once) and compile
each one's `<namespace>.cpp` and `<namespace>_c.cpp`; a crate's implementation converts its
Expand Down
Loading
Loading