Ubuntu Manpage: Glib::devel - Binding developer's overview of Glib's internals

Provided by: libglib-perl_1.326-1build1_amd64

NAME

       Glib::devel - Binding developer's overview of Glib's internals

DESCRIPTION

       Do you need to know how the gtk2-perl language bindings work, or need to write your own
       language bindings for a Glib/Gtk2-based library?  Then you've come to the right place.  If
       you are just a perl developer wanting to write programs with Glib or Gtk2, then this is
       probably way over your head.

       This document began its life as a post to gtk-perl-list about a redesign of the
       fundamentals of the bindings; today it is the reference documentation for the developers
       of the bindings.

       To reduce confusion, refer to GLib, the C library, with a capital L, and Glib the perl
       module with a lower-case l.  While the Gtk2 module is the primary client of Glib, it is
       not necessarily the only one; in fact, the perl bindings for the GStreamer library build
       directly atop Glib.  Therefore, this document describes just the GLib/Glib basics.  For
       details on how Gtk2 extends upon the concepts presented here, see Gtk2::devel.

       In various places, we use the name GPerl to refer to the actual binding subsystem.

       In order to avoid getting very quickly out of date, this document doesn't go into great
       detail on APIs.  gperl.h is rather heavily commented, and should be considered the
       canonical source of correct API information.

Basic Philosophy

GLib is a portability library for C programs, providing a common set of APIs and services
on various platforms. Along with that you get libgobject, which provides an inheritance-
based type system and other spiffy things.

Glib, as a perl module, must decide which portions of GLib's facilities to map to perl and
which to abstract and encapsulate.

In the grand scheme, the bindings have been designed with a few basic tenets in mind:

- Stick close to the C API, to allow a perl developer to use knowledge from the C API
and API reference docs with the perl bindings; this is overruled in some places by the
remaining tenets.

- Be perlish. This is the most important. The user of the perl bindings should not
have to worry about memory management, reference counting, freeing objects, and all
that stuff, else he might as well go write in C instead.

- Leave out deprecated functionality.

- Don't add new functionality. The exceptions to this rule are consolidation of methods
where default parameters may be used, or where the direct analog from C is not
practical.

- Be lightweight. As little indirection and bloat as possible. If possible, implement
each toplevel module (e.g., Glib, Gtk2, Gnome2, GtkHTML, etc) as one .pm and one .so.

- Be extensible. Export header files and typemaps so that other modules can easily
chain off of our base. Do not require the entirely of Gtk2 for someone who needs only
to build atop GObject.

The Glib Module

       In keeping with the tenet of not requiring the entire car for someone who only needs a
       single wheel, I broke the glib/gobject library family into its own module and namespace.
       This has proved to be a godsend, as it has made things very easy to debug; there's a clean
       separation between the base of the type system and the stuff on top of it.

       The Glib module takes care of all the basic types handled by the GObject library ---
       GEnum, GFlags, GBoxed, GObject, GValue, GClosure --- as well has signal marshalling and
       such in GSignal.  I'll discuss each of these separately.

       In practice, you will rarely see direct calls to the functions that convert objects in and
       out of perl.  Most code should use the C preprocessor to provide easier-to-remember names
       that follow the perl API style, e.g., newSVGObject(obj) rather than
       gperl_new_object(type,obj) and SvGObject(sv) instead of gperl_get_gobject(type, sv).  The
       convention used in all of gtk2-perl is described in Gtk2::devel.

   Wrappers
       FIXME maybe this section should be rolled into the GBoxed and GObject sections?

       In order to use the C data structures from Perl, we need to wrap those objects up in Perl
       objects.  In general, a Perl object is simply a blessed reference.  A typical scheme for
       representing C objects in perl is bless a reference to a scalar holding the C pointer
       value; perl will destroy the reference-counted scalar when there are no more references to
       it, and one would normally destroy the underlying data structure at this point.  However,
       GLib is a little more complex than your typical C library, so this easy, typical setup
       won't work for us.

       GBoxed types are opaque wrappers for C structures, providing copy and free functions, to
       allow the types to be used generically.  For the most part we can get away with using the
       typical scheme described above to provide an opaque object, but in some instances an
       opaque object is very alien in perl.  The Glib::Boxed section explains how we get around
       this.

       GObject, on the other hand, is a type-aware, reference-counted object with lifetime
       semantics that differ somewhat from perl SVs.  Thus we need something a bit more
       sophisticated than a plain old opaque wrapper; in fact, we use a blessed hash reference
       with the pointer to the C object tucked away in attached magic, and a pointer to the SV
       stored in the GObject's user data.  The combined perl/C object does some nifty reference-
       count borrowing to ensure that object lifetime is managed correctly.

       If an object is created by a function that returns directly to perl, then the wrapper
       returned by that function should "own" the object.  If no other code assumes ownership of
       that object (by ref'ing a GObject or copying a GBoxed), then the object should be
       destroyed when the perl scalar is destroyed (actually, as part of its destruction).

       If a function returns a preexisting object owned by someone else, then the bindings should
       NOT destroy the object with the perl wrapper.  How we handle this for the various types is
       described below.

   GType to Package Mappings
       GType is the GObject library's unique type identifier; this is a runtime variable, because
       GLib types may be loaded dynamically.  The direct analog in perl is the package name,
       which uniquely specifies an object's class.  Since these do about the same thing, we
       completely replace the GType with the perl package.

       For various reasons, mostly to do with robustness and performance, there is a one-to-one
       mapping between GType classes and perl package names.  These must be registered, usually
       as part of the module initialization process.

       In addition, the type system tries as hard as it can to recover when things don't go well,
       using the GType system to its advantage.  If you return a C object of a type that is not
       registered with Gperl, such as MyCustomTypeFoo, gperl_new_object (see below) will warn you
       that it has blessed the unknown MyCustomTypeFoo into the first known package in its
       ancestry, Gtk2::VBox.

       GBoxed and GObject have distinct mapping registries to avoid cross-pollination and
       mistakes in the type system.  See below.

       To assist in handling inheritance that isn't specified directly by the GType system, the
       function gperl_set_isa allows you to add elements to the @ISA for a package.
       gperl_register_object does this for you, but you may need to add additional parents, e.g.,
       for implementing GInterfaces.  (see Gtk2/xs/GtkEntry.xs for an example)

       You may be thinking that we could use substitution rules to map the GObject classes to
       perl packages. In practice, this is a bad idea, fraught with problems; the substitution
       rules are not easily extendable and are easily broken by extension packages which don't
       follow the naming conventions.

   GEnums and GFlags
       GLib provides a mechanism for creating runtime type information about enumeration and flag
       types.  Enumerations are lists of specific values, one of which may be used at at time,
       whereas multiple flag values may be supplied at a time.  In C flags are meant to be used
       with bitfields.  A GType is associated with the various valid values for a given GEnum or
       GFlags type as strings, in both full-name and nickname forms.

       GPerl uses this mechanism to avoid the need to know integer values for enum and flag types
       at the perl level.  An enum value is just a string; a bitfield of flag values is
       represented as a reference to an array of strings.  These strings are the GLib-provided
       nicknames.  For the convenience of a perl developer, the bindings treat '-' and '_' as
       equivalent when looking up the corresponding integer values during conversion.

       A GEnum or GFlags type mapping should be registered with

        void gperl_register_fundamental (GType gtype, const char * package);

       so that their package names can be used where a GType is required (for example, as GObject
       property types or GtkTreeModel column types).

       The basic functions for converting between C and perl values are

        /* croak if val is not part of type, otherwise return
         * corresponding value.  this is the general case. */
        gint gperl_convert_enum (GType type, SV * val);

        /* return a scalar which is the nickname of the enum value
         * val, or croak if val is not a member of the enum. */
        SV * gperl_convert_back_enum (GType type, gint val);

        /* collapse a list of strings to an integer with all the
         * correct bits set, croak if anything is invalid. */
        gint gperl_convert_flags (GType type, SV * val);

        /* convert a bitfield to a list of strings, or croak. */
        SV * gperl_convert_back_flags (GType type, gint val);

       Other utility functions allow for finer-grained control, such as the ability to pass
       unknown values, which can be necessary in special cases.  In general, each of these
       functions raises an exception when something goes wrong.  To be helpful, they croak with a
       message listing the valid values when they encounter invalid input.

   GBoxed
       GBoxed provides a way to register functions that create, copy, and destroy opaque
       structures.  For our purposes, we'll allow any perl package to inherit from Glib::Boxed
       and implement accessors for the struct members, but Glib::Boxed will handle the object and
       wrapper lifetime issues.

       There are two functions for creating boxed wrappers:

        SV * gperl_new_boxed (gpointer boxed, GType gtype, gboolean own);
        SV * gperl_new_boxed_copy (gpointer boxed, GType gtype);

       If own is TRUE, the wrapper returned by gperl_new_boxed will take boxed with it when it
       dies.  In the case of a copy, own is implied, so there's a separate function which doesn't
       need the own option.

       To get a boxed pointer out of a scalar wrapper, you just call gperl_get_boxed_check ---
       this will croak if the sv is undef or not blessed into the specified package.

       When you register a boxed type you get the option of supplying a table of function
       pointers describing how the boxed object should be wrapped, unwrapped, and destroyed.
       This allows you to decide in the wrapping function what subclass of the boxed type's class
       the wrapper should actually take (a trick used by Gtk2::Gdk::Event), or represent a boxed
       type as a native perl type (such as using array references for Gnome2::Canvas::Point
       objects).  All of this happens automagically, behind the scenes, and most types assume the
       default wrapper class.

       See the commentary in gperl.h for more information.

   GObject
       The GObject knows its own type.  Thus, we need only one parameter to create a GObject
       wrapper.  In reality, we ask for two:

        SV * gperl_new_object (GObject * object, gboolean own);

       The wrapper SV will be blessed into the package corresponding to the gtype returned by
       G_OBJECT_TYPE (object), that is, the bottommost type in the inheritance chain.  If that
       bottommost type is not known, the function walks back up the tree until it finds one
       that's known, blesses the reference into that package, and spits out a warning on stderr.
       To hush the warning, you need merely call

       In general, this process will claim a reference on the GObject (with g_object_ref()), so
       that the C object stays alive so long as there is a perl wrapper for it.  If <i>own</i> is
       set to TRUE, the perl wrapper will claim ownership of the C object by removing that
       reference; in theory, for a new GObject, fresh from a constructor, this leaves the object
       with a single reference owned by the perl object.  The next question out of your mouth
       should be, "But what about GObject derivatives that require sinking or other strange
       methods to claim ownership?"  For the answer, see the GtkObject section's description of
       sink functions.

        void gperl_register_object (GType gtype, const char * package);

       This magical function also sets up the @ISA for the package to point to the package
       corresponding to g_type_parent (gtype).  [Since this requires the parent package to be
       registered, there is a simple deferral mechanism, which means your @ISA might not be set
       until the next call to gperl_register_object.]

       There are two ways to get an object out of an SV (though I think only one is really
       needed):

        GObject * gperl_get_object (SV * sv);
        GObject * gperl_get_object_check (SV * sv, GType gtype);

       The second one is like the first, but croaks if the object is not derived from gtype.

       You can get and set object data and object parameters just like you'd expect.

   GSignal
       All of this GObject stuff wouldn't be very useful if you couldn't connect signals and
       closures.  I got most of my handling code from gtk2-perl and pygtk, and it's pretty
       straightforward.  The data member is optional, and must be a scalar.

       To connect perl subroutines to GSignals I use GClosures, which require the handling of
       GValues.

   GPerlClosure
       Use a GPerlClosure wherever you could use a GClosure and things should work out great.
       FIXME say more here

   GPerlCallback
       Function pointers are required in many places throughout gtk+, usually for a callback to
       be used as a "foreach" function or for some other purpose.  Unfortunately, a majority of
       these spots aren't designed to work with GClosures (usually by lacking a way to destroy
       data associated with the callback when it is no longer needed).  For this purpose, the
       GPerlCallback wraps up the gruntwork of using perl's call_sv to use a callback function
       directly.

AUTHOR

       muppet <scott at asofyet.org>

COPYRIGHT