From 2698fcf7c8eec872047de205ce643885550edfee Mon Sep 17 00:00:00 2001 From: Philip Chimento Date: Sat, 4 Mar 2023 12:19:50 -0800 Subject: docs: Advice on transfer-none return values APIs such as the Gio.AppInfo.get_id vfunc which contravene this advice, can cause memory leaks. (See https://gitlab.gnome.org/GNOME/gjs/-/issues/519) Document it here so that it hopefully happens less often in the future. --- docs/website/writingbindableapis.rst | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/website/writingbindableapis.rst b/docs/website/writingbindableapis.rst index d74a3de8..ca790bee 100644 --- a/docs/website/writingbindableapis.rst +++ b/docs/website/writingbindableapis.rst @@ -224,3 +224,29 @@ That is, don't do this: Instead, put initialization code in the ``foo_bar_init()`` function or the ``foo_bar_constructed()`` virtual function. + + +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 +you assume about storage lifetime in C may not apply in other languages. + +For example, + +.. code-block:: c + + typedef struct { + GTypeInterface iface; + + const char * (*my_vfunc) (FooBaz *self); /* Don't do this! */ + char * (*my_better_vfunc) (FooBaz *self); /* Do this instead! */ + } FooBazIface; + +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. -- cgit v1.2.1