I’m creating a GObject and have a doubt about how to return another object from a method. Currently, this object, when calling a method, launches a process using GSubprocessLauncher, waits asynchronously for its termination in the returned GSubprocess to be able to clean some things in that case (so it keeps a reference to that object), but also returns that GSubprocess to the programmer, to allow to, externally, do anything the programmer need with it.
My question is: should I annotate it as “transfer: full”, or “transfer: none”? Currently I’m using “transfer:full”, because that is what I understand I have to use since GSubprocess is a reference counted object, but I’m not fully sure.
The transfer annotation describes who owns the arguments or return values. It’s not a matter of what type you’re using, but how the ownership of the argument or return value can be described to callers, and, in essence, how you expect the memory management of those types to work.
Ignoring the container annotation, which does not apply in your case, you have two options:
none means that the ownership is not transfered; in other words: the return value is owned by the callee—the function owns the return value and is responsible for releasing its resources. An example is gtk_entry_get_buffer(): the returned GtkEntryBuffer instance is owned by the GtkEntry instance, and the getter function merely returns a pointer to it. The ownership of the GtkEntryBuffer is not transferred from the callee to the caller.
full is the opposite of none: the ownership of the returned value is transferred from the callee to the caller. A typical case is a singleton constructor that caches its result, but returns a new reference with every invocation, like g_resolver_get_default().
If you’re returning a real reference to a GSubprocess and thus you expect the caller to call g_object_unref() on it once they are done, you should use transfer full; if you’re returning a simple pointer to a GSubprocess and thus you expect the caller to never call g_object_unref() on it, then use transfer none.
You can check the documentation for the introspection annotations.