Skip to content

Commit

Permalink
Add documentation about boxed_inline to the book
Browse files Browse the repository at this point in the history
  • Loading branch information
sdroege committed Oct 11, 2021
1 parent 50dea7e commit d98ff84
Showing 1 changed file with 13 additions and 4 deletions.
17 changes: 13 additions & 4 deletions book/src/config_api.md
Expand Up @@ -259,17 +259,26 @@ found, based on an existing implementation of `get_type`. Otherwise no record
implementation can be generated.

Some boxed types are passed as `out` parameters to functions and the caller is
required to allocate them. For this it is necessary to provide Rust
required to allocate them. For this the boxed type has to be configured as
inline-allocated boxed type, i.e. the memory of is not allocated on the heap
but directly as part of the value e.g. on the stack.

For inline-allocated boxed types it is possible to provide Rust
expressions in the configuration for initializing newly allocated memory for
them, and to free any resources that might be stored in values of that boxed
types. By default the memory is zero-initialized and it is valid to provide an
empty closure like below.
them, to copy from one value into another one, and to free any resources that
might be stored in values of that boxed types.

By default the memory is zero-initialized and copying is done via
`std::ptr::copy()`. If the boxed type contains memory that needs to be freed
then these functions must be provided.

```toml
[[object]]
name = "Gtk.TreeIter"
status = "generate"
boxed_inline = true
init_function_expression = "|_ptr| ()"
copy_into_function_expression = "|dest, src| { std::ptr::copy(src, dest, 1); }"
clear_function_expression = "|_ptr| ()"
```

Expand Down

0 comments on commit d98ff84

Please sign in to comment.