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 void gperl_hv_take_sv (HV *hv, const char *key, size_t key_length, SV
102 *sv)
103 Tries to store sv in hv. Decreases sv's reference count if
104 something goes wrong.
105 GError Exception Objects
107 GError is a facility for propagating run-time error / exception
108 information around in C, which is a language without native support for
109 exceptions. GError uses a simple error code, usually defined as an
110 enum. Since the enums will overlap, GError includes the GQuark
111 corresponding to a particular error "domain" to tell you which error
112 codes will be used. There's also a string containing a specific error
113 message. The strings are arbitrary, and may be translated, but the
114 domains and codes are definite.
115 Perl has native support for exceptions, using "eval" as "try", "croak"
117 or "die" as "throw", and "if ($@)" as "catch". $@ may, in fact, be any
118 scalar, including blessed objects.
119 So, GPerl maps GLib's GError to Perl exceptions.
121 Since, as we described above, error messages are not guaranteed to be
123 unique everywhere, we need to support the use of the error domains and
124 codes. The obvious choice here is to use exception objects; however,
125 to support blessed exception objects, we must perform a little bit of
126 black magic in the bindings. There is no built-in association between
127 an error domain quark and the GType of the corresponding error code
128 enumeration, so the bindings supply both of these when specifying the
129 name of the package into which to bless exceptions of this domain. All
130 GError-based exceptions derive from Glib::Error, of course, and this
131 base class provides all of the functionality, including
132 stringification.
133 All you'll really ever need to do is register error domains with
135 "gperl_register_error_domain", and throw errors with
136 "gperl_croak_gerror".
137 void gperl_register_error_domain (GQuark domain, GType error_enum,
139 const char * package)
140 Tell the bindings to bless GErrors with error->domain == domain
141 into package, and use error_enum to find the nicknames for the
142 error codes. This will call "gperl_set_isa" on package to add
143 "Glib::Error" to package's @ISA.
144 domain may not be 0, and package may not be NULL; what would be the
146 point? error_enum may be 0, in which case you'll get no fancy
147 stringified error values.
148 SV * gperl_sv_from_gerror (GError * error)
150 You should rarely, if ever, need to call this function. This is
151 what turns a GError into a Perl object.
152 gperl_gerror_from_sv (SV * sv, GError ** error)
154 You should rarely need this function. This parses a perl data
155 structure into a GError. If sv is undef (or the empty string),
156 sets *error to NULL, otherwise, allocates a new GError with
157 "g_error_new_literal()" and writes through error; the caller is
158 responsible for calling "g_error_free()". (gperl_croak_gerror()
159 does this, for example.)
160 void gperl_croak_gerror (const char * ignored, GError * err)
162 Croak with an exception based on err. err may not be NULL.
163 ignored exists for backward compatibility, and is, well, ignored.
164 This function calls croak(), which does not return.
165 Since croak() does not return, this function handles the magic
167 behind not leaking the memory associated with the #GError. To use
168 this you'd do something like
169 PREINIT:
171 GError * error = NULL;
172 CODE:
173 if (!funtion_that_can_fail (something, &error))
174 gperl_croak_gerror (NULL, error);
175 It's just that simple!
177 GLog
179 GLib has a message logging mechanism which it uses for the
180 g_return_if_fail() assertion macros, etc.; it's really versatile and
181 allows you to set various levels to be fatal and whatnot. Libraries
182 use these for various types of message reporting.
183 These functions let you reroute those messages from Perl. By default,
185 the warning, critical, and message levels go through perl's warn(), and
186 fatal ones go through croak(). [i'm not sure that these get to croak()
187 before GLib abort()s on them...]
188 gint gperl_handle_logs_for (const gchar * log_domain)
190 Route all g_logs for log_domain through gperl's log handling.
191 You'll have to register domains in each binding submodule, because
192 there's no way we can know about them down here.
193 And, technically, this traps all the predefined log levels, not any
195 of the ones you (or your library) may define for yourself.
196 GType / GEnum / GFlags
198 void gperl_register_fundamental (GType gtype, const char * package)
199 register a mapping between gtype and package. this is for
200 "fundamental" types which have no other requirements for metadata
201 storage, such as GEnums, GFlags, or real GLib fundamental types
202 like G_TYPE_INT, G_TYPE_FLOAT, etc.
203 void gperl_register_fundamental_alias (GType gtype, const char *
205 package)
206 Makes package an alias for type. This means that the package name
207 specified by package will be mapped to type by
208 gperl_fundamental_type_from_package, but
209 gperl_fundamental_package_from_type won't map type to package.
210 This is useful if you want to change the canonical package name of
211 a type while preserving backwards compatibility with code which
212 uses package to specify type.
213 In order for this to make sense, another package name should be
215 registered for type with gperl_register_fundamental or
216 gperl_register_fundamental_full.
217 GPerlValueWrapperClass
219 Specifies the vtable that is to be used to convert fundamental
220 types to and from Perl variables.
221 typedef struct _GPerlValueWrapperClass GPerlValueWrapperClass;
223 struct _GPerlValueWrapperClass {
224 GPerlValueWrapFunc wrap;
225 GPerlValueUnwrapFunc unwrap;
226 };
227 The members are function pointers, each of which serves a specific
229 purpose:
230 GPerlValueWrapFunc
232 Turns value into an SV. The caller assumes ownership of the
233 SV. value is not to be modified.
234 typedef SV* (*GPerlValueWrapFunc) (const GValue * value);
236 GPerlValueUnwrapFunc
238 Turns sv into its fundamental representation and stores the
239 result in the pre-configured value. value must not be
240 overwritten; instead one of the various "g_value_set_*()"
241 functions must be used or the "value->data" pointer must be
242 modified directly.
243 typedef void (*GPerlValueUnwrapFunc) (GValue * value,
245 SV * sv);
246 void gperl_register_fundamental_full (GType gtype, const char *
248 package, GPerlValueWrapperClass * wrapper_class)
249 Like gperl_register_fundamental, registers a mapping between gtype
250 and package. In addition, this also installs the function pointers
251 in wrapper_class as the handlers for the type. See
252 GPerlValueWrapperClass.
253 gperl_register_fundamental_full does not copy the contents of
255 wrapper_class -- it assumes that wrapper_class is statically
256 allocated and that it will be valid for the whole lifetime of the
257 program.
258 GType gperl_fundamental_type_from_package (const char * package)
260 look up the GType corresponding to a package registered by
261 gperl_register_fundamental().
262 const char * gperl_fundamental_package_from_type (GType gtype)
264 look up the package corresponding to a gtype registered by
265 gperl_register_fundamental().
266 GPerlValueWrapperClass * gperl_fundamental_wrapper_class_from_type
268 (GType gtype)
269 look up the wrapper class corresponding to a gtype that has
270 previously been registered with gperl_register_fundamental_full().
271 gboolean gperl_try_convert_enum (GType gtype, SV * sv, gint * val)
273 return FALSE if sv can't be mapped to a valid member of the
274 registered enum type gtype; otherwise, return TRUE write the new
275 value to the int pointed to by val.
276 you'll need this only in esoteric cases.
278 gint gperl_convert_enum (GType type, SV * val)
280 croak if val is not part of type, otherwise return corresponding
281 value
282 SV * gperl_convert_back_enum_pass_unknown (GType type, gint val)
284 return a scalar containing the nickname of the enum value val, or
285 the integer value of val if val is not a member of the enum type.
286 SV * gperl_convert_back_enum (GType type, gint val)
288 return a scalar which is the nickname of the enum value val, or
289 croak if val is not a member of the enum.
290 gboolean gperl_try_convert_flag (GType type, const char * val_p, gint *
292 val)
293 like gperl_try_convert_enum(), but for GFlags.
294 gint gperl_convert_flag_one (GType type, const char * val)
296 croak if val is not part of type, otherwise return corresponding
297 value.
298 gint gperl_convert_flags (GType type, SV * val)
300 collapse a list of strings to an integer with all the correct bits
301 set, croak if anything is invalid.
302 SV * gperl_convert_back_flags (GType type, gint val)
304 convert a bitfield to a list of strings.
305 Inheritance management
307 void gperl_set_isa (const char * child_package, const char *
308 parent_package)
309 tell perl that child_package inherits parent_package, after
310 whatever else is already there. equivalent to "push
311 @{$parent_package}::ISA, $child_package;"
312 void gperl_prepend_isa (const char * child_package, const char *
314 parent_package)
315 tell perl that child_package inherits parent_package, but before
316 whatever else is already there. equivalent to "unshift
317 @{$parent_package}::ISA, $child_package;"
318 GType gperl_type_from_package (const char * package)
320 Look up the GType associated with package, regardless of how it was
321 registered. Returns 0 if no mapping can be found.
322 const char * gperl_package_from_type (GType gtype)
324 Look up the name of the package associated with gtype, regardless
325 of how it was registered. Returns NULL if no mapping can be found.
326 Boxed type support for SV
328 In order to allow GValues to hold perl SVs we need a GBoxed wrapper.
329 GPERL_TYPE_SV
331 Evaluates to the GType for SVs. The bindings register a mapping
332 between GPERL_TYPE_SV and the package 'Glib::Scalar' with
333 gperl_register_boxed().
334 SV * gperl_sv_copy (SV * sv)
336 implemented as "newSVsv (sv)".
337 void gperl_sv_free (SV * sv)
339 implemented as "SvREFCNT_dec (sv)".
340 UTF-8 strings with gchar
342 By convention, gchar* is assumed to point to UTF8 string data, and
343 char* points to ascii string data. Here we define a pair of wrappers
344 for the boilerplate of upgrading Perl strings. They are implemented as
345 functions rather than macros, because comma expressions in macros are
346 not supported by all compilers.
347 These functions should be used instead of newSVpv and SvPV_nolen in all
349 cases which deal with gchar* types.
350 gchar * SvGChar (SV * sv)
352 extract a UTF8 string from sv.
353 SV * newSVGChar (const gchar * str)
355 copy a UTF8 string into a new SV. if str is NULL, returns
356 &PL_sv_undef.
357 64 bit integers
359 On 32 bit machines and even on some 64 bit machines, perl's IV/UV data
360 type can only hold 32 bit values. The following functions therefore
361 convert 64 bit integers to and from Perl strings if normal IV/UV
362 conversion does not suffice.
363 gint64 SvGInt64 (SV *sv)
365 Converts the string in sv to a signed 64 bit integer. If
366 appropriate, uses "SvIV" instead.
367 SV * newSVGInt64 (gint64 value)
369 Creates a PV from the signed 64 bit integer in value. If
370 appropriate, uses "newSViv" instead.
371 guint64 SvGUInt64 (SV *sv)
373 Converts the string in sv to an unsigned 64 bit integer. If
374 appropriate, uses "SvUV" instead.
375 SV * newSVGUInt64 (guint64 value)
377 Creates a PV from the unsigned 64 bit integer in value. If
378 appropriate, uses "newSVuv" instead.
379 GBoxed
381 GPerlBoxedWrapperClass
382 Specifies the vtable of functions to be used for bringing boxed
383 types in and out of perl. The structure is defined like this:
384 typedef struct _GPerlBoxedWrapperClass GPerlBoxedWrapperClass;
386 struct _GPerlBoxedWrapperClass {
387 GPerlBoxedWrapFunc wrap;
388 GPerlBoxedUnwrapFunc unwrap;
389 GPerlBoxedDestroyFunc destroy;
390 };
391 The members are function pointers, each of which serves a specific
393 purpose:
394 GPerlBoxedWrapFunc
396 turn a boxed pointer into an SV. gtype is the type of the
397 boxed pointer, and package is the package to which that gtype
398 is registered (the lookup has already been done for you at this
399 point). if own is true, the wrapper is responsible for freeing
400 the object; if it is false, some other code owns the object and
401 you must NOT free it.
402 typedef SV* (*GPerlBoxedWrapFunc) (GType gtype,
404 const char * package,
405 gpointer boxed,
406 gboolean own);
407 GPerlBoxedUnwrapFunc
409 turn an SV into a boxed pointer. like GPerlBoxedWrapFunc,
410 gtype and package are the registered type pair, already looked
411 up for you (in the process of finding the proper wrapper
412 class). sv is the sv to unwrap.
413 typedef gpointer (*GPerlBoxedUnwrapFunc) (GType gtype,
415 const char * package,
416 SV * sv);
417 GPerlBoxedDestroyFunc
419 this will be called by Glib::Boxed::DESTROY, when the wrapper
420 is destroyed. it is a hook that allows you to destroy an
421 object owned by the wrapper; note, however, that you will have
422 had to keep track yourself of whether the object was to be
423 freed.
424 typedef void (*GPerlBoxedDestroyFunc) (SV * sv);
426 void gperl_register_boxed (GType gtype, const char * package,
428 GPerlBoxedWrapperClass * wrapper_class)
429 Register a mapping between the GBoxed derivative gtype and package.
430 The specified, wrapper_class will be used to wrap and unwrap
431 objects of this type; you may pass NULL to use the default wrapper
432 (the same one returned by gperl_default_boxed_wrapper_class()).
433 In normal usage, the standard opaque wrapper supplied by the
435 library is sufficient and correct. In some cases, however, you
436 want a boxed type to map directly to a native perl type; for
437 example, some struct may be more appropriately represented as a
438 hash in perl. Since the most necessary place for this conversion
439 to happen is in gperl_value_from_sv() and gperl_sv_from_value(),
440 the only reliable and robust way to implement this is a hook into
441 gperl_get_boxed_check() and gperl_new_boxed(); that is exactly the
442 purpose of wrapper_class. See "GPerlBoxedWrapperClass".
443 gperl_register_boxed does not copy the contents of wrapper_class --
445 it assumes that wrapper_class is statically allocated and that it
446 will be valid for the whole lifetime of the program.
447 void gperl_register_boxed_alias (GType gtype, const char * package)
449 Makes package an alias for type. This means that the package name
450 specified by package will be mapped to type by
451 gperl_boxed_type_from_package, but gperl_boxed_package_from_type
452 won't map type to package. This is useful if you want to change
453 the canonical package name of a type while preserving backwards
454 compatibility with code which uses package to specify type.
455 In order for this to make sense, another package name should be
457 registered for type with gperl_register_boxed.
458 void gperl_register_boxed_synonym (GType registered_gtype, GType
460 synonym_gtype)
461 Registers synonym_gtype as a synonym for registered_gtype. All
462 boxed objects of type synonym_gtype will then be treated as if they
463 were of type registered_gtype, and gperl_boxed_package_from_type
464 will return the package associated with registered_gtype.
465 registered_gtype must have been registered with
467 gperl_register_boxed already.
468 GType gperl_boxed_type_from_package (const char * package)
470 Look up the GType associated with package package. Returns 0 if
471 type is not registered.
472 const char * gperl_boxed_package_from_type (GType type)
474 Look up the package associated with GBoxed derivative type.
475 Returns NULL if type is not registered.
476 GPerlBoxedWrapperClass * gperl_default_boxed_wrapper_class (void)
478 get a pointer to the default wrapper class; handy if you want to
479 use the normal wrapper, with minor modifications. note that you
480 can just pass NULL to gperl_register_boxed(), so you really only
481 need this in fringe cases.
482 SV * gperl_new_boxed (gpointer boxed, GType gtype, gboolean own)
484 Export a GBoxed derivative to perl, according to whatever
485 GPerlBoxedWrapperClass is registered for gtype. In the default
486 implementation, this means wrapping an opaque perl object around
487 the pointer to a small wrapper structure which stores some
488 metadata, such as whether the boxed structure should be destroyed
489 when the wrapper is destroyed (controlled by own; if the wrapper
490 owns the object, the wrapper is in charge of destroying it's data).
491 This function might end up calling other Perl code, so if you use
493 it in XS code for a generic GType, make sure the stack pointer is
494 set up correctly before the call, and restore it after the call.
495 SV * gperl_new_boxed_copy (gpointer boxed, GType gtype)
497 Create a new copy of boxed and return an owner wrapper for it.
498 boxed may not be NULL. See "gperl_new_boxed".
499 gpointer gperl_get_boxed_check (SV * sv, GType gtype)
501 Extract the boxed pointer from a wrapper; croaks if the wrapper sv
502 is not blessed into a derivative of the expected gtype. Does not
503 allow undef.
504 GObject
506 To deal with the intricate interaction of the different reference-
507 counting semantics of Perl objects versus GObjects, the bindings create
508 a combined PerlObject+GObject, with the GObject's pointer in magic
509 attached to the Perl object, and the Perl object's pointer in the
510 GObject's user data. Thus it's not really a "wrapper", but we refer to
511 it as one, because "combined Perl object + GObject" is a cumbersome and
512 confusing mouthful.
513 GObjects are represented as blessed hash references. The GObject user
515 data mechanism is not typesafe, and thus is used only for unsigned
516 integer values; the Perl-level hash is available for any type of user
517 data. The combined nature of the wrapper means that data stored in the
518 hash will stick around as long as the object is alive.
519 Since the C pointer is stored in attached magic, the C pointer is not
521 available to the Perl developer via the hash object, so there's no need
522 to worry about breaking it from perl.
523 Propers go to Marc Lehmann for dreaming most of this up.
525 void gperl_register_object (GType gtype, const char * package)
527 tell the GPerl type subsystem what Perl package corresponds with a
528 given GObject by GType. automagically sets up @package::ISA for
529 you.
530 note that @ISA will not be created for gtype until gtype's parent
532 has been registered. if you are experiencing strange problems with
533 a class' @ISA not being set up, change the order in which you
534 register them.
535 void gperl_register_object_alias (GType gtype, const char * package)
537 Makes package an alias for type. This means that the package name
538 specified by package will be mapped to type by
539 gperl_object_type_from_package, but gperl_object_package_from_type
540 won't map type to package. This is useful if you want to change
541 the canonical package name of a type while preserving backwards
542 compatibility with code which uses package to specify type.
543 In order for this to make sense, another package name should be
545 registered for type with gperl_register_object.
546 void gperl_register_sink_func (GType gtype, GPerlObjectSinkFunc func)
548 Tell gperl_new_object() to use func to claim ownership of objects
549 derived from gtype.
550 gperl_new_object() always refs a GObject when wrapping it for the
552 first time. To have the Perl wrapper claim ownership of a GObject
553 as part of gperl_new_object(), you unref the object after ref'ing
554 it. however, different GObject subclasses have different ways to
555 claim ownership; for example, GtkObject simply requires you to call
556 gtk_object_sink(). To make this concept generic, this function
557 allows you to register a function to be called when then wrapper
558 should claim ownership of the object. The func registered for a
559 given type will be called on any object for which "g_type_isa
560 (G_TYPE_OBJECT (object), type)" succeeds.
561 If no sinkfunc is found for an object, g_object_unref() will be
563 used.
564 Even though GObjects don't need sink funcs, we need to have them in
566 Glib as a hook for upstream objects. If we create a GtkObject (or
567 any other type of object which uses a different way to claim
568 ownership) via Glib::Object->new, any upstream wrappers, such as
569 gtk2perl_new_object(), will not be called. Having a sink func
570 facility down here enables us always to do the right thing.
571 void gperl_object_set_no_warn_unreg_subclass (GType gtype, gboolean
573 nowarn)
574 In versions 1.00 through 1.10x of Glib, the bindings required all
575 types to be registered ahead of time. Upon encountering an unknown
576 type, the bindings would emit a warning to the effect of "unknown
577 type 'Foo'; representing as first known parent type 'Bar'".
578 However, for some types, such as GtkStyle or GdkGC, the actual
579 object returned is an instance of a child type of a private
580 implementation (e.g., a theme engine ("BlueCurveStyle") or gdk
581 backend ("GdkGCX11")); we neither can nor should have registered
582 names for these types. Therefore, it is possible to tell the
583 bindings not to warn about these unregistered subclasses, and
584 simply represent them as the parent type.
585 With 1.12x, the bindings will automatically register unknown
587 classes into the namespace Glib::Object::_Unregistered to avoid
588 possible breakage resulting from unknown ancestors of known
589 children. To preserve the old registered-as-unregistered behavior,
590 the value installed by this function is used to prevent the
591 _Unregistered mapping for such private backend classes.
592 Note: this assumes gtype has already been registered with
594 gperl_register_object().
595 const char * gperl_object_package_from_type (GType gtype)
597 Get the package corresponding to gtype. If gtype is not a GObject
598 or GInterface, returns NULL. If gtype is not registered to a
599 package name, a new name of the form
600 "Glib::Object::_Unregistered::$c_type_name" will be created, used
601 to register the class, and then returned.
602 HV * gperl_object_stash_from_type (GType gtype)
604 Get the stash corresponding to gtype; returns NULL if gtype is not
605 registered. The stash is useful for "bless"ing.
606 GType gperl_object_type_from_package (const char * package)
608 Inverse of gperl_object_package_from_type(), returns 0 if package
609 is not registered.
610 SV * gperl_new_object (GObject * object, gboolean own)
612 Use this function to get the perl part of a GObject. If object has
613 never been seen by perl before, a new, empty perl object will be
614 created and added to a private key under object's qdata. If object
615 already has a perl part, a new reference to it will be created. The
616 gobject + perl object together form a combined object that is
617 properly refcounted, i.e. both parts will stay alive as long as at
618 least one of them is alive, and only when both perl object and
619 gobject are no longer referenced will both be freed.
620 The perl object will be blessed into the package corresponding to
622 the GType returned by calling G_OBJECT_TYPE() on object; if that
623 class has not been registered via gperl_register_object(), this
624 function will emit a warning to that effect (with warn()), and
625 attempt to bless it into the first known class in the object's
626 ancestry. Since Glib::Object is already registered, you'll get a
627 Glib::Object if you are lazy, and thus this function can fail only
628 if object isn't descended from GObject, in which case it croaks.
629 (In reality, if you pass a non-GObject to this function, you'll be
630 lucky if you don't get a segfault, as there's not really a way to
631 trap that.) In practice these warnings can be unavoidable, so you
632 can use gperl_object_set_no_warn_unreg_subclass() to quell them on
633 a class-by-class basis.
634 However, when perl code is calling a GObject constructor (any
636 function which returns a new GObject), call gperl_new_object() with
637 own set to %TRUE; this will cause the first matching sink function
638 to be called on the GObject to claim ownership of that object, so
639 that it will be destroyed when the perl object goes out of scope.
640 The default sink func is g_object_unref(); other types should
641 supply the proper function; e.g., GtkObject should use
642 gtk_object_sink() here.
643 Returns the blessed perl object, or #&PL_sv_undef if object was
645 #NULL.
646 GObject * gperl_get_object (SV * sv)
648 retrieve the GObject pointer from a Perl object. Returns NULL if
649 sv is not linked to a GObject.
650 Note, this one is not safe -- in general you want to use
652 gperl_get_object_check().
653 GObject * gperl_get_object_check (SV * sv, GType gtype);
655 croaks if sv is undef or is not blessed into the package
656 corresponding to gtype. use this for bringing parameters into
657 xsubs from perl. Returns the same as gperl_get_object() (provided
658 it doesn't croak first).
659 SV * gperl_object_check_type (SV * sv, GType gtype)
661 Essentially the same as gperl_get_object_check().
662 This croaks if the types aren't compatible.
664 typedef GObject GObject_noinc
666 typedef GObject GObject_ornull
667 newSVGObject(obj)
668 newSVGObject_noinc(obj)
669 SvGObject(sv)
670 SvGObject_ornull(sv)
671 GValue
673 GValue is GLib's generic value container, and it is because of GValue
674 that the run time type handling of GObject parameters and GClosure
675 marshaling can function, and most usages of these functions will be
676 from those two points.
677 Client code will run into uses for gperl_sv_from_value() and
679 gperl_value_from_sv() when trying to convert lists of parameters into
680 GValue arrays and the like.
681 gboolean gperl_value_from_sv (GValue * value, SV * sv)
683 set a value from a whatever is in sv. value must be initialized so
684 the code knows what kind of value to coerce out of sv.
685 Return value is always TRUE; if the code knows how to perform the
687 conversion, it croaks. (The return value is for backward
688 compatibility.) In reality, this really ought to always succeed; a
689 failed conversion should be considered a bug or unimplemented code!
690 SV * gperl_sv_from_value (const GValue * value)
692 Coerce whatever is in value into a perl scalar and return it.
693 Croaks if the code doesn't know how to perform the conversion.
695 Might end up calling other Perl code. So if you use this function
697 in XS code for a generic GType, make sure the stack pointer is set
698 up correctly before the call, and restore it after the call.
699 GClosure / GPerlClosure
701 GPerlClosure is a wrapper around the gobject library's GClosure with
702 special handling for marshalling perl subroutines as callbacks. This
703 is specially tuned for use with GSignal and stuff like io watch,
704 timeout, and idle handlers.
705 For generic callback functions, which need parameters but do not get
707 registered with the type system, this is sometimes overkill. See
708 GPerlCallback, below.
709 GClosure * gperl_closure_new (SV * callback, SV * data, gboolean swap)
711 Create and return a new GPerlClosure. callback and data will be
712 copied for storage; callback must not be NULL. If swap is TRUE,
713 data will be swapped with the instance during invocation (this is
714 used to implement g_signal_connect_swapped()).
715 If compiled under a thread-enabled perl, the closure will be
717 created and marshaled in such a way as to ensure that the same
718 interpreter which created the closure will be used to invoke it.
719 GClosure * gperl_closure_new_with_marshaller (SV * callback, SV * data,
721 gboolean swap, GClosureMarshal marshaller)
722 Like "gperl_closure_new", but uses a caller-supplied marshaller.
723 This is provided for use in those sticky circumstances when you
724 just can't do it any other way; in general, you want to use the
725 default marshaller, which you get if you provide NULL for
726 marshaller.
727 If you use you own marshaller, you need to take care of everything
729 yourself, including swapping the instance and data if
730 "GPERL_CLOSURE_SWAP_DATA (closure)" is true, calling
731 "gperl_run_exception_handlers" if ERRSV is true after invoking the
732 perl sub, and ensuring that you properly use the "marshal_data"
733 parameter as the perl interpreter when PERL_IMPLICIT_CONTEXT is
734 defined. See the implementation of the default marshaller,
735 "gperl_closure_marshal", in Glib/GClosure.xs for inspiration.
736 GPerlCallback
738 generic callback functions usually get invoked directly, and are not
739 passed parameter lists as GValues. we could very easily wrap up such
740 generic callbacks with something that converts the parameters to
741 GValues and then channels everything through GClosure, but this has two
742 problems: 1) the above implementation of GClosure is tuned to
743 marshalling signal handlers, which always have an instance object, and
744 2) it's more work than is strictly necessary.
745 additionally, generic callbacks aren't always kind to the GClosure
747 paradigm.
748 so, here's GPerlCallback, which is designed specifically to run generic
750 callback functions. it reads parameters off the C stack and converts
751 them into parameters on the perl stack. (it uses the GValue to/from SV
752 mechanism to do so, but doesn't allocate any temps on the heap.) the
753 callback object itself stores the parameter type list.
754 unfortunately, since the data element is always last, but the number of
756 arguments is not known until we have the callback object, we can't pass
757 gperl_callback_invoke directly to functions requiring a callback;
758 you'll have to write a proxy callback which calls
759 gperl_callback_invoke.
760 GPerlCallback * gperl_callback_new (SV * func, SV * data, gint
762 n_params, GType param_types[], GType return_type)
763 Create and return a new GPerlCallback; use gperl_callback_destroy
764 when you are finished with it.
765 func: perl subroutine to call. this SV will be copied, so don't
767 worry about reference counts. must not be #NULL.
768 data: scalar to pass to func in addition to all other arguments.
770 the SV will be copied, so don't worry about reference counts. may
771 be #NULL.
772 n_params: the number of elements in param_types.
774 param_types: the #GType of each argument that should be passed from
776 the invocation to func. may be #NULL if n_params is zero,
777 otherwise it must be n_params elements long or nasty things will
778 happen. this array will be copied; see gperl_callback_invoke() for
779 how it is used.
780 return_type: the #GType of the return value, or 0 if the function
782 has void return.
783 void gperl_callback_destroy (GPerlCallback * callback)
785 Dispose of callback.
786 void gperl_callback_invoke (GPerlCallback * callback, GValue *
788 return_value, ...)
789 Marshall the variadic parameters according to callback's
790 param_types, and then invoke callback's subroutine in scalar
791 context, or void context if the return type is G_TYPE_VOID. If
792 return_value is not NULL, then value returned (if any) will be
793 copied into return_value.
794 A typical callback handler would look like this:
796 static gint
798 real_c_callback (Foo * f, Bar * b, int a, gpointer data)
799 {
800 GPerlCallback * callback = (GPerlCallback*)data;
801 GValue return_value = {0,};
802 gint retval;
803 g_value_init (&return_value, callback->return_type);
804 gperl_callback_invoke (callback, &return_value,
805 f, b, a);
806 retval = g_value_get_int (&return_value);
807 g_value_unset (&return_value);
808 return retval;
809 }
810 Exception Handling
812 Like Event, Tk, and most other callback-using, event-based perl
813 modules, Glib traps exceptions that happen in callbacks. To enable
814 your code to do something about these exceptions, Glib stores a list of
815 exception handlers which will be called on the trapped exceptions.
816 This is completely distinct from the $SIG{__DIE__} mechanism provided
817 by Perl itself, for various reasons (not the least of which is that the
818 Perl docs and source code say that $SIG{__DIE__} is intended for
819 running as the program is about to exit, and other behaviors may be
820 removed in the future (apparently a source of much debate on p5p)).
821 int gperl_install_exception_handler (GClosure * closure)
823 Install a GClosure to be executed when gperl_closure_invoke() traps
824 an exception. The closure should return boolean (TRUE if the
825 handler should remain installed) and expect to receive a perl
826 scalar. This scalar will be a private copy of ERRSV ($@) which the
827 handler can mangle to its heart's content.
828 The return value is an integer id tag that may be passed to
830 gperl_removed_exception_handler().
831 void gperl_remove_exception_handler (guint tag)
833 Remove the exception handler identified by tag, as returned by
834 gperl_install_exception_handler(). If tag cannot be found, this
835 does nothing.
836 WARNING: this function locks a global data structure, so do NOT
838 call it recursively. also, calling this from within an exception
839 handler will result in a deadlock situation. if you want to remove
840 your handler just have it return FALSE.
841 void gperl_run_exception_handlers (void)
843 Invoke whatever exception handlers are installed. You will need
844 this if you have written a custom marshaler. Uses the value of the
845 global ERRSV.
846 GSignal
848 void gperl_signal_set_marshaller_for (GType instance_type, char *
849 detailed_signal, GClosureMarshal marshaller)
850 You need this function only in rare cases, usually as workarounds
851 for bad signal parameter types or to implement writable arguments.
852 Use the given marshaller to marshal all handlers for
853 detailed_signal on instance_type. "gperl_signal_connect" will look
854 for marshallers registered here, and apply them to the GPerlClosure
855 it creates for the given callback being connected.
856 A canonical form of detailed_signal will be used so that marshaller
858 is applied for all possible spellings of the signal name.
859 Use the helper macros in gperl_marshal.h to help write your
861 marshaller function. That header, which is installed with the Glib
862 module but not #included through gperl.h, includes commentary and
863 examples which you should follow closely to avoid nasty bugs. Use
864 the Source, Luke.
865 WARNING: Bend over backwards and turn your head around 720 degrees
867 before attempting to write a GPerlClosure marshaller without using
868 the macros in gperl_marshal.h. If you absolutely cannot use those
869 macros, be certain to understand what those macros do so you can
870 get the semantics correct, and keep your code synchronized with
871 them, or you may miss very important bugfixes.
872 gulong gperl_signal_connect (SV * instance, char * detailed_signal, SV
874 * callback, SV * data, GConnectFlags flags)
875 The actual workhorse behind GObject::signal_connect, the binding
876 for g_signal_connect, for use from within XS. This creates a
877 "GPerlClosure" wrapper for the given callback and data, and
878 connects that closure to the signal named detailed_signal on the
879 given GObject instance. This is only good for named signals.
880 flags is the same as for g_signal_connect(). data may be NULL, but
881 callback must not be.
882 Returns the id of the installed callback.
884
886 perlapi(1), perlguts(1), GLib Reference Manual, Glib(3pm),
887 Glib::devel(3pm).
888
890 This file was automatically generated from the source code of the Glib
891 module, which is maintained by the gtk2-perl team.
892
894 Copyright (C) 2003 by the gtk2-perl team (see the file AUTHORS for the
895 full list)
896 This library is free software; you can redistribute it and/or modify it
898 under the terms of the GNU Library General Public License as published
899 by the Free Software Foundation; either version 2.1 of the License, or
900 (at your option) any later version.
901 This library is distributed in the hope that it will be useful, but
903 WITHOUT ANY WARRANTY; without even the implied warranty of
904 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
905 Library General Public License for more details.
906 You should have received a copy of the GNU Library General Public
908 License along with this library; if not, write to the Free Software
909 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
910 02110-1301 USA.
911perl v5.34.0 2022-01-21 Glib::xsapi(3)