[perl-Glib] Glib::Object::Subclass: document complications with boxed types

[Torsten Schönfeld <tsch src gnome org>]

commit 94a013f77cf5f7e2d14d836fd25fd4370cff3182
Author: Kevin Ryde <user42 zip com au>
Date:   Thu Nov 25 09:44:05 2010 +1100

    Glib::Object::Subclass: document complications with boxed types
    
    Explain that non-reference-counted boxed types need special treatment in
    GET_PROPERTY/SET_PROPERTY implementations.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=635733

 lib/Glib/Object/Subclass.pm |    8 ++++++++
 1 files changed, 8 insertions(+), 0 deletions(-)
---
diff --git a/lib/Glib/Object/Subclass.pm b/lib/Glib/Object/Subclass.pm
index 50ab8c4..80a48f5 100644
--- a/lib/Glib/Object/Subclass.pm
+++ b/lib/Glib/Object/Subclass.pm
@@ -179,6 +179,14 @@ a property changes, like redraw or resize a widget.  Eg.
      }
    }
 
+Care must be taken with boxed non-reference-counted types such as
+C<Gtk2::Gdk::Color>.  In C<SET_PROPERTY> the C<$newval> is generally good
+only for the duration of the call.  Use C<copy> or similar if keeping it
+longer (see L<Glib::Boxed>).  In C<GET_PROPERTY> the returned memory must
+last long enough to reach the caller, which generally means returning a
+field, not a newly created object (which is destroyed with the scalar
+holding it).
+
 C<GET_PROPERTY> is different from a C get_property method in that the
 perl method returns the retrieved value. For symmetry, the C<$newval>
 and C<$pspec> args on C<SET_PROPERTY> are swapped from the C usage.