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.
25 GPERL_CALL_BOOT(name)
27 call the boot code of a module by symbol rather than by name.
28 in a perl extension which uses several xs files but only one pm,
30 you need to bootstrap the other xs files in order to get their
31 functions exported to perl. if the file has MODULE = Foo::Bar, the
32 boot symbol would be boot_Foo__Bar.
33 void _gperl_call_XS (pTHX_ void (*subaddr) (pTHX_ CV *), CV * cv, SV **
35 mark);
36 never use this function directly. see "GPERL_CALL_BOOT".
37 for the curious, this calls a perl sub by function pointer rather
39 than by name; call_sv requires that the xsub already be registered,
40 but we need this to call a function which will register xsubs.
41 this is an evil hack and should not be used outside of the
42 GPERL_CALL_BOOT macro. it's implemented as a function to avoid
43 code size bloat, and exported so that extension modules can pull
44 the same trick.
45 gpointer gperl_alloc_temp (int nbytes)
47 Allocate and return a pointer to an nbytes-long, zero-initialized,
48 temporary buffer that will be reaped at the next garbage collection
49 sweep. This is handy for allocating things that need to be
50 alloc'ed before a croak (since croak doesn't return and give you
51 the chance to free them). The trick is that the memory is allo‐
52 cated in a mortal perl scalar. See the perl online manual for
53 notes on using this technique.
54 Do not under any circumstances attempt to call g_free(), free(), or
56 any other deallocator on this pointer, or you will crash the inter‐
57 preter.
58 gchar *gperl_filename_from_sv (SV *sv)
60 Return a localized version of the filename in the sv, using g_file‐
61 name_from_utf8 (and consequently this function might croak). The
62 memory is allocated using gperl_alloc_temp.
63 SV *gperl_sv_from_filename (const gchar *filename)
65 Convert the filename into an utf8 string as used by gtk/glib and
66 perl.
67 gboolean gperl_str_eq (const char * a, const char * b);
69 Compare a pair of ascii strings, considering '-' and '_' to be
70 equivalent. Used for things like enum value nicknames and signal
71 names.
72 guint gperl_str_hash (gconstpointer key)
74 Like g_str_hash(), but considers '-' and '_' to be equivalent.
75 GPerlArgv * gperl_argv_new ()
77 Creates a new Perl argv object whose members can then be passed to
78 functions that request argc and argv style arguments.
79 If the called function(s) modified argv, you can call
81 gperl_argv_update to update Perl's @ARGV in the same way.
82 Remember to call gperl_argv_free when you're done.
84 void gperl_argv_update (GPerlArgv *pargv)
86 Updates @ARGV to resemble the stored argv array.
87 void gperl_argv_free (GPerlArgv *pargv)
89 Frees any resources associated with pargv.
90 char * gperl_format_variable_for_output (SV * sv)
92 Formats the variable stored in sv for output in error messages.
93 Like SvPV_nolen(), but ellipsizes real strings (i.e., not stringi‐
94 fied references) at 20 chars to trim things down for error mes‐
95 sages.
96 GError Exception Objects
98 GError is a facility for propagating run-time error / exception infor‐
100 mation around in C, which is a language without native support for
101 exceptions. GError uses a simple error code, usually defined as an
102 enum. Since the enums will overlap, GError includes the GQuark corre‐
103 sponding to a particular error "domain" to tell you which error codes
104 will be used. There's also a string containing a specific error mes‐
105 sage. The strings are arbitrary, and may be translated, but the
106 domains and codes are definite.
107 Perl has native support for exceptions, using "eval" as "try", "croak"
109 or "die" as "throw", and "if ($@)" as "catch". $@ may, in fact, be any
110 scalar, including blessed objects.
111 So, GPerl maps GLib's GError to Perl exceptions.
113 Since, as we described above, error messages are not guaranteed to be
115 unique everywhere, we need to support the use of the error domains and
116 codes. The obvious choice here is to use exception objects; however,
117 to support blessed exception objects, we must perform a little bit of
118 black magic in the bindings. There is no built-in association between
119 an error domain quark and the GType of the corresponding error code
120 enumeration, so the bindings supply both of these when specifying the
121 name of the package into which to bless exceptions of this domain. All
122 GError-based exceptions derive from Glib::Error, of course, and this
123 base class provides all of the functionality, including stringifica‐
124 tion.
125 All you'll really ever need to do is register error domains with
127 "gperl_register_error_domain", and throw errors with "gperl_croak_ger‐
128 ror".
129 void gperl_register_error_domain (GQuark domain, GType error_enum,
131 const char * package)
132 Tell the bindings to bless GErrors with error->domain == domain
133 into package, and use error_enum to find the nicknames for the
134 error codes. This will call "gperl_set_isa" on package to add
135 "Glib::Error" to package's @ISA.
136 domain may not be 0, and package may not be NULL; what would be the
138 point? error_enum may be 0, in which case you'll get no fancy
139 stringified error values.
140 SV * gperl_sv_from_gerror (GError * error)
142 You should rarely, if ever, need to call this function. This is
143 what turns a GError into a Perl object.
144 gperl_gerror_from_sv (SV * sv, GError ** error)
146 You should rarely need this function. This parses a perl data
147 structure into a GError. If sv is undef (or the empty string),
148 sets *error to NULL, otherwise, allocates a new GError with
149 "g_error_new_literal()" and writes through error; the caller is
150 responsible for calling "g_error_free()". (gperl_croak_gerror()
151 does this, for example.)
152 void gperl_croak_gerror (const char * ignored, GError * err)
154 Croak with an exception based on err. err may not be NULL.
155 ignored exists for backward compatibility, and is, well, ignored.
156 This function calls croak(), which does not return.
157 Since croak() does not return, this function handles the magic
159 behind not leaking the memory associated with the #GError. To use
160 this you'd do something like
161 PREINIT:
163 GError * error = NULL;
164 CODE:
165 if (!funtion_that_can_fail (something, &error))
166 gperl_croak_gerror (NULL, error);
167 It's just that simple!
169 GLog
171 GLib has a message logging mechanism which it uses for the
173 g_return_if_fail() assertion macros, etc.; it's really versatile and
174 allows you to set various levels to be fatal and whatnot. Libraries
175 use these for various types of message reporting.
176 These functions let you reroute those messages from Perl. By default,
178 the warning, critical, and message levels go through perl's warn(), and
179 fatal ones go through croak(). [i'm not sure that these get to croak()
180 before GLib abort()s on them...]
181 gint gperl_handle_logs_for (const gchar * log_domain)
183 Route all g_logs for log_domain through gperl's log handling.
184 You'll have to register domains in each binding submodule, because
185 there's no way we can know about them down here.
186 And, technically, this traps all the predefined log levels, not any
188 of the ones you (or your library) may define for yourself.
189 GType / GEnum / GFlags
191 void gperl_register_fundamental (GType gtype, const char * package)
193 register a mapping between gtype and package. this is for "funda‐
194 mental" types which have no other requirements for metadata stor‐
195 age, such as GEnums, GFlags, or real GLib fundamental types like
196 G_TYPE_INT, G_TYPE_FLOAT, etc.
197 GPerlValueWrapperClass
199 Specifies the vtable that is to be used to convert fundamental
200 types to and from Perl variables.
201 typedef struct _GPerlValueWrapperClass GPerlValueWrapperClass;
203 struct _GPerlValueWrapperClass {
204 GPerlValueWrapFunc wrap;
205 GPerlValueUnwrapFunc unwrap;
206 };
207 The members are function pointers, each of which serves a specific
209 purpose:
210 GPerlValueWrapFunc
212 Turns value into an SV. The caller assumes ownership of the
213 SV. value is not to be modified.
214 typedef SV* (*GPerlValueWrapFunc) (const GValue * value);
216 GPerlValueUnwrapFunc
218 Turns sv into its fundamental representation and stores the
219 result in the pre-configured value. value must not be over‐
220 written; instead one of the various "g_value_set_*()" functions
221 must be used or the "value->data" pointer must be modifed
222 directly.
223 typedef void (*GPerlValueUnwrapFunc) (GValue * value,
225 SV * sv);
226 void gperl_register_fundamental_full (GType gtype, const char * pack‐
228 age, GPerlValueWrapperClass * wrapper_class)
229 Like gperl_register_fundamental, registers a mapping between gtype
230 and package. In addition, this also installs the function pointers
231 in wrapper_class as the handlers for the type. See GPerlValueWrap‐
232 perClass.
233 gperl_register_fundamental_full does not copy the contents of wrap‐
235 per_class -- it assumes that wrapper_class is statically allocated
236 and that it will be valid for the whole lifetime of the program.
237 GType gperl_fundamental_type_from_package (const char * package)
239 look up the GType corresponding to a package registered by
240 gperl_register_fundamental().
241 const char * gperl_fundamental_package_from_type (GType gtype)
243 look up the package corresponding to a gtype registered by
244 gperl_register_fundamental().
245 GPerlValueWrapperClass * gperl_fundamental_wrapper_class_from_type
247 (GType gtype)
248 look up the wrapper class corresponding to a gtype that has previ‐
249 ously been registered with gperl_register_fundamental_full().
250 gboolean gperl_try_convert_enum (GType gtype, SV * sv, gint * val)
252 return FALSE if sv can't be mapped to a valid member of the regis‐
253 tered enum type gtype; otherwise, return TRUE write the new value
254 to the int pointed to by val.
255 you'll need this only in esoteric cases.
257 gint gperl_convert_enum (GType type, SV * val)
259 croak if val is not part of type, otherwise return corresponding
260 value
261 SV * gperl_convert_back_enum_pass_unknown (GType type, gint val)
263 return a scalar containing the nickname of the enum value val, or
264 the integer value of val if val is not a member of the enum type.
265 SV * gperl_convert_back_enum (GType type, gint val)
267 return a scalar which is the nickname of the enum value val, or
268 croak if val is not a member of the enum.
269 gboolean gperl_try_convert_flag (GType type, const char * val_p, gint *
271 val)
272 like gperl_try_convert_enum(), but for GFlags.
273 gint gperl_convert_flag_one (GType type, const char * val)
275 croak if val is not part of type, otherwise return corresponding
276 value.
277 gint gperl_convert_flags (GType type, SV * val)
279 collapse a list of strings to an integer with all the correct bits
280 set, croak if anything is invalid.
281 SV * gperl_convert_back_flags (GType type, gint val)
283 convert a bitfield to a list of strings.
284 Inheritance management
286 void gperl_set_isa (const char * child_package, const char * par‐
288 ent_package)
289 tell perl that child_package inherits parent_package, after what‐
290 ever else is already there. equivalent to "push @{$parent_pack‐
291 age}::ISA, $child_package;"
292 void gperl_prepend_isa (const char * child_package, const char * par‐
294 ent_package)
295 tell perl that child_package inherits parent_package, but before
296 whatever else is already there. equivalent to "unshift @{$par‐
297 ent_package}::ISA, $child_package;"
298 GType gperl_type_from_package (const char * package)
300 Look up the GType associated with package, regardless of how it was
301 registered. Returns 0 if no mapping can be found.
302 const char * gperl_package_from_type (GType gtype)
304 Look up the name of the package associated with gtype, regardless
305 of how it was registered. Returns NULL if no mapping can be found.
306 Boxed type support for SV
308 In order to allow GValues to hold perl SVs we need a GBoxed wrapper.
310 GPERL_TYPE_SV
312 Evaluates to the GType for SVs. The bindings register a mapping
313 between GPERL_TYPE_SV and the package 'Glib::Scalar' with
314 gperl_register_boxed().
315 SV * gperl_sv_copy (SV * sv)
317 implemented as "newSVsv (sv)".
318 void gperl_sv_free (SV * sv)
320 implemented as "SvREFCNT_dec (sv)".
321 UTF-8 strings with gchar
323 By convention, gchar* is assumed to point to UTF8 string data, and
325 char* points to ascii string data. Here we define a pair of wrappers
326 for the boilerplate of upgrading Perl strings. They are implemented as
327 functions rather than macros, because comma expressions in macros are
328 not supported by all compilers.
329 These functions should be used instead of newSVpv and SvPV_nolen in all
331 cases which deal with gchar* types.
332 gchar * SvGChar (SV * sv)
334 extract a UTF8 string from sv.
335 SV * newSVGChar (const gchar * str)
337 copy a UTF8 string into a new SV. if str is NULL, returns
338 &PL_sv_undef.
339 64 bit integers
341 On 32 bit machines and even on some 64 bit machines, perl's IV/UV data
343 type can only hold 32 bit values. The following functions therefore
344 convert 64 bit integers to and from Perl strings if normal IV/UV con‐
345 version does not suffice.
346 gint64 SvGInt64 (SV *sv)
348 Converts the string in sv to a signed 64 bit integer. If appropri‐
349 ate, uses "SvIV" instead.
350 SV * newSVGInt64 (gint64 value)
352 Creates a PV from the signed 64 bit integer in value. If appropri‐
353 ate, uses "newSViv" instead.
354 guint64 SvGUInt64 (SV *sv)
356 Converts the string in sv to an unsigned 64 bit integer. If appro‐
357 priate, uses "SvUV" instead.
358 SV * newSVGUInt64 (guint64 value)
360 Creates a PV from the unsigned 64 bit integer in value. If appro‐
361 priate, uses "newSVuv" instead.
362 GBoxed
364 GPerlBoxedWrapperClass
366 Specifies the vtable of functions to be used for bringing boxed
367 types in and out of perl. The structure is defined like this:
368 typedef struct _GPerlBoxedWrapperClass GPerlBoxedWrapperClass;
370 struct _GPerlBoxedWrapperClass {
371 GPerlBoxedWrapFunc wrap;
372 GPerlBoxedUnwrapFunc unwrap;
373 GPerlBoxedDestroyFunc destroy;
374 };
375 The members are function pointers, each of which serves a specific
377 purpose:
378 GPerlBoxedWrapFunc
380 turn a boxed pointer into an SV. gtype is the type of the
381 boxed pointer, and package is the package to which that gtype
382 is registered (the lookup has already been done for you at this
383 point). if own is true, the wrapper is responsible for freeing
384 the object; if it is false, some other code owns the object and
385 you must NOT free it.
386 typedef SV* (*GPerlBoxedWrapFunc) (GType gtype,
388 const char * package,
389 gpointer boxed,
390 gboolean own);
391 GPerlBoxedUnwrapFunc
393 turn an SV into a boxed pointer. like GPerlBoxedWrapFunc,
394 gtype and package are the registered type pair, already looked
395 up for you (in the process of finding the proper wrapper
396 class). sv is the sv to unwrap.
397 typedef gpointer (*GPerlBoxedUnwrapFunc) (GType gtype,
399 const char * package,
400 SV * sv);
401 GPerlBoxedDestroyFunc
403 this will be called by Glib::Boxed::DESTROY, when the wrapper
404 is destroyed. it is a hook that allows you to destroy an
405 object owned by the wrapper; note, however, that you will have
406 had to keep track yourself of whether the object was to be
407 freed.
408 typedef void (*GPerlBoxedDestroyFunc) (SV * sv);
410 void gperl_register_boxed (GType gtype, const char * package, GPerl‐
412 BoxedWrapperClass * wrapper_class)
413 Register a mapping between the GBoxed derivative gtype and package.
414 The specified, wrapper_class will be used to wrap and unwrap
415 objects of this type; you may pass NULL to use the default wrapper
416 (the same one returned by gperl_default_boxed_wrapper_class()).
417 In normal usage, the standard opaque wrapper supplied by the
419 library is sufficient and correct. In some cases, however, you
420 want a boxed type to map directly to a native perl type; for exam‐
421 ple, some struct may be more appropriately represented as a hash in
422 perl. Since the most necessary place for this conversion to happen
423 is in gperl_value_from_sv() and gperl_sv_from_value(), the only
424 reliable and robust way to implement this is a hook into
425 gperl_get_boxed_check() and gperl_new_boxed(); that is exactly the
426 purpose of wrapper_class. See "GPerlBoxedWrapperClass".
427 gperl_register_boxed does not copy the contents of wrapper_class --
429 it assumes that wrapper_class is statically allocated and that it
430 will be valid for the whole lifetime of the program.
431 GType gperl_boxed_type_from_package (const char * package)
433 Look up the GType associated with package package. Returns 0 if
434 type is not registered.
435 const char * gperl_boxed_package_from_type (GType type)
437 Look up the package associated with GBoxed derivative type.
438 Returns NULL if type is not registered.
439 GPerlBoxedWrapperClass * gperl_default_boxed_wrapper_class (void)
441 get a pointer to the default wrapper class; handy if you want to
442 use the normal wrapper, with minor modifications. note that you
443 can just pass NULL to gperl_register_boxed(), so you really only
444 need this in fringe cases.
445 SV * gperl_new_boxed (gpointer boxed, GType gtype, gboolean own)
447 Export a GBoxed derivative to perl, according to whatever GPerl‐
448 BoxedWrapperClass is registered for gtype. In the default imple‐
449 mentation, this means wrapping an opaque perl object around the
450 pointer to a small wrapper structure which stores some metadata,
451 such as whether the boxed structure should be destroyed when the
452 wrapper is destroyed (controlled by own; if the wrapper owns the
453 object, the wrapper is in charge of destroying it's data).
454 SV * gperl_new_boxed_copy (gpointer boxed, GType gtype)
456 Create a new copy of boxed and return an owner wrapper for it.
457 boxed may not be NULL. See "gperl_new_boxed".
458 gpointer gperl_get_boxed_check (SV * sv, GType gtype)
460 Extract the boxed pointer from a wrapper; croaks if the wrapper sv
461 is not blessed into a derivative of the expected gtype. Does not
462 allow undef.
463 GObject
465 To deal with the intricate interaction of the different reference-
467 counting semantics of Perl objects versus GObjects, the bindings create
468 a combined PerlObject+GObject, with the GObject's pointer in magic
469 attached to the Perl object, and the Perl object's pointer in the GOb‐
470 ject's user data. Thus it's not really a "wrapper", but we refer to it
471 as one, because "combined Perl object + GObject" is a cumbersome and
472 confusing mouthful.
473 GObjects are represented as blessed hash references. The GObject user
475 data mechanism is not typesafe, and thus is used only for unsigned
476 integer values; the Perl-level hash is available for any type of user
477 data. The combined nature of the wrapper means that data stored in the
478 hash will stick around as long as the object is alive.
479 Since the C pointer is stored in attached magic, the C pointer is not
481 available to the Perl developer via the hash object, so there's no need
482 to worry about breaking it from perl.
483 Propers go to Marc Lehmann for dreaming most of this up.
485 void gperl_register_object (GType gtype, const char * package)
487 tell the GPerl type subsystem what Perl package corresponds with a
488 given GObject by GType. automagically sets up @package::ISA for
489 you.
490 note that @ISA will not be created for gtype until gtype's parent
492 has been registered. if you are experiencing strange problems with
493 a class' @ISA not being set up, change the order in which you reg‐
494 ister them.
495 void gperl_register_sink_func (GType gtype, GPerlObjectSinkFunc func)
497 Tell gperl_new_object() to use func to claim ownership of objects
498 derived from gtype.
499 gperl_new_object() always refs a GObject when wrapping it for the
501 first time. To have the Perl wrapper claim ownership of a GObject
502 as part of gperl_new_object(), you unref the object after ref'ing
503 it. however, different GObject subclasses have different ways to
504 claim ownership; for example, GtkObject simply requires you to call
505 gtk_object_sink(). To make this concept generic, this function
506 allows you to register a function to be called when then wrapper
507 should claim ownership of the object. The func registered for a
508 given type will be called on any object for which "g_type_isa
509 (G_TYPE_OBJECT (object), type)" succeeds.
510 If no sinkfunc is found for an object, g_object_unref() will be
512 used.
513 Even though GObjects don't need sink funcs, we need to have them in
515 Glib as a hook for upstream objects. If we create a GtkObject (or
516 any other type of object which uses a different way to claim owner‐
517 ship) via Glib::Object->new, any upstream wrappers, such as
518 gtk2perl_new_object(), will not be called. Having a sink func
519 facility down here enables us always to do the right thing.
520 void gperl_object_set_no_warn_unreg_subclass (GType gtype, gboolean
522 nowarn)
523 In versions 1.00 through 1.10x of Glib, the bindings required all
524 types to be registered ahead of time. Upon encountering an unknown
525 type, the bindings would emit a warning to the effect of "unknown
526 type 'Foo'; representing as first known parent type 'Bar'". How‐
527 ever, for some types, such as GtkStyle or GdkGC, the actual object
528 returned is an instance of a child type of a private implementation
529 (e.g., a theme engine ("BlueCurveStyle") or gdk backend
530 ("GdkGCX11")); we neither can nor should have registered names for
531 these types. Therefore, it is possible to tell the bindings not to
532 warn about these unregistered subclasses, and simply represent them
533 as the parent type.
534 With 1.12x, the bindings will automatically register unknown
536 classes into the namespace Glib::Object::_Unregistered to avoid
537 possible breakage resulting from unknown ancestors of known chil‐
538 dren. To preserve the old registered-as-unregistered behavior, the
539 value installed by this function is used to prevent the _Unregis‐
540 tered mapping for such private backend classes.
541 Note: this assumes gtype has already been registered with
543 gperl_register_object().
544 const char * gperl_object_package_from_type (GType gtype)
546 Get the package corresponding to gtype. If gtype is not a GObject
547 or GInterface, returns NULL. If gtype is not registered to a pack‐
548 age name, a new name of the form "Glib::Object::_Unregis‐
549 tered::$c_type_name" will be created, used to register the class,
550 and then returned.
551 HV * gperl_object_stash_from_type (GType gtype)
553 Get the stash corresponding to gtype; returns NULL if gtype is not
554 registered. The stash is useful for "bless"ing.
555 GType gperl_object_type_from_package (const char * package)
557 Inverse of gperl_object_package_from_type(), returns 0 if package
558 is not registered.
559 SV * gperl_new_object (GObject * object, gboolean own)
561 Use this function to get the perl part of a GObject. If object has
562 never been seen by perl before, a new, empty perl object will be
563 created and added to a private key under object's qdata. If object
564 already has a perl part, a new reference to it will be created. The
565 gobject + perl object together form a combined object that is prop‐
566 erly refcounted, i.e. both parts will stay alive as long as at
567 least one of them is alive, and only when both perl object and gob‐
568 ject are no longer referenced will both be freed.
569 The perl object will be blessed into the package corresponding to
571 the GType returned by calling G_OBJECT_TYPE() on object; if that
572 class has not been registered via gperl_register_object(), this
573 function will emit a warning to that effect (with warn()), and
574 attempt to bless it into the first known class in the object's
575 ancestry. Since Glib::Object is already registered, you'll get a
576 Glib::Object if you are lazy, and thus this function can fail only
577 if object isn't descended from GObject, in which case it croaks.
578 (In reality, if you pass a non-GObject to this function, you'll be
579 lucky if you don't get a segfault, as there's not really a way to
580 trap that.) In practice these warnings can be unavoidable, so you
581 can use gperl_object_set_no_warn_unreg_subclass() to quell them on
582 a class-by-class basis.
583 However, when perl code is calling a GObject constructor (any func‐
585 tion which returns a new GObject), call gperl_new_object() with own
586 set to %TRUE; this will cause the first matching sink function to
587 be called on the GObject to claim ownership of that object, so that
588 it will be destroyed when the perl object goes out of scope. The
589 default sink func is g_object_unref(); other types should supply
590 the proper function; e.g., GtkObject should use gtk_object_sink()
591 here.
592 Returns the blessed perl object, or #&PL_sv_undef if object was
594 #NULL.
595 GObject * gperl_get_object (SV * sv)
597 retrieve the GObject pointer from a Perl object. Returns NULL if
598 sv is not linked to a GObject.
599 Note, this one is not safe -- in general you want to use
601 gperl_get_object_check().
602 GObject * gperl_get_object_check (SV * sv, GType gtype);
604 croaks if sv is undef or is not blessed into the package corre‐
605 sponding to gtype. use this for bringing parameters into xsubs
606 from perl. Returns the same as gperl_get_object() (provided it
607 doesn't croak first).
608 SV * gperl_object_check_type (SV * sv, GType gtype)
610 Essentially the same as gperl_get_object_check().
611 This croaks if the types aren't compatible.
613 typedef GObject GObject_noinc
615 typedef GObject GObject_ornull
616 newSVGObject(obj)
617 newSVGObject_noinc(obj)
618 SvGObject(sv)
619 SvGObject_ornull(sv)
620 GValue
622 GValue is GLib's generic value container, and it is because of GValue
624 that the run time type handling of GObject parameters and GClosure mar‐
625 shaling can function, and most usages of these functions will be from
626 those two points.
627 Client code will run into uses for gperl_sv_from_value() and
629 gperl_value_from_sv() when trying to convert lists of parameters into
630 GValue arrays and the like.
631 gboolean gperl_value_from_sv (GValue * value, SV * sv)
633 set a value from a whatever is in sv. value must be initialized so
634 the code knows what kind of value to coerce out of sv.
635 Return value is always TRUE; if the code knows how to perform the
637 conversion, it croaks. (The return value is for backward compati‐
638 bility.) In reality, this really ought to always succeed; a failed
639 conversion should be considered a bug or unimplemented code!
640 SV * gperl_sv_from_value (const GValue * value)
642 Coerce whatever is in value into a perl scalar and return it.
643 Croaks if the code doesn't know how to perform the conversion.
645 GClosure / GPerlClosure
647 GPerlClosure is a wrapper around the gobject library's GClosure with
649 special handling for marshalling perl subroutines as callbacks. This
650 is specially tuned for use with GSignal and stuff like io watch, time‐
651 out, and idle handlers.
652 For generic callback functions, which need parameters but do not get
654 registered with the type system, this is sometimes overkill. See
655 GPerlCallback, below.
656 GClosure * gperl_closure_new (SV * callback, SV * data, gboolean swap)
658 Create and return a new GPerlClosure. callback and data will be
659 copied for storage; callback must not be NULL. If swap is TRUE,
660 data will be swapped with the instance during invocation (this is
661 used to implement g_signal_connect_swapped()).
662 If compiled under a thread-enabled perl, the closure will be cre‐
664 ated and marshaled in such a way as to ensure that the same inter‐
665 preter which created the closure will be used to invoke it.
666 GClosure * gperl_closure_new_with_marshaller (SV * callback, SV * data,
668 gboolean swap, GClosureMarshal marshaller)
669 Like "gperl_closure_new", but uses a caller-supplied marshaller.
670 This is provided for use in those sticky circumstances when you
671 just can't do it any other way; in general, you want to use the
672 default marshaller, which you get if you provide NULL for mar‐
673 shaller.
674 If you use you own marshaller, you need to take care of everything
676 yourself, including swapping the instance and data if "GPERL_CLO‐
677 SURE_SWAP_DATA (closure)" is true, calling "gperl_run_excep‐
678 tion_handlers" if ERRSV is true after invoking the perl sub, and
679 ensuring that you properly use the "marshal_data" parameter as the
680 perl interpreter when PERL_IMPLICIT_CONTEXT is defined. See the
681 implementation of the default marshaller, "gperl_closure_marshal",
682 in Glib/GClosure.xs for inspiration.
683 GPerlCallback
685 generic callback functions usually get invoked directly, and are not
687 passed parameter lists as GValues. we could very easily wrap up such
688 generic callbacks with something that converts the parameters to GVal‐
689 ues and then channels everything through GClosure, but this has two
690 problems: 1) the above implementation of GClosure is tuned to mar‐
691 shalling signal handlers, which always have an instance object, and 2)
692 it's more work than is strictly necessary.
693 additionally, generic callbacks aren't always kind to the GClosure par‐
695 adigm.
696 so, here's GPerlCallback, which is designed specifically to run generic
698 callback functions. it reads parameters off the C stack and converts
699 them into parameters on the perl stack. (it uses the GValue to/from SV
700 mechanism to do so, but doesn't allocate any temps on the heap.) the
701 callback object itself stores the parameter type list.
702 unfortunately, since the data element is always last, but the number of
704 arguments is not known until we have the callback object, we can't pass
705 gperl_callback_invoke directly to functions requiring a callback;
706 you'll have to write a proxy callback which calls gperl_call‐
707 back_invoke.
708 GPerlCallback * gperl_callback_new (SV * func, SV * data, gint
710 n_params, GType param_types[], GType return_type)
711 Create and return a new GPerlCallback; use gperl_callback_destroy
712 when you are finished with it.
713 func: perl subroutine to call. this SV will be copied, so don't
715 worry about reference counts. must not be #NULL.
716 data: scalar to pass to func in addition to all other arguments.
718 the SV will be copied, so don't worry about reference counts. may
719 be #NULL.
720 n_params: the number of elements in param_types.
722 param_types: the #GType of each argument that should be passed from
724 the invocation to func. may be #NULL if n_params is zero, other‐
725 wise it must be n_params elements long or nasty things will happen.
726 this array will be copied; see gperl_callback_invoke() for how it
727 is used.
728 return_type: the #GType of the return value, or 0 if the function
730 has void return.
731 void gperl_callback_destroy (GPerlCallback * callback)
733 Dispose of callback.
734 void gperl_callback_invoke (GPerlCallback * callback, GValue *
736 return_value, ...)
737 Marshall the variadic parameters according to callback's
738 param_types, and then invoke callback's subroutine in scalar con‐
739 text, or void context if the return type is G_TYPE_VOID. If
740 return_value is not NULL, then value returned (if any) will be
741 copied into return_value.
742 A typical callback handler would look like this:
744 static gint
746 real_c_callback (Foo * f, Bar * b, int a, gpointer data)
747 {
748 GPerlCallback * callback = (GPerlCallback*)data;
749 GValue return_value = {0,};
750 gint retval;
751 g_value_init (&return_value, callback->return_type);
752 gperl_callback_invoke (callback, &return_value,
753 f, b, a);
754 retval = g_value_get_int (&return_value);
755 g_value_unset (&return_value);
756 return retval;
757 }
758 Exception Handling
760 Like Event, Tk, and most other callback-using, event-based perl mod‐
762 ules, Glib traps exceptions that happen in callbacks. To enable your
763 code to do something about these exceptions, Glib stores a list of
764 exception handlers which will be called on the trapped exceptions.
765 This is completely distinct from the $SIG{__DIE__} mechanism provided
766 by Perl itself, for various reasons (not the least of which is that the
767 Perl docs and source code say that $SIG{__DIE__} is intended for run‐
768 ning as the program is about to exit, and other behaviors may be
769 removed in the future (apparently a source of much debate on p5p)).
770 int gperl_install_exception_handler (GClosure * closure)
772 Install a GClosure to be executed when gperl_closure_invoke() traps
773 an exception. The closure should return boolean (TRUE if the han‐
774 dler should remain installed) and expect to receive a perl scalar.
775 This scalar will be a private copy of ERRSV ($@) which the handler
776 can mangle to its heart's content.
777 The return value is an integer id tag that may be passed to
779 gperl_removed_exception_handler().
780 void gperl_remove_exception_handler (guint tag)
782 Remove the exception handler identified by tag, as returned by
783 gperl_install_exception_handler(). If tag cannot be found, this
784 does nothing.
785 WARNING: this function locks a global data structure, so do NOT
787 call it recursively. also, calling this from within an exception
788 handler will result in a deadlock situation. if you want to remove
789 your handler just have it return FALSE.
790 void gperl_run_exception_handlers (void)
792 Invoke whatever exception handlers are installed. You will need
793 this if you have written a custom marshaler. Uses the value of the
794 global ERRSV.
795 GSignal
797 void gperl_signal_set_marshaller_for (GType instance_type, char *
799 detailed_signal, GClosureMarshal marshaller)
800 You need this function only in rare cases, usually as workarounds
801 for bad signal parameter types or to implement writable arguments.
802 Use the given marshaller to marshal all handlers for detailed_sig‐
803 nal on instance_type. "gperl_signal_connect" will look for mar‐
804 shallers registered here, and apply them to the GPerlClosure it
805 creates for the given callback being connected.
806 Use the helper macros in gperl_marshal.h to help write your mar‐
808 shaller function. That header, which is installed with the Glib
809 module but not #included through gperl.h, includes commentary and
810 examples which you should follow closely to avoid nasty bugs. Use
811 the Source, Luke.
812 WARNING: Bend over backwards and turn your head around 720 degrees
814 before attempting to write a GPerlClosure marshaller without using
815 the macros in gperl_marshal.h. If you absolutely cannot use those
816 macros, be certain to understand what those macros do so you can
817 get the semantics correct, and keep your code synchronized with
818 them, or you may miss very important bugfixes.
819 gulong gperl_signal_connect (SV * instance, char * detailed_signal, SV
821 * callback, SV * data, GConnectFlags flags)
822 The actual workhorse behind GObject::signal_connect, the binding
823 for g_signal_connect, for use from within XS. This creates a
824 "GPerlClosure" wrapper for the given callback and data, and con‐
825 nects that closure to the signal named detailed_signal on the given
826 GObject instance. This is only good for named signals. flags is
827 the same as for g_signal_connect(). data may be NULL, but callback
828 must not be.
829 Returns the id of the installed callback.
831
833 perlapi(1), perlguts(1), GLib Reference Manual, Glib(3pm),
834 Glib::devel(3pm).
835
837 This file was automatically generated from the source code of the Glib
838 module, which is maintained by the gtk2-perl team.
839
841 Copyright (C) 2003 by the gtk2-perl team (see the file AUTHORS for the
842 full list)
843 This library is free software; you can redistribute it and/or modify it
845 under the terms of the GNU Library General Public License as published
846 by the Free Software Foundation; either version 2.1 of the License, or
847 (at your option) any later version.
848 This library is distributed in the hope that it will be useful, but
850 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
851 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library
852 General Public License for more details.
853 You should have received a copy of the GNU Library General Public
855 License along with this library; if not, write to the Free Software
856 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307
857 USA.
858perl v5.8.8 2007-02-26 Glib::xsapi(3)