1devel(3)              User Contributed Perl Documentation             devel(3)
2
3
4

NAME

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

DESCRIPTION

9       Do you need to know how the gtk2-perl language bindings work, or need
10       to write your own language bindings for a Glib/Gtk2-based library?
11       Then you've come to the right place.  If you are just a perl developer
12       wanting to write programs with Glib or Gtk2, then this is probably way
13       over your head.
14
15       This document began its life as a post to gtk-perl-list about a
16       redesign of the fundamentals of the bindings; today it is the reference
17       documentation for the developers of the bindings.
18
19       To reduce confusion, refer to GLib, the C library, with a capital L,
20       and Glib the perl module with a lower-case l.  While the Gtk2 module is
21       the primary client of Glib, it is not necessarily the only one; in
22       fact, the perl bindings for the GStreamer library build directly atop
23       Glib.  Therefore, this document describes just the GLib/Glib basics.
24       For details on how Gtk2 extends upon the concepts presented here, see
25       Gtk2::devel.
26
27       In various places, we use the name GPerl to refer to the actual binding
28       subsystem.
29
30       In order to avoid getting very quickly out of date, this document
31       doesn't go into great detail on APIs.  gperl.h is rather heavily
32       commented, and should be considered the canonical source of correct API
33       information.
34

Basic Philosophy

36       GLib is a portability library for C programs, providing a common set of
37       APIs and services on various platforms.  Along with that you get
38       libgobject, which provides an inheritance-based type system and other
39       spiffy things.
40
41       Glib, as a perl module, must decide which portions of GLib's facilities
42       to map to perl and which to abstract and encapsulate.
43
44       In the grand scheme, the bindings have been designed with a few basic
45       tenets in mind:
46
47       -   Stick close to the C API, to allow a perl developer to use
48           knowledge from the C API and API reference docs with the perl
49           bindings; this is overruled in some places by the remaining tenets.
50
51       -   Be perlish.  This is the most important.  The user of the perl
52           bindings should not have to worry about memory management,
53           reference counting, freeing objects, and all that stuff, else he
54           might as well go write in C instead.
55
56       -   Leave out deprecated functionality.
57
58       -   Don't add new functionality.  The exceptions to this rule are
59           consolidation of methods where default parameters may be used, or
60           where the direct analog from C is not practical.
61
62       -   Be lightweight.  As little indirection and bloat as possible.  If
63           possible, implement each toplevel module (e.g., Glib, Gtk2, Gnome2,
64           GtkHTML, etc) as one .pm and one .so.
65
66       -   Be extensible.  Export header files and typemaps so that other
67           modules can easily chain off of our base.  Do not require the
68           entirely of Gtk2 for someone who needs only to build atop GObject.
69

The Glib Module

71       In keeping with the tenet of not requiring the entire car for someone
72       who only needs a single wheel, I broke the glib/gobject library family
73       into its own module and namespace.  This has proved to be a godsend, as
74       it has made things very easy to debug; there's a clean separation
75       between the base of the type system and the stuff on top of it.
76
77       The Glib module takes care of all the basic types handled by the
78       GObject library --- GEnum, GFlags, GBoxed, GObject, GValue, GClosure
79       --- as well has signal marshalling and such in GSignal.  I'll discuss
80       each of these separately.
81
82       In practice, you will rarely see direct calls to the functions that
83       convert objects in and out of perl.  Most code should use the C
84       preprocessor to provide easier-to-remember names that follow the perl
85       API style, e.g., newSVGObject(obj) rather than
86       gperl_new_object(type,obj) and SvGObject(sv) instead of
87       gperl_get_gobject(type, sv).  The convention used in all of gtk2-perl
88       is described in Gtk2::devel.
89
90   Wrappers
91       FIXME maybe this section should be rolled into the GBoxed and GObject
92       sections?
93
94       In order to use the C data structures from Perl, we need to wrap those
95       objects up in Perl objects.  In general, a Perl object is simply a
96       blessed reference.  A typical scheme for representing C objects in perl
97       is bless a reference to a scalar holding the C pointer value; perl will
98       destroy the reference-counted scalar when there are no more references
99       to it, and one would normally destroy the underlying data structure at
100       this point.  However, GLib is a little more complex than your typical C
101       library, so this easy, typical setup won't work for us.
102
103       GBoxed types are opaque wrappers for C structures, providing copy and
104       free functions, to allow the types to be used generically.  For the
105       most part we can get away with using the typical scheme described above
106       to provide an opaque object, but in some instances an opaque object is
107       very alien in perl.  The Glib::Boxed section explains how we get around
108       this.
109
110       GObject, on the other hand, is a type-aware, reference-counted object
111       with lifetime semantics that differ somewhat from perl SVs.  Thus we
112       need something a bit more sophisticated than a plain old opaque
113       wrapper; in fact, we use a blessed hash reference with the pointer to
114       the C object tucked away in attached magic, and a pointer to the SV
115       stored in the GObject's user data.  The combined perl/C object does
116       some nifty reference-count borrowing to ensure that object lifetime is
117       managed correctly.
118
119       If an object is created by a function that returns directly to perl,
120       then the wrapper returned by that function should "own" the object.  If
121       no other code assumes ownership of that object (by ref'ing a GObject or
122       copying a GBoxed), then the object should be destroyed when the perl
123       scalar is destroyed (actually, as part of its destruction).
124
125       If a function returns a preexisting object owned by someone else, then
126       the bindings should NOT destroy the object with the perl wrapper.  How
127       we handle this for the various types is described below.
128
129   GType to Package Mappings
130       GType is the GObject library's unique type identifier; this is a
131       runtime variable, because GLib types may be loaded dynamically.  The
132       direct analog in perl is the package name, which uniquely specifies an
133       object's class.  Since these do about the same thing, we completely
134       replace the GType with the perl package.
135
136       For various reasons, mostly to do with robustness and performance,
137       there is a one-to-one mapping between GType classes and perl package
138       names.  These must be registered, usually as part of the module
139       initialization process.
140
141       In addition, the type system tries as hard as it can to recover when
142       things don't go well, using the GType system to its advantage.  If you
143       return a C object of a type that is not registered with Gperl, such as
144       MyCustomTypeFoo, gperl_new_object (see below) will warn you that it has
145       blessed the unknown MyCustomTypeFoo into the first known package in its
146       ancestry, Gtk2::VBox.
147
148       GBoxed and GObject have distinct mapping registries to avoid cross-
149       pollination and mistakes in the type system.  See below.
150
151       To assist in handling inheritance that isn't specified directly by the
152       GType system, the function gperl_set_isa allows you to add elements to
153       the @ISA for a package.  gperl_register_object does this for you, but
154       you may need to add additional parents, e.g., for implementing
155       GInterfaces.  (see Gtk2/xs/GtkEntry.xs for an example)
156
157       You may be thinking that we could use substitution rules to map the
158       GObject classes to perl packages. In practice, this is a bad idea,
159       fraught with problems; the substitution rules are not easily extendable
160       and are easily broken by extension packages which don't follow the
161       naming conventions.
162
163   GEnums and GFlags
164       GLib provides a mechanism for creating runtime type information about
165       enumeration and flag types.  Enumerations are lists of specific values,
166       one of which may be used at at time, whereas multiple flag values may
167       be supplied at a time.  In C flags are meant to be used with bitfields.
168       A GType is associated with the various valid values for a given GEnum
169       or GFlags type as strings, in both full-name and nickname forms.
170
171       GPerl uses this mechanism to avoid the need to know integer values for
172       enum and flag types at the perl level.  An enum value is just a string;
173       a bitfield of flag values is represented as a reference to an array of
174       strings.  These strings are the GLib-provided nicknames.  For the
175       convenience of a perl developer, the bindings treat '-' and '_' as
176       equivalent when looking up the corresponding integer values during
177       conversion.
178
179       A GEnum or GFlags type mapping should be registered with
180
181        void gperl_register_fundamental (GType gtype, const char * package);
182
183       so that their package names can be used where a GType is required (for
184       example, as GObject property types or GtkTreeModel column types).
185
186       The basic functions for converting between C and perl values are
187
188        /* croak if val is not part of type, otherwise return
189         * corresponding value.  this is the general case. */
190        gint gperl_convert_enum (GType type, SV * val);
191
192        /* return a scalar which is the nickname of the enum value
193         * val, or croak if val is not a member of the enum. */
194        SV * gperl_convert_back_enum (GType type, gint val);
195
196        /* collapse a list of strings to an integer with all the
197         * correct bits set, croak if anything is invalid. */
198        gint gperl_convert_flags (GType type, SV * val);
199
200        /* convert a bitfield to a list of strings, or croak. */
201        SV * gperl_convert_back_flags (GType type, gint val);
202
203       Other utility functions allow for finer-grained control, such as the
204       ability to pass unknown values, which can be necessary in special
205       cases.  In general, each of these functions raises an exception when
206       something goes wrong.  To be helpful, they croak with a message listing
207       the valid values when they encounter invalid input.
208
209   GBoxed
210       GBoxed provides a way to register functions that create, copy, and
211       destroy opaque structures.  For our purposes, we'll allow any perl
212       package to inherit from Glib::Boxed and implement accessors for the
213       struct members, but Glib::Boxed will handle the object and wrapper
214       lifetime issues.
215
216       There are two functions for creating boxed wrappers:
217
218        SV * gperl_new_boxed (gpointer boxed, GType gtype, gboolean own);
219        SV * gperl_new_boxed_copy (gpointer boxed, GType gtype);
220
221       If own is TRUE, the wrapper returned by gperl_new_boxed will take boxed
222       with it when it dies.  In the case of a copy, own is implied, so
223       there's a separate function which doesn't need the own option.
224
225       To get a boxed pointer out of a scalar wrapper, you just call
226       gperl_get_boxed_check --- this will croak if the sv is undef or not
227       blessed into the specified package.
228
229       When you register a boxed type you get the option of supplying a table
230       of function pointers describing how the boxed object should be wrapped,
231       unwrapped, and destroyed.  This allows you to decide in the wrapping
232       function what subclass of the boxed type's class the wrapper should
233       actually take (a trick used by Gtk2::Gdk::Event), or represent a boxed
234       type as a native perl type (such as using array references for
235       Gnome2::Canvas::Point objects).  All of this happens automagically,
236       behind the scenes, and most types assume the default wrapper class.
237
238       See the commentary in gperl.h for more information.
239
240   GObject
241       The GObject knows its own type.  Thus, we need only one parameter to
242       create a GObject wrapper.  In reality, we ask for two:
243
244        SV * gperl_new_object (GObject * object, gboolean own);
245
246       The wrapper SV will be blessed into the package corresponding to the
247       gtype returned by G_OBJECT_TYPE (object), that is, the bottommost type
248       in the inheritance chain.  If that bottommost type is not known, the
249       function walks back up the tree until it finds one that's known,
250       blesses the reference into that package, and spits out a warning on
251       stderr.  To hush the warning, you need merely call
252
253       In general, this process will claim a reference on the GObject (with
254       g_object_ref()), so that the C object stays alive so long as there is a
255       perl wrapper for it.  If <i>own</i> is set to TRUE, the perl wrapper
256       will claim ownership of the C object by removing that reference; in
257       theory, for a new GObject, fresh from a constructor, this leaves the
258       object with a single reference owned by the perl object.  The next
259       question out of your mouth should be, "But what about GObject
260       derivatives that require sinking or other strange methods to claim
261       ownership?"  For the answer, see the GtkObject section's description of
262       sink functions.
263
264        void gperl_register_object (GType gtype, const char * package);
265
266       This magical function also sets up the @ISA for the package to point to
267       the package corresponding to g_type_parent (gtype).  [Since this
268       requires the parent package to be registered, there is a simple
269       deferral mechanism, which means your @ISA might not be set until the
270       next call to gperl_register_object.]
271
272       There are two ways to get an object out of an SV (though I think only
273       one is really needed):
274
275        GObject * gperl_get_object (SV * sv);
276        GObject * gperl_get_object_check (SV * sv, GType gtype);
277
278       The second one is like the first, but croaks if the object is not
279       derived from gtype.
280
281       You can get and set object data and object parameters just like you'd
282       expect.
283
284   GSignal
285       All of this GObject stuff wouldn't be very useful if you couldn't
286       connect signals and closures.  I got most of my handling code from
287       gtk2-perl and pygtk, and it's pretty straightforward.  The data member
288       is optional, and must be a scalar.
289
290       To connect perl subroutines to GSignals I use GClosures, which require
291       the handling of GValues.
292
293   GPerlClosure
294       Use a GPerlClosure wherever you could use a GClosure and things should
295       work out great.  FIXME say more here
296
297   GPerlCallback
298       Function pointers are required in many places throughout gtk+, usually
299       for a callback to be used as a "foreach" function or for some other
300       purpose.  Unfortunately, a majority of these spots aren't designed to
301       work with GClosures (usually by lacking a way to destroy data
302       associated with the callback when it is no longer needed).  For this
303       purpose, the GPerlCallback wraps up the gruntwork of using perl's
304       call_sv to use a callback function directly.
305

SEE ALSO

307       perl(1), perlxs(1), perlguts(1), perlapi(1), perlxstut(1),
308       ExtUtils::Depends(3pm), ExtUtils::PkgConfig(3pm) Glib(3pm),
309       Glib::Object::Subclass(3pm), Glib::xsapi(3pm)
310

AUTHOR

312       muppet <scott at asofyet.org>
313
315       Copyright (C) 2003 by the gtk2-perl team (see the file AUTHORS for the
316       full list)
317
318       This library is free software; you can redistribute it and/or modify it
319       under the terms of the GNU Library General Public License as published
320       by the Free Software Foundation; either version 2.1 of the License, or
321       (at your option) any later version.
322
323       This library is distributed in the hope that it will be useful, but
324       WITHOUT ANY WARRANTY; without even the implied warranty of
325       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
326       Library General Public License for more details.
327
328       You should have received a copy of the GNU Library General Public
329       License along with this library; if not, write to the Free Software
330       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
331       02110-1301 USA.
332
333
334
335perl v5.28.0                      2012-01-06                          devel(3)
Impressum