"transfer none" semantics for parameters

Platform
1

When a reference counted object parameter has"transfer none" annotation, does it imply that the callee should not refcount the object ?

2

It depends.

If the argument’s direction is “in”, then it means that the ownership of the instance will not be transferred from the caller to the callee: the caller still owns the object, and if the callee wishes to have its own ownership, then it will need to acquire a reference.

If the argument’s direction is “out”, then it means the callee maintains the ownership of the instance, and the caller will need to acquire its own reference if it wants to have its own ownership.

1 Like
3

Perhaps more accurate to say “If the argument’s direction is “in”, then it means that the ownership of one of the counted references will not be transferred…”

4

That was my next question.

E.g.

Let us consider 2 object types A and B, and object D ( the refcounted data object )

  1. Object A creates object D. It is supposed to be the owner as per documentation and now it is.
  2. Object A passes object D to a function in object B ( with ‘transfer none’ parameter semantics )
  3. Object B does a “g_object_ref (D)” in the function.
  4. Object A goes out of existence few seconds later and calls “g_object_unref (D)” in its finalize function.
  5. Object D is still alive through its reference held by object B.

Assuming that object B will be finalized when the program exits, object D will live till the program exits.

Now from above it appears that object B is more an owner of object D than object A, though the documentation claims that object A is the owner of object D.

What exactly do we mean by ownership in cases like this ?

5

For a ref-counted object, you own a counted reference, not the object. Possibly documentation talks about owning an object for brevity instead saying owning a counted reference of an object.

Similarly when the documentation talks about an object having a floating reference, it means that one of the counted references is floating, i.e. unowned. Therefore, for a returned object, (transfer none) does not necessarily mean that a callee maintains ownership of (a counted reference to) the returned object because the returned object could have a single floating reference, i.e. the only counted reference is unowned. (I don’t think it is customary for an argument whose direction is ‘out’ to pass out an object with a floating reference but I guess it is possible.)

1 Like
6

Maybe, we should add the following content to https://gi.readthedocs.io/en/latest/annotations/giannotations.html

  1. Content discussed in this topic.
  2. Content discussed in About "transfer" in GObject Introspection

I feel the "transfer" annotation content is too thin currently.

7

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.