diff options
author | Emmanuele Bassi <ebassi@gmail.com> | 2023-03-18 22:52:04 +0000 |
---|---|---|
committer | Emmanuele Bassi <ebassi@gmail.com> | 2023-03-18 23:05:22 +0000 |
commit | 305f1e2fe15e226663f5bdcb7735bc84218b06a5 (patch) | |
tree | 5005e9804b9fd3ff2414c7023234c76a38c53031 /docs/website/writingbindableapis.rst | |
parent | 2698fcf7c8eec872047de205ce643885550edfee (diff) | |
download | gobject-introspection-305f1e2fe15e226663f5bdcb7735bc84218b06a5.tar.gz |
docs: Add Emmanuele's suggestions to "Writing Bindable APIs"
These suggestions came up in code review.
Diffstat (limited to 'docs/website/writingbindableapis.rst')
-rw-r--r-- | docs/website/writingbindableapis.rst | 16 |
1 files changed, 11 insertions, 5 deletions
diff --git a/docs/website/writingbindableapis.rst b/docs/website/writingbindableapis.rst index ca790bee..ed2ac9a0 100644 --- a/docs/website/writingbindableapis.rst +++ b/docs/website/writingbindableapis.rst @@ -132,8 +132,9 @@ return value or an out argument. FooBoxed *boxed_in, FooBoxed **boxed_out); -In particular, don't require the caller to pass in a ``GValue`` which a C -function modifies. +In particular, do not require the caller to pass an initialized ``GValue`` to +avoid the in-out annotation; instead, pass a ``GValue`` as an out argument, and +have the function initialize it. Arrays @@ -152,7 +153,7 @@ deal with. Strings ~~~~~~~ -C treats strings as arrays of bytes, but many other languages do not. So don't +C treats strings as zero-terminated arrays of bytes, but many other languages do not. So don't write APIs that treat ``const char *`` parameters as arrays that need an ``array length`` annotation. @@ -169,6 +170,9 @@ contain embedded zeroes. const uint8_t *bytes, size_t length); +In particular, avoid functions taking a ``const char *`` with a signed length +that can be set to a negative value to let the function compute the string +length in bytes. These functions are hard to bind, and require manual overrides. Callbacks ~~~~~~~~~ @@ -231,7 +235,7 @@ Transfer-none return values from the binding If your library expects to call a function from C which may be implemented in another language and exposed through the binding (for example, a signal handler, -or a GObject vfunc), it's best not to return transfer-none strings, because what +or a GObject vfunc), it's best not to return transfer-none values, because what you assume about storage lifetime in C may not apply in other languages. For example, @@ -249,4 +253,6 @@ A class that implements ``FooBazIface`` in another programming language may not be able to return a static string here, because the language may not have a concept of static storage lifetime, or it may not store strings as zero-terminated UTF-8 bytes as C code would expect. This can cause memory leaks. -Instead, duplicate the string before returning it, and use transfer-full. +Instead, duplicate the string before returning it, and use transfer-full. This +recommendation applies to any data type with an ownership, including boxed and +object types. |