1Glib::xsapi(3) User Contributed Perl Documentation Glib::xsapi(3)
2
6 Glib::xsapi - internal API reference for GPerl.
7
9 #include <gperl.h>
10
12 This is the binding developer's API reference for GPerl, automatically
13 generated from the xs source files. This header defines the public
14 interface for use when creating new Perl language bindings for GLib-
15 based C libraries.
16 gperl.h includes for you all the headers needed for writing XSUBs
18 (EXTERN.h, perl.h, and XSUB.h), as well as all of GLib (via
19 glib-object.h).
20
22 Miscellaneous
23 Various useful utilities defined in Glib.xs.
24 GPERL_CALL_BOOT(name)
26 call the boot code of a module by symbol rather than by name.
27 in a perl extension which uses several xs files but only one pm,
29 you need to bootstrap the other xs files in order to get their
30 functions exported to perl. if the file has MODULE = Foo::Bar, the
31 boot symbol would be boot_Foo__Bar.
32 void _gperl_call_XS (pTHX_ void (*subaddr) (pTHX_ CV *), CV * cv, SV **
34 mark);
35 never use this function directly. see "GPERL_CALL_BOOT".
36 for the curious, this calls a perl sub by function pointer rather
38 than by name; call_sv requires that the xsub already be registered,
39 but we need this to call a function which will register xsubs.
40 this is an evil hack and should not be used outside of the
41 GPERL_CALL_BOOT macro. it's implemented as a function to avoid
42 code size bloat, and exported so that extension modules can pull
43 the same trick.
44 gpointer gperl_alloc_temp (int nbytes)
46 Allocate and return a pointer to an nbytes-long, zero-initialized,
47 temporary buffer that will be reaped at the next garbage collection
48 sweep. This is handy for allocating things that need to be
49 alloc'ed before a croak (since croak doesn't return and give you
50 the chance to free them). The trick is that the memory is
51 allocated in a mortal perl scalar. See the perl online manual for
52 notes on using this technique.
53 Do not under any circumstances attempt to call g_free(), free(), or
55 any other deallocator on this pointer, or you will crash the
56 interpreter.
57 gchar *gperl_filename_from_sv (SV *sv)
59 Return a localized version of the filename in the sv, using
60 g_filename_from_utf8 (and consequently this function might croak).
61 The memory is allocated using gperl_alloc_temp.
62 SV *gperl_sv_from_filename (const gchar *filename)
64 Convert the filename into an utf8 string as used by gtk/glib and
65 perl.
66 gboolean gperl_str_eq (const char * a, const char * b);
68 Compare a pair of ascii strings, considering '-' and '_' to be
69 equivalent. Used for things like enum value nicknames and signal
70 names.
71 guint gperl_str_hash (gconstpointer key)
73 Like g_str_hash(), but considers '-' and '_' to be equivalent.
74 GPerlArgv * gperl_argv_new ()
76 Creates a new Perl argv object whose members can then be passed to
77 functions that request argc and argv style arguments.
78 If the called function(s) modified argv, you can call
80 gperl_argv_update to update Perl's @ARGV in the same way.
81 Remember to call gperl_argv_free when you're done.
83 void gperl_argv_update (GPerlArgv *pargv)
85 Updates @ARGV to resemble the stored argv array.
86 void gperl_argv_free (GPerlArgv *pargv)
88 Frees any resources associated with pargv.
89 char * gperl_format_variable_for_output (SV * sv)
91 Formats the variable stored in sv for output in error messages.
92 Like SvPV_nolen(), but ellipsizes real strings (i.e., not
93 stringified references) at 20 chars to trim things down for error
94 messages.
95 gboolean gperl_sv_is_defined (SV *sv)
97 Checks the SV sv for definedness just like Perl's defined() would
98 do. Most importantly, it correctly handles "magical" SVs, unlike
99 bare SvOK. It's also NULL-safe.
100 GError Exception Objects
102 GError is a facility for propagating run-time error / exception
103 information around in C, which is a language without native support for
104 exceptions. GError uses a simple error code, usually defined as an
105 enum. Since the enums will overlap, GError includes the GQuark
106 corresponding to a particular error "domain" to tell you which error
107 codes will be used. There's also a string containing a specific error
108 message. The strings are arbitrary, and may be translated, but the
109 domains and codes are definite.
110 Perl has native support for exceptions, using "eval" as "try", "croak"
112 or "die" as "throw", and "if ($@)" as "catch". $@ may, in fact, be any
113 scalar, including blessed objects.
114 So, GPerl maps GLib's GError to Perl exceptions.
116 Since, as we described above, error messages are not guaranteed to be
118 unique everywhere, we need to support the use of the error domains and
119 codes. The obvious choice here is to use exception objects; however,
120 to support blessed exception objects, we must perform a little bit of
121 black magic in the bindings. There is no built-in association between
122 an error domain quark and the GType of the corresponding error code
123 enumeration, so the bindings supply both of these when specifying the
124 name of the package into which to bless exceptions of this domain. All
125 GError-based exceptions derive from Glib::Error, of course, and this
126 base class provides all of the functionality, including
127 stringification.
128 All you'll really ever need to do is register error domains with
130 "gperl_register_error_domain", and throw errors with
131 "gperl_croak_gerror".
132 void gperl_register_error_domain (GQuark domain, GType error_enum,
134 const char * package)
135 Tell the bindings to bless GErrors with error->domain == domain
136 into package, and use error_enum to find the nicknames for the
137 error codes. This will call "gperl_set_isa" on package to add
138 "Glib::Error" to package's @ISA.
139 domain may not be 0, and package may not be NULL; what would be the
141 point? error_enum may be 0, in which case you'll get no fancy
142 stringified error values.
143 SV * gperl_sv_from_gerror (GError * error)
145 You should rarely, if ever, need to call this function. This is
146 what turns a GError into a Perl object.
147 gperl_gerror_from_sv (SV * sv, GError ** error)
149 You should rarely need this function. This parses a perl data
150 structure into a GError. If sv is undef (or the empty string),
151 sets *error to NULL, otherwise, allocates a new GError with
152 "g_error_new_literal()" and writes through error; the caller is
153 responsible for calling "g_error_free()". (gperl_croak_gerror()
154 does this, for example.)
155 void gperl_croak_gerror (const char * ignored, GError * err)
157 Croak with an exception based on err. err may not be NULL.
158 ignored exists for backward compatibility, and is, well, ignored.
159 This function calls croak(), which does not return.
160 Since croak() does not return, this function handles the magic
162 behind not leaking the memory associated with the #GError. To use
163 this you'd do something like
164 PREINIT:
166 GError * error = NULL;
167 CODE:
168 if (!funtion_that_can_fail (something, &error))
169 gperl_croak_gerror (NULL, error);
170 It's just that simple!
172 GLog
174 GLib has a message logging mechanism which it uses for the
175 g_return_if_fail() assertion macros, etc.; it's really versatile and
176 allows you to set various levels to be fatal and whatnot. Libraries
177 use these for various types of message reporting.
178 These functions let you reroute those messages from Perl. By default,
180 the warning, critical, and message levels go through perl's warn(), and
181 fatal ones go through croak(). [i'm not sure that these get to croak()
182 before GLib abort()s on them...]
183 gint gperl_handle_logs_for (const gchar * log_domain)
185 Route all g_logs for log_domain through gperl's log handling.
186 You'll have to register domains in each binding submodule, because
187 there's no way we can know about them down here.
188 And, technically, this traps all the predefined log levels, not any
190 of the ones you (or your library) may define for yourself.
191 GType / GEnum / GFlags
193 void gperl_register_fundamental (GType gtype, const char * package)
194 register a mapping between gtype and package. this is for
195 "fundamental" types which have no other requirements for metadata
196 storage, such as GEnums, GFlags, or real GLib fundamental types
197 like G_TYPE_INT, G_TYPE_FLOAT, etc.
198 void gperl_register_fundamental_alias (GType gtype, const char *
200 package)
201 Makes package an alias for type. This means that the package name
202 specified by package will be mapped to type by
203 gperl_fundamental_type_from_package, but
204 gperl_fundamental_package_from_type won't map type to package.
205 This is useful if you want to change the canonical package name of
206 a type while preserving backwards compatibility with code which
207 uses package to specify type.
208 In order for this to make sense, another package name should be
210 registered for type with gperl_register_fundamental or
211 gperl_register_fundamental_full.
212 GPerlValueWrapperClass
214 Specifies the vtable that is to be used to convert fundamental
215 types to and from Perl variables.
216 typedef struct _GPerlValueWrapperClass GPerlValueWrapperClass;
218 struct _GPerlValueWrapperClass {
219 GPerlValueWrapFunc wrap;
220 GPerlValueUnwrapFunc unwrap;
221 };
222 The members are function pointers, each of which serves a specific
224 purpose:
225 GPerlValueWrapFunc
227 Turns value into an SV. The caller assumes ownership of the
228 SV. value is not to be modified.
229 typedef SV* (*GPerlValueWrapFunc) (const GValue * value);
231 GPerlValueUnwrapFunc
233 Turns sv into its fundamental representation and stores the
234 result in the pre-configured value. value must not be
235 overwritten; instead one of the various "g_value_set_*()"
236 functions must be used or the "value->data" pointer must be
237 modifed directly.
238 typedef void (*GPerlValueUnwrapFunc) (GValue * value,
240 SV * sv);
241 void gperl_register_fundamental_full (GType gtype, const char *
243 package, GPerlValueWrapperClass * wrapper_class)
244 Like gperl_register_fundamental, registers a mapping between gtype
245 and package. In addition, this also installs the function pointers
246 in wrapper_class as the handlers for the type. See
247 GPerlValueWrapperClass.
248 gperl_register_fundamental_full does not copy the contents of
250 wrapper_class -- it assumes that wrapper_class is statically
251 allocated and that it will be valid for the whole lifetime of the
252 program.
253 GType gperl_fundamental_type_from_package (const char * package)
255 look up the GType corresponding to a package registered by
256 gperl_register_fundamental().
257 const char * gperl_fundamental_package_from_type (GType gtype)
259 look up the package corresponding to a gtype registered by
260 gperl_register_fundamental().
261 GPerlValueWrapperClass * gperl_fundamental_wrapper_class_from_type
263 (GType gtype)
264 look up the wrapper class corresponding to a gtype that has
265 previously been registered with gperl_register_fundamental_full().
266 gboolean gperl_try_convert_enum (GType gtype, SV * sv, gint * val)
268 return FALSE if sv can't be mapped to a valid member of the
269 registered enum type gtype; otherwise, return TRUE write the new
270 value to the int pointed to by val.
271 you'll need this only in esoteric cases.
273 gint gperl_convert_enum (GType type, SV * val)
275 croak if val is not part of type, otherwise return corresponding
276 value
277 SV * gperl_convert_back_enum_pass_unknown (GType type, gint val)
279 return a scalar containing the nickname of the enum value val, or
280 the integer value of val if val is not a member of the enum type.
281 SV * gperl_convert_back_enum (GType type, gint val)
283 return a scalar which is the nickname of the enum value val, or
284 croak if val is not a member of the enum.
285 gboolean gperl_try_convert_flag (GType type, const char * val_p, gint *
287 val)
288 like gperl_try_convert_enum(), but for GFlags.
289 gint gperl_convert_flag_one (GType type, const char * val)
291 croak if val is not part of type, otherwise return corresponding
292 value.
293 gint gperl_convert_flags (GType type, SV * val)
295 collapse a list of strings to an integer with all the correct bits
296 set, croak if anything is invalid.
297 SV * gperl_convert_back_flags (GType type, gint val)
299 convert a bitfield to a list of strings.
300 Inheritance management
302 void gperl_set_isa (const char * child_package, const char *
303 parent_package)
304 tell perl that child_package inherits parent_package, after
305 whatever else is already there. equivalent to "push
306 @{$parent_package}::ISA, $child_package;"
307 void gperl_prepend_isa (const char * child_package, const char *
309 parent_package)
310 tell perl that child_package inherits parent_package, but before
311 whatever else is already there. equivalent to "unshift
312 @{$parent_package}::ISA, $child_package;"
313 GType gperl_type_from_package (const char * package)
315 Look up the GType associated with package, regardless of how it was
316 registered. Returns 0 if no mapping can be found.
317 const char * gperl_package_from_type (GType gtype)
319 Look up the name of the package associated with gtype, regardless
320 of how it was registered. Returns NULL if no mapping can be found.
321 Boxed type support for SV
323 In order to allow GValues to hold perl SVs we need a GBoxed wrapper.
324 GPERL_TYPE_SV
326 Evaluates to the GType for SVs. The bindings register a mapping
327 between GPERL_TYPE_SV and the package 'Glib::Scalar' with
328 gperl_register_boxed().
329 SV * gperl_sv_copy (SV * sv)
331 implemented as "newSVsv (sv)".
332 void gperl_sv_free (SV * sv)
334 implemented as "SvREFCNT_dec (sv)".
335 UTF-8 strings with gchar
337 By convention, gchar* is assumed to point to UTF8 string data, and
338 char* points to ascii string data. Here we define a pair of wrappers
339 for the boilerplate of upgrading Perl strings. They are implemented as
340 functions rather than macros, because comma expressions in macros are
341 not supported by all compilers.
342 These functions should be used instead of newSVpv and SvPV_nolen in all
344 cases which deal with gchar* types.
345 gchar * SvGChar (SV * sv)
347 extract a UTF8 string from sv.
348 SV * newSVGChar (const gchar * str)
350 copy a UTF8 string into a new SV. if str is NULL, returns
351 &PL_sv_undef.
352 64 bit integers
354 On 32 bit machines and even on some 64 bit machines, perl's IV/UV data
355 type can only hold 32 bit values. The following functions therefore
356 convert 64 bit integers to and from Perl strings if normal IV/UV
357 conversion does not suffice.
358 gint64 SvGInt64 (SV *sv)
360 Converts the string in sv to a signed 64 bit integer. If
361 appropriate, uses "SvIV" instead.
362 SV * newSVGInt64 (gint64 value)
364 Creates a PV from the signed 64 bit integer in value. If
365 appropriate, uses "newSViv" instead.
366 guint64 SvGUInt64 (SV *sv)
368 Converts the string in sv to an unsigned 64 bit integer. If
369 appropriate, uses "SvUV" instead.
370 SV * newSVGUInt64 (guint64 value)
372 Creates a PV from the unsigned 64 bit integer in value. If
373 appropriate, uses "newSVuv" instead.
374 GBoxed
376 GPerlBoxedWrapperClass
377 Specifies the vtable of functions to be used for bringing boxed
378 types in and out of perl. The structure is defined like this:
379 typedef struct _GPerlBoxedWrapperClass GPerlBoxedWrapperClass;
381 struct _GPerlBoxedWrapperClass {
382 GPerlBoxedWrapFunc wrap;
383 GPerlBoxedUnwrapFunc unwrap;
384 GPerlBoxedDestroyFunc destroy;
385 };
386 The members are function pointers, each of which serves a specific
388 purpose:
389 GPerlBoxedWrapFunc
391 turn a boxed pointer into an SV. gtype is the type of the
392 boxed pointer, and package is the package to which that gtype
393 is registered (the lookup has already been done for you at this
394 point). if own is true, the wrapper is responsible for freeing
395 the object; if it is false, some other code owns the object and
396 you must NOT free it.
397 typedef SV* (*GPerlBoxedWrapFunc) (GType gtype,
399 const char * package,
400 gpointer boxed,
401 gboolean own);
402 GPerlBoxedUnwrapFunc
404 turn an SV into a boxed pointer. like GPerlBoxedWrapFunc,
405 gtype and package are the registered type pair, already looked
406 up for you (in the process of finding the proper wrapper
407 class). sv is the sv to unwrap.
408 typedef gpointer (*GPerlBoxedUnwrapFunc) (GType gtype,
410 const char * package,
411 SV * sv);
412 GPerlBoxedDestroyFunc
414 this will be called by Glib::Boxed::DESTROY, when the wrapper
415 is destroyed. it is a hook that allows you to destroy an
416 object owned by the wrapper; note, however, that you will have
417 had to keep track yourself of whether the object was to be
418 freed.
419 typedef void (*GPerlBoxedDestroyFunc) (SV * sv);
421 void gperl_register_boxed (GType gtype, const char * package,
423 GPerlBoxedWrapperClass * wrapper_class)
424 Register a mapping between the GBoxed derivative gtype and package.
425 The specified, wrapper_class will be used to wrap and unwrap
426 objects of this type; you may pass NULL to use the default wrapper
427 (the same one returned by gperl_default_boxed_wrapper_class()).
428 In normal usage, the standard opaque wrapper supplied by the
430 library is sufficient and correct. In some cases, however, you
431 want a boxed type to map directly to a native perl type; for
432 example, some struct may be more appropriately represented as a
433 hash in perl. Since the most necessary place for this conversion
434 to happen is in gperl_value_from_sv() and gperl_sv_from_value(),
435 the only reliable and robust way to implement this is a hook into
436 gperl_get_boxed_check() and gperl_new_boxed(); that is exactly the
437 purpose of wrapper_class. See "GPerlBoxedWrapperClass".
438 gperl_register_boxed does not copy the contents of wrapper_class --
440 it assumes that wrapper_class is statically allocated and that it
441 will be valid for the whole lifetime of the program.
442 void gperl_register_boxed_alias (GType gtype, const char * package)
444 Makes package an alias for type. This means that the package name
445 specified by package will be mapped to type by
446 gperl_boxed_type_from_package, but gperl_boxed_package_from_type
447 won't map type to package. This is useful if you want to change
448 the canonical package name of a type while preserving backwards
449 compatibility with code which uses package to specify type.
450 In order for this to make sense, another package name should be
452 registered for type with gperl_register_boxed.
453 GType gperl_boxed_type_from_package (const char * package)
455 Look up the GType associated with package package. Returns 0 if
456 type is not registered.
457 const char * gperl_boxed_package_from_type (GType type)
459 Look up the package associated with GBoxed derivative type.
460 Returns NULL if type is not registered.
461 GPerlBoxedWrapperClass * gperl_default_boxed_wrapper_class (void)
463 get a pointer to the default wrapper class; handy if you want to
464 use the normal wrapper, with minor modifications. note that you
465 can just pass NULL to gperl_register_boxed(), so you really only
466 need this in fringe cases.
467 SV * gperl_new_boxed (gpointer boxed, GType gtype, gboolean own)
469 Export a GBoxed derivative to perl, according to whatever
470 GPerlBoxedWrapperClass is registered for gtype. In the default
471 implementation, this means wrapping an opaque perl object around
472 the pointer to a small wrapper structure which stores some
473 metadata, such as whether the boxed structure should be destroyed
474 when the wrapper is destroyed (controlled by own; if the wrapper
475 owns the object, the wrapper is in charge of destroying it's data).
476 SV * gperl_new_boxed_copy (gpointer boxed, GType gtype)
478 Create a new copy of boxed and return an owner wrapper for it.
479 boxed may not be NULL. See "gperl_new_boxed".
480 gpointer gperl_get_boxed_check (SV * sv, GType gtype)
482 Extract the boxed pointer from a wrapper; croaks if the wrapper sv
483 is not blessed into a derivative of the expected gtype. Does not
484 allow undef.
485 GObject
487 To deal with the intricate interaction of the different reference-
488 counting semantics of Perl objects versus GObjects, the bindings create
489 a combined PerlObject+GObject, with the GObject's pointer in magic
490 attached to the Perl object, and the Perl object's pointer in the
491 GObject's user data. Thus it's not really a "wrapper", but we refer to
492 it as one, because "combined Perl object + GObject" is a cumbersome and
493 confusing mouthful.
494 GObjects are represented as blessed hash references. The GObject user
496 data mechanism is not typesafe, and thus is used only for unsigned
497 integer values; the Perl-level hash is available for any type of user
498 data. The combined nature of the wrapper means that data stored in the
499 hash will stick around as long as the object is alive.
500 Since the C pointer is stored in attached magic, the C pointer is not
502 available to the Perl developer via the hash object, so there's no need
503 to worry about breaking it from perl.
504 Propers go to Marc Lehmann for dreaming most of this up.
506 void gperl_register_object (GType gtype, const char * package)
508 tell the GPerl type subsystem what Perl package corresponds with a
509 given GObject by GType. automagically sets up @package::ISA for
510 you.
511 note that @ISA will not be created for gtype until gtype's parent
513 has been registered. if you are experiencing strange problems with
514 a class' @ISA not being set up, change the order in which you
515 register them.
516 void gperl_register_object_alias (GType gtype, const char * package)
518 Makes package an alias for type. This means that the package name
519 specified by package will be mapped to type by
520 gperl_object_type_from_package, but gperl_object_package_from_type
521 won't map type to package. This is useful if you want to change
522 the canonical package name of a type while preserving backwards
523 compatibility with code which uses package to specify type.
524 In order for this to make sense, another package name should be
526 registered for type with gperl_register_object.
527 void gperl_register_sink_func (GType gtype, GPerlObjectSinkFunc func)
529 Tell gperl_new_object() to use func to claim ownership of objects
530 derived from gtype.
531 gperl_new_object() always refs a GObject when wrapping it for the
533 first time. To have the Perl wrapper claim ownership of a GObject
534 as part of gperl_new_object(), you unref the object after ref'ing
535 it. however, different GObject subclasses have different ways to
536 claim ownership; for example, GtkObject simply requires you to call
537 gtk_object_sink(). To make this concept generic, this function
538 allows you to register a function to be called when then wrapper
539 should claim ownership of the object. The func registered for a
540 given type will be called on any object for which "g_type_isa
541 (G_TYPE_OBJECT (object), type)" succeeds.
542 If no sinkfunc is found for an object, g_object_unref() will be
544 used.
545 Even though GObjects don't need sink funcs, we need to have them in
547 Glib as a hook for upstream objects. If we create a GtkObject (or
548 any other type of object which uses a different way to claim
549 ownership) via Glib::Object->new, any upstream wrappers, such as
550 gtk2perl_new_object(), will not be called. Having a sink func
551 facility down here enables us always to do the right thing.
552 void gperl_object_set_no_warn_unreg_subclass (GType gtype, gboolean
554 nowarn)
555 In versions 1.00 through 1.10x of Glib, the bindings required all
556 types to be registered ahead of time. Upon encountering an unknown
557 type, the bindings would emit a warning to the effect of "unknown
558 type 'Foo'; representing as first known parent type 'Bar'".
559 However, for some types, such as GtkStyle or GdkGC, the actual
560 object returned is an instance of a child type of a private
561 implementation (e.g., a theme engine ("BlueCurveStyle") or gdk
562 backend ("GdkGCX11")); we neither can nor should have registered
563 names for these types. Therefore, it is possible to tell the
564 bindings not to warn about these unregistered subclasses, and
565 simply represent them as the parent type.
566 With 1.12x, the bindings will automatically register unknown
568 classes into the namespace Glib::Object::_Unregistered to avoid
569 possible breakage resulting from unknown ancestors of known
570 children. To preserve the old registered-as-unregistered behavior,
571 the value installed by this function is used to prevent the
572 _Unregistered mapping for such private backend classes.
573 Note: this assumes gtype has already been registered with
575 gperl_register_object().
576 const char * gperl_object_package_from_type (GType gtype)
578 Get the package corresponding to gtype. If gtype is not a GObject
579 or GInterface, returns NULL. If gtype is not registered to a
580 package name, a new name of the form
581 "Glib::Object::_Unregistered::$c_type_name" will be created, used
582 to register the class, and then returned.
583 HV * gperl_object_stash_from_type (GType gtype)
585 Get the stash corresponding to gtype; returns NULL if gtype is not
586 registered. The stash is useful for "bless"ing.
587 GType gperl_object_type_from_package (const char * package)
589 Inverse of gperl_object_package_from_type(), returns 0 if package
590 is not registered.
591 SV * gperl_new_object (GObject * object, gboolean own)
593 Use this function to get the perl part of a GObject. If object has
594 never been seen by perl before, a new, empty perl object will be
595 created and added to a private key under object's qdata. If object
596 already has a perl part, a new reference to it will be created. The
597 gobject + perl object together form a combined object that is
598 properly refcounted, i.e. both parts will stay alive as long as at
599 least one of them is alive, and only when both perl object and
600 gobject are no longer referenced will both be freed.
601 The perl object will be blessed into the package corresponding to
603 the GType returned by calling G_OBJECT_TYPE() on object; if that
604 class has not been registered via gperl_register_object(), this
605 function will emit a warning to that effect (with warn()), and
606 attempt to bless it into the first known class in the object's
607 ancestry. Since Glib::Object is already registered, you'll get a
608 Glib::Object if you are lazy, and thus this function can fail only
609 if object isn't descended from GObject, in which case it croaks.
610 (In reality, if you pass a non-GObject to this function, you'll be
611 lucky if you don't get a segfault, as there's not really a way to
612 trap that.) In practice these warnings can be unavoidable, so you
613 can use gperl_object_set_no_warn_unreg_subclass() to quell them on
614 a class-by-class basis.
615 However, when perl code is calling a GObject constructor (any
617 function which returns a new GObject), call gperl_new_object() with
618 own set to %TRUE; this will cause the first matching sink function
619 to be called on the GObject to claim ownership of that object, so
620 that it will be destroyed when the perl object goes out of scope.
621 The default sink func is g_object_unref(); other types should
622 supply the proper function; e.g., GtkObject should use
623 gtk_object_sink() here.
624 Returns the blessed perl object, or #&PL_sv_undef if object was
626 #NULL.
627 GObject * gperl_get_object (SV * sv)
629 retrieve the GObject pointer from a Perl object. Returns NULL if
630 sv is not linked to a GObject.
631 Note, this one is not safe -- in general you want to use
633 gperl_get_object_check().
634 GObject * gperl_get_object_check (SV * sv, GType gtype);
636 croaks if sv is undef or is not blessed into the package
637 corresponding to gtype. use this for bringing parameters into
638 xsubs from perl. Returns the same as gperl_get_object() (provided
639 it doesn't croak first).
640 SV * gperl_object_check_type (SV * sv, GType gtype)
642 Essentially the same as gperl_get_object_check().
643 This croaks if the types aren't compatible.
645 typedef GObject GObject_noinc
647 typedef GObject GObject_ornull
648 newSVGObject(obj)
649 newSVGObject_noinc(obj)
650 SvGObject(sv)
651 SvGObject_ornull(sv)
652 GValue
654 GValue is GLib's generic value container, and it is because of GValue
655 that the run time type handling of GObject parameters and GClosure
656 marshaling can function, and most usages of these functions will be
657 from those two points.
658 Client code will run into uses for gperl_sv_from_value() and
660 gperl_value_from_sv() when trying to convert lists of parameters into
661 GValue arrays and the like.
662 gboolean gperl_value_from_sv (GValue * value, SV * sv)
664 set a value from a whatever is in sv. value must be initialized so
665 the code knows what kind of value to coerce out of sv.
666 Return value is always TRUE; if the code knows how to perform the
668 conversion, it croaks. (The return value is for backward
669 compatibility.) In reality, this really ought to always succeed; a
670 failed conversion should be considered a bug or unimplemented code!
671 SV * gperl_sv_from_value (const GValue * value)
673 Coerce whatever is in value into a perl scalar and return it.
674 Croaks if the code doesn't know how to perform the conversion.
676 GClosure / GPerlClosure
678 GPerlClosure is a wrapper around the gobject library's GClosure with
679 special handling for marshalling perl subroutines as callbacks. This
680 is specially tuned for use with GSignal and stuff like io watch,
681 timeout, and idle handlers.
682 For generic callback functions, which need parameters but do not get
684 registered with the type system, this is sometimes overkill. See
685 GPerlCallback, below.
686 GClosure * gperl_closure_new (SV * callback, SV * data, gboolean swap)
688 Create and return a new GPerlClosure. callback and data will be
689 copied for storage; callback must not be NULL. If swap is TRUE,
690 data will be swapped with the instance during invocation (this is
691 used to implement g_signal_connect_swapped()).
692 If compiled under a thread-enabled perl, the closure will be
694 created and marshaled in such a way as to ensure that the same
695 interpreter which created the closure will be used to invoke it.
696 GClosure * gperl_closure_new_with_marshaller (SV * callback, SV * data,
698 gboolean swap, GClosureMarshal marshaller)
699 Like "gperl_closure_new", but uses a caller-supplied marshaller.
700 This is provided for use in those sticky circumstances when you
701 just can't do it any other way; in general, you want to use the
702 default marshaller, which you get if you provide NULL for
703 marshaller.
704 If you use you own marshaller, you need to take care of everything
706 yourself, including swapping the instance and data if
707 "GPERL_CLOSURE_SWAP_DATA (closure)" is true, calling
708 "gperl_run_exception_handlers" if ERRSV is true after invoking the
709 perl sub, and ensuring that you properly use the "marshal_data"
710 parameter as the perl interpreter when PERL_IMPLICIT_CONTEXT is
711 defined. See the implementation of the default marshaller,
712 "gperl_closure_marshal", in Glib/GClosure.xs for inspiration.
713 GPerlCallback
715 generic callback functions usually get invoked directly, and are not
716 passed parameter lists as GValues. we could very easily wrap up such
717 generic callbacks with something that converts the parameters to
718 GValues and then channels everything through GClosure, but this has two
719 problems: 1) the above implementation of GClosure is tuned to
720 marshalling signal handlers, which always have an instance object, and
721 2) it's more work than is strictly necessary.
722 additionally, generic callbacks aren't always kind to the GClosure
724 paradigm.
725 so, here's GPerlCallback, which is designed specifically to run generic
727 callback functions. it reads parameters off the C stack and converts
728 them into parameters on the perl stack. (it uses the GValue to/from SV
729 mechanism to do so, but doesn't allocate any temps on the heap.) the
730 callback object itself stores the parameter type list.
731 unfortunately, since the data element is always last, but the number of
733 arguments is not known until we have the callback object, we can't pass
734 gperl_callback_invoke directly to functions requiring a callback;
735 you'll have to write a proxy callback which calls
736 gperl_callback_invoke.
737 GPerlCallback * gperl_callback_new (SV * func, SV * data, gint
739 n_params, GType param_types[], GType return_type)
740 Create and return a new GPerlCallback; use gperl_callback_destroy
741 when you are finished with it.
742 func: perl subroutine to call. this SV will be copied, so don't
744 worry about reference counts. must not be #NULL.
745 data: scalar to pass to func in addition to all other arguments.
747 the SV will be copied, so don't worry about reference counts. may
748 be #NULL.
749 n_params: the number of elements in param_types.
751 param_types: the #GType of each argument that should be passed from
753 the invocation to func. may be #NULL if n_params is zero,
754 otherwise it must be n_params elements long or nasty things will
755 happen. this array will be copied; see gperl_callback_invoke() for
756 how it is used.
757 return_type: the #GType of the return value, or 0 if the function
759 has void return.
760 void gperl_callback_destroy (GPerlCallback * callback)
762 Dispose of callback.
763 void gperl_callback_invoke (GPerlCallback * callback, GValue *
765 return_value, ...)
766 Marshall the variadic parameters according to callback's
767 param_types, and then invoke callback's subroutine in scalar
768 context, or void context if the return type is G_TYPE_VOID. If
769 return_value is not NULL, then value returned (if any) will be
770 copied into return_value.
771 A typical callback handler would look like this:
773 static gint
775 real_c_callback (Foo * f, Bar * b, int a, gpointer data)
776 {
777 GPerlCallback * callback = (GPerlCallback*)data;
778 GValue return_value = {0,};
779 gint retval;
780 g_value_init (&return_value, callback->return_type);
781 gperl_callback_invoke (callback, &return_value,
782 f, b, a);
783 retval = g_value_get_int (&return_value);
784 g_value_unset (&return_value);
785 return retval;
786 }
787 Exception Handling
789 Like Event, Tk, and most other callback-using, event-based perl
790 modules, Glib traps exceptions that happen in callbacks. To enable
791 your code to do something about these exceptions, Glib stores a list of
792 exception handlers which will be called on the trapped exceptions.
793 This is completely distinct from the $SIG{__DIE__} mechanism provided
794 by Perl itself, for various reasons (not the least of which is that the
795 Perl docs and source code say that $SIG{__DIE__} is intended for
796 running as the program is about to exit, and other behaviors may be
797 removed in the future (apparently a source of much debate on p5p)).
798 int gperl_install_exception_handler (GClosure * closure)
800 Install a GClosure to be executed when gperl_closure_invoke() traps
801 an exception. The closure should return boolean (TRUE if the
802 handler should remain installed) and expect to receive a perl
803 scalar. This scalar will be a private copy of ERRSV ($@) which the
804 handler can mangle to its heart's content.
805 The return value is an integer id tag that may be passed to
807 gperl_removed_exception_handler().
808 void gperl_remove_exception_handler (guint tag)
810 Remove the exception handler identified by tag, as returned by
811 gperl_install_exception_handler(). If tag cannot be found, this
812 does nothing.
813 WARNING: this function locks a global data structure, so do NOT
815 call it recursively. also, calling this from within an exception
816 handler will result in a deadlock situation. if you want to remove
817 your handler just have it return FALSE.
818 void gperl_run_exception_handlers (void)
820 Invoke whatever exception handlers are installed. You will need
821 this if you have written a custom marshaler. Uses the value of the
822 global ERRSV.
823 GSignal
825 void gperl_signal_set_marshaller_for (GType instance_type, char *
826 detailed_signal, GClosureMarshal marshaller)
827 You need this function only in rare cases, usually as workarounds
828 for bad signal parameter types or to implement writable arguments.
829 Use the given marshaller to marshal all handlers for
830 detailed_signal on instance_type. "gperl_signal_connect" will look
831 for marshallers registered here, and apply them to the GPerlClosure
832 it creates for the given callback being connected.
833 Use the helper macros in gperl_marshal.h to help write your
835 marshaller function. That header, which is installed with the Glib
836 module but not #included through gperl.h, includes commentary and
837 examples which you should follow closely to avoid nasty bugs. Use
838 the Source, Luke.
839 WARNING: Bend over backwards and turn your head around 720 degrees
841 before attempting to write a GPerlClosure marshaller without using
842 the macros in gperl_marshal.h. If you absolutely cannot use those
843 macros, be certain to understand what those macros do so you can
844 get the semantics correct, and keep your code synchronized with
845 them, or you may miss very important bugfixes.
846 gulong gperl_signal_connect (SV * instance, char * detailed_signal, SV
848 * callback, SV * data, GConnectFlags flags)
849 The actual workhorse behind GObject::signal_connect, the binding
850 for g_signal_connect, for use from within XS. This creates a
851 "GPerlClosure" wrapper for the given callback and data, and
852 connects that closure to the signal named detailed_signal on the
853 given GObject instance. This is only good for named signals.
854 flags is the same as for g_signal_connect(). data may be NULL, but
855 callback must not be.
856 Returns the id of the installed callback.
858
860 perlapi(1), perlguts(1), GLib Reference Manual, Glib(3pm),
861 Glib::devel(3pm).
862
864 This file was automatically generated from the source code of the Glib
865 module, which is maintained by the gtk2-perl team.
866
868 Copyright (C) 2003 by the gtk2-perl team (see the file AUTHORS for the
869 full list)
870 This library is free software; you can redistribute it and/or modify it
872 under the terms of the GNU Library General Public License as published
873 by the Free Software Foundation; either version 2.1 of the License, or
874 (at your option) any later version.
875 This library is distributed in the hope that it will be useful, but
877 WITHOUT ANY WARRANTY; without even the implied warranty of
878 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
879 Library General Public License for more details.
880 You should have received a copy of the GNU Library General Public
882 License along with this library; if not, write to the Free Software
883 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307
884 USA.
885perl v5.12.1 2010-07-07 Glib::xsapi(3)