Re: [gobject-introspection] How to use caller-allocates and allow-none annotations in Clutter

[Simon McVittie <simon mcvittie collabora co uk>]

[I am not a g-i developer, please do not take this as authoritative.]

On 07/01/13 13:22, Kouhei Sutou wrote:
>   ClutterActorIter iter;
>   ClutterActor *child;
> 
>   clutter_actor_iter_init (&iter, container);
>   while (clutter_actor_iter_next (&iter, &child))
>     {
>       /* do something with child */
>     }
[...]
>
> The "child" parameter is a return location and the return
> location is allocated by caller. (The returned object isn't
> allocated by caller.)
> 
> What annotation should be used for the case?  I thought
> "out caller-allocates". Is it right usage for the
> annotation? Or "out" is the right annotation?

To me this looks like an ordinary (out), the same case as each of the
two "outputs" of g_hash_table_iter_next(). (out caller-allocates) is
rare: as I understand it, you'd use it in this situation:

    GValue value = { 0 };

    this_value_argument_is_out_caller_allocates (&value);
    ...
    g_value_unset (&value);

and not many others.

> The "child" parameter can be NULL. What annotation should be
> used for the case? I thought "allow-none". Is it right usage
> for the annotation? Can I use "allow-none" for an out
> parameter?

I believe (out) (allow-none) means "it is safe to pass NULL instead of
&child, if you just want to look at the boolean return", rather than "if
you pass &child, that might result in child == NULL afterwards".

>   match_start:
>     return location for start of match, or
>     NULL. [out caller-allocates][allow-none]

I believe this means you call it like this:

    GtkTextIter start;

    if (gtk_text_iter_forward_search (..., &start, ...))
      {
        printf ("match starts at %d\n",
                gtk_text_iter_get_offset (&start));
      }

or perhaps like this if you need to use the heap for start for whatever
reason (I'm not sure about this usage, some details might be wrong):

    GtkTextIter *start = g_new0 (GtkTextIter);

    if (gtk_text_iter_forward_search (..., start, ...))
      {
        printf ("match starts at %d\n",
                gtk_text_iter_get_offset (start));
      }

    g_free (start);

> Is clutter_actor_iter_next() case the same case as
> gtk_text_iter_forward_search()?

No, I think it's the same case as g_hash_table_iter_next().

    S