1devel(3) User Contributed Perl Documentation devel(3)
2
6 Glib::devel - Binding developer's overview of Glib's internals
7
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 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 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 In various places, we use the name GPerl to refer to the actual binding
28 subsystem.
29 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 com‐
32 mented, and should be considered the canonical source of correct API
33 information.
34
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 lib‐
38 gobject, which provides an inheritance-based type system and other
39 spiffy things.
40 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 In the grand scheme, the bindings have been designed with a few basic
45 tenets in mind:
46 - Stick close to the C API, to allow a perl developer to use knowl‐
48 edge from the C API and API reference docs with the perl bindings;
49 this is overruled in some places by the remaining tenets.
50 - Be perlish. This is the most important. The user of the perl
52 bindings should not have to worry about memory management, refer‐
53 ence counting, freeing objects, and all that stuff, else he might
54 as well go write in C instead.
55 - Leave out deprecated functionality.
57 - Don't add new functionality. The exceptions to this rule are con‐
59 solidation of methods where default parameters may be used, or
60 where the direct analog from C is not practical.
61 - 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 - Be extensible. Export header files and typemaps so that other mod‐
67 ules can easily chain off of our base. Do not require the entirely
68 of Gtk2 for someone who needs only to build atop GObject.
69
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 The Glib module takes care of all the basic types handled by the GOb‐
78 ject library --- GEnum, GFlags, GBoxed, GObject, GValue, GClosure ---
79 as well has signal marshalling and such in GSignal. I'll discuss each
80 of these separately.
81 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 pre‐
84 processor to provide easier-to-remember names that follow the perl API
85 style, e.g., newSVGObject(obj) rather than gperl_new_object(type,obj)
86 and SvGObject(sv) instead of gperl_get_gobject(type, sv). The conven‐
87 tion used in all of gtk2-perl is described in Gtk2::devel.
88 Wrappers
90 FIXME maybe this section should be rolled into the GBoxed and GObject
92 sections?
93 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 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 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 wrap‐
113 per; in fact, we use a blessed hash reference with the pointer to the C
114 object tucked away in attached magic, and a pointer to the SV stored in
115 the GObject's user data. The combined perl/C object does some nifty
116 reference-count borrowing to ensure that object lifetime is managed
117 correctly.
118 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 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 GType to Package Mappings
130 GType is the GObject library's unique type identifier; this is a run‐
132 time variable, because GLib types may be loaded dynamically. The
133 direct analog in perl is the package name, which uniquely specifies an
134 object's class. Since these do about the same thing, we completely
135 replace the GType with the perl package.
136 For various reasons, mostly to do with robustness and performance,
138 there is a one-to-one mapping between GType classes and perl package
139 names. These must be registered, usually as part of the module ini‐
140 tialization process.
141 In addition, the type system tries as hard as it can to recover when
143 things don't go well, using the GType system to its advantage. If you
144 return a C object of a type that is not registered with Gperl, such as
145 MyCustomTypeFoo, gperl_new_object (see below) will warn you that it has
146 blessed the unknown MyCustomTypeFoo into the first known package in its
147 ancestry, Gtk2::VBox.
148 GBoxed and GObject have distinct mapping registries to avoid cross-pol‐
150 lination and mistakes in the type system. See below.
151 To assist in handling inheritance that isn't specified directly by the
153 GType system, the function gperl_set_isa allows you to add elements to
154 the @ISA for a package. gperl_register_object does this for you, but
155 you may need to add additional parents, e.g., for implementing GInter‐
156 faces. (see Gtk2/xs/GtkEntry.xs for an example)
157 You may be thinking that we could use substitution rules to map the
159 GObject classes to perl packages. In practice, this is a bad idea,
160 fraught with problems; the substitution rules are not easily extendable
161 and are easily broken by extension packages which don't follow the nam‐
162 ing conventions.
163 GEnums and GFlags
165 GLib provides a mechanism for creating runtime type information about
167 enumeration and flag types. Enumerations are lists of specific values,
168 one of which may be used at at time, whereas multiple flag values may
169 be supplied at a time. In C flags are meant to be used with bitfields.
170 A GType is associated with the various valid values for a given GEnum
171 or GFlags type as strings, in both full-name and nickname forms.
172 GPerl uses this mechanism to avoid the need to know integer values for
174 enum and flag types at the perl level. An enum value is just a string;
175 a bitfield of flag values is represented as a reference to an array of
176 strings. These strings are the GLib-provided nicknames. For the con‐
177 venience of a perl developer, the bindings treat '-' and '_' as equiva‐
178 lent when looking up the corresponding integer values during conver‐
179 sion.
180 A GEnum or GFlags type mapping should be registered with
182 void gperl_register_fundamental (GType gtype, const char * package);
184 so that their package names can be used where a GType is required (for
186 example, as GObject property types or GtkTreeModel column types).
187 The basic functions for converting between C and perl values are
189 /* croak if val is not part of type, otherwise return
191 * corresponding value. this is the general case. */
192 gint gperl_convert_enum (GType type, SV * val);
193 /* return a scalar which is the nickname of the enum value
195 * val, or croak if val is not a member of the enum. */
196 SV * gperl_convert_back_enum (GType type, gint val);
197 /* collapse a list of strings to an integer with all the
199 * correct bits set, croak if anything is invalid. */
200 gint gperl_convert_flags (GType type, SV * val);
201 /* convert a bitfield to a list of strings, or croak. */
203 SV * gperl_convert_back_flags (GType type, gint val);
204 Other utility functions allow for finer-grained control, such as the
206 ability to pass unknown values, which can be necessary in special
207 cases. In general, each of these functions raises an exception when
208 something goes wrong. To be helpful, they croak with a message listing
209 the valid values when they encounter invalid input.
210 GBoxed
212 GBoxed provides a way to register functions that create, copy, and
214 destroy opaque structures. For our purposes, we'll allow any perl
215 package to inherit from Glib::Boxed and implement accessors for the
216 struct members, but Glib::Boxed will handle the object and wrapper
217 lifetime issues.
218 There are two functions for creating boxed wrappers:
220 SV * gperl_new_boxed (gpointer boxed, GType gtype, gboolean own);
222 SV * gperl_new_boxed_copy (gpointer boxed, GType gtype);
223 If own is TRUE, the wrapper returned by gperl_new_boxed will take boxed
225 with it when it dies. In the case of a copy, own is implied, so
226 there's a separate function which doesn't need the own option.
227 To get a boxed pointer out of a scalar wrapper, you just call
229 gperl_get_boxed_check --- this will croak if the sv is undef or not
230 blessed into the specified package.
231 When you register a boxed type you get the option of supplying a table
233 of function pointers describing how the boxed object should be wrapped,
234 unwrapped, and destroyed. This allows you to decide in the wrapping
235 function what subclass of the boxed type's class the wrapper should
236 actually take (a trick used by Gtk2::Gdk::Event), or represent a boxed
237 type as a native perl type (such as using array references for
238 Gnome2::Canvas::Point objects). All of this happens automagically,
239 behind the scenes, and most types assume the default wrapper class.
240 See the commentary in gperl.h for more information.
242 GObject
244 The GObject knows its own type. Thus, we need only one parameter to
246 create a GObject wrapper. In reality, we ask for two:
247 SV * gperl_new_object (GObject * object, gboolean own);
249 The wrapper SV will be blessed into the package corresponding to the
251 gtype returned by G_OBJECT_TYPE (object), that is, the bottommost type
252 in the inheritance chain. If that bottommost type is not known, the
253 function walks back up the tree until it finds one that's known,
254 blesses the reference into that package, and spits out a warning on
255 stderr. To hush the warning, you need merely call
256 In general, this process will claim a reference on the GObject (with
258 g_object_ref()), so that the C object stays alive so long as there is a
259 perl wrapper for it. If <i>own</i> is set to TRUE, the perl wrapper
260 will claim ownership of the C object by removing that reference; in
261 theory, for a new GObject, fresh from a constructor, this leaves the
262 object with a single reference owned by the perl object. The next
263 question out of your mouth should be, "But what about GObject deriva‐
264 tives that require sinking or other strange methods to claim owner‐
265 ship?" For the answer, see the GtkObject section's description of sink
266 functions.
267 void gperl_register_object (GType gtype, const char * package);
269 This magical function also sets up the @ISA for the package to point to
271 the package corresponding to g_type_parent (gtype). [Since this
272 requires the parent package to be registered, there is a simple defer‐
273 ral mechanism, which means your @ISA might not be set until the next
274 call to gperl_register_object.]
275 There are two ways to get an object out of an SV (though I think only
277 one is really needed):
278 GObject * gperl_get_object (SV * sv);
280 GObject * gperl_get_object_check (SV * sv, GType gtype);
281 The second one is like the first, but croaks if the object is not
283 derived from gtype.
284 You can get and set object data and object parameters just like you'd
286 expect.
287 GSignal
289 All of this GObject stuff wouldn't be very useful if you couldn't con‐
291 nect signals and closures. I got most of my handling code from
292 gtk2-perl and pygtk, and it's pretty straightforward. The data member
293 is optional, and must be a scalar.
294 To connect perl subroutines to GSignals I use GClosures, which require
296 the handling of GValues.
297 GPerlClosure
299 Use a GPerlClosure wherever you could use a GClosure and things should
301 work out great. FIXME say more here
302 GPerlCallback
304 Function pointers are required in many places throughout gtk+, usually
306 for a callback to be used as a "foreach" function or for some other
307 purpose. Unfortunately, a majority of these spots aren't designed to
308 work with GClosures (usually by lacking a way to destroy data associ‐
309 ated with the callback when it is no longer needed). For this purpose,
310 the GPerlCallback wraps up the gruntwork of using perl's call_sv to use
311 a callback function directly.
312
314 perl(1), perlxs(1), perlguts(1), perlapi(1), perlxstut(1), ExtU‐
315 tils::Depends(3pm), ExtUtils::PkgConfig(3pm) Glib(3pm),
316 Glib::Object::Subclass(3pm), Glib::xsapi(3pm)
317
319 muppet <scott at asofyet.org>
320
322 Copyright (C) 2003 by the gtk2-perl team (see the file AUTHORS for the
323 full list)
324 This library is free software; you can redistribute it and/or modify it
326 under the terms of the GNU Library General Public License as published
327 by the Free Software Foundation; either version 2.1 of the License, or
328 (at your option) any later version.
329 This library is distributed in the hope that it will be useful, but
331 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
332 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library
333 General Public License for more details.
334 You should have received a copy of the GNU Library General Public
336 License along with this library; if not, write to the Free Software
337 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307
338 USA.
339perl v5.8.8 2007-02-26 devel(3)