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

[Kouhei Sutou <kou cozmixng org>]

Hi,

In <50EAD835 5070101 collabora co uk>
  "Re: [gobject-introspection] How to use caller-allocates and allow-none annotations in Clutter" on Mon, 07 Jan 2013 14:14:13 +0000,
  Simon McVittie <simon mcvittie collabora co uk> wrote:

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

Thanks for your reply.
I am still waiting for a g-i developer but your reply is
very helpful for me.

I may misunderstand (out caller-allocates).
My understanding about (out) (allow-none) will be right.

Thanks!
--
kou

> 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
> _______________________________________________
> gtk-devel-list mailing list
> gtk-devel-list gnome org
> https://mail.gnome.org/mailman/listinfo/gtk-devel-list