1Glib::xsapi(3)        User Contributed Perl Documentation       Glib::xsapi(3)
2
3
4

NAME

6       Glib::xsapi - internal API reference for GPerl.
7

SYNOPSIS

9        #include <gperl.h>
10

DESCRIPTION

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
17       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

API

22   Miscellaneous
23       Various useful utilities defined in Glib.xs.
24
25       GPERL_CALL_BOOT(name)
26           call the boot code of a module by symbol rather than by name.
27
28           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
33       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
37           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
45       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
54           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
58       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
63       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
67       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
72       guint gperl_str_hash (gconstpointer key)
73           Like g_str_hash(), but considers '-' and '_' to be equivalent.
74
75       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
79           If the called function(s) modified argv, you can call
80           gperl_argv_update to update Perl's @ARGV in the same way.
81
82           Remember to call gperl_argv_free when you're done.
83
84       void gperl_argv_update (GPerlArgv *pargv)
85           Updates @ARGV to resemble the stored argv array.
86
87       void gperl_argv_free (GPerlArgv *pargv)
88           Frees any resources associated with pargv.
89
90       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
96       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
101       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
106   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
116       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
120       So, GPerl maps GLib's GError to Perl exceptions.
121
122       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
134       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
138       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
145           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
149       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
153       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() does
159           this, for example.)
160
161       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
166           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
170            PREINIT:
171              GError * error = NULL;
172            CODE:
173              if (!funtion_that_can_fail (something, &error))
174                 gperl_croak_gerror (NULL, error);
175
176           It's just that simple!
177
178   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
184       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
189       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
194           And, technically, this traps all the predefined log levels, not any
195           of the ones you (or your library) may define for yourself.
196
197   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
204       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
214           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
218       GPerlValueWrapperClass
219           Specifies the vtable that is to be used to convert fundamental
220           types to and from Perl variables.
221
222             typedef struct _GPerlValueWrapperClass GPerlValueWrapperClass;
223             struct _GPerlValueWrapperClass {
224                     GPerlValueWrapFunc   wrap;
225                     GPerlValueUnwrapFunc unwrap;
226             };
227
228           The members are function pointers, each of which serves a specific
229           purpose:
230
231           GPerlValueWrapFunc
232               Turns value into an SV.  The caller assumes ownership of the
233               SV.  value is not to be modified.
234
235                 typedef SV*  (*GPerlValueWrapFunc)   (const GValue * value);
236
237           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
244                 typedef void (*GPerlValueUnwrapFunc) (GValue       * value,
245                                                       SV           * sv);
246
247       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
254           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
259       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
263       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
267       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
272       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
277           you'll need this only in esoteric cases.
278
279       gint gperl_convert_enum (GType type, SV * val)
280           croak if val is not part of type, otherwise return corresponding
281           value
282
283       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
287       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
291       gboolean gperl_try_convert_flag (GType type, const char * val_p, gint *
292       val)
293           like gperl_try_convert_enum(), but for GFlags.
294
295       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
299       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
303       SV * gperl_convert_back_flags (GType type, gint val)
304           convert a bitfield to a list of strings.
305
306   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
313       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
319       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
323       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
327   Boxed type support for SV
328       In order to allow GValues to hold perl SVs we need a GBoxed wrapper.
329
330       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
335       SV * gperl_sv_copy (SV * sv)
336           implemented as "newSVsv (sv)".
337
338       void gperl_sv_free (SV * sv)
339           implemented as "SvREFCNT_dec (sv)".
340
341   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
348       These functions should be used instead of newSVpv and SvPV_nolen in all
349       cases which deal with gchar* types.
350
351       gchar * SvGChar (SV * sv)
352           extract a UTF8 string from sv.
353
354       SV * newSVGChar (const gchar * str)
355           copy a UTF8 string into a new SV.  if str is NULL, returns
356           &PL_sv_undef.
357
358   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
364       gint64 SvGInt64 (SV *sv)
365           Converts the string in sv to a signed 64 bit integer.  If
366           appropriate, uses "SvIV" instead.
367
368       SV * newSVGInt64 (gint64 value)
369           Creates a PV from the signed 64 bit integer in value.  If
370           appropriate, uses "newSViv" instead.
371
372       guint64 SvGUInt64 (SV *sv)
373           Converts the string in sv to an unsigned 64 bit integer.  If
374           appropriate, uses "SvUV" instead.
375
376       SV * newSVGUInt64 (guint64 value)
377           Creates a PV from the unsigned 64 bit integer in value.  If
378           appropriate, uses "newSVuv" instead.
379
380   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
385            typedef struct _GPerlBoxedWrapperClass GPerlBoxedWrapperClass;
386            struct _GPerlBoxedWrapperClass {
387                     GPerlBoxedWrapFunc    wrap;
388                     GPerlBoxedUnwrapFunc  unwrap;
389                     GPerlBoxedDestroyFunc destroy;
390            };
391
392           The members are function pointers, each of which serves a specific
393           purpose:
394
395           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
403                typedef SV*      (*GPerlBoxedWrapFunc)    (GType        gtype,
404                                                           const char * package,
405                                                           gpointer     boxed,
406                                                           gboolean     own);
407
408           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
414                typedef gpointer (*GPerlBoxedUnwrapFunc)  (GType        gtype,
415                                                           const char * package,
416                                                           SV         * sv);
417
418           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
425                typedef void     (*GPerlBoxedDestroyFunc) (SV         * sv);
426
427       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
434           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
444           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
448       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
456           In order for this to make sense, another package name should be
457           registered for type with gperl_register_boxed.
458
459       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
466           registered_gtype must have been registered with
467           gperl_register_boxed already.
468
469       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
473       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
477       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
483       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
492           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
496       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
500       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
505   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
514       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
520       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
524       Propers go to Marc Lehmann for dreaming most of this up.
525
526       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
531           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
536       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
544           In order for this to make sense, another package name should be
545           registered for type with gperl_register_object.
546
547       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
551           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
562           If no sinkfunc is found for an object, g_object_unref() will be
563           used.
564
565           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
572       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
586           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
593           Note: this assumes gtype has already been registered with
594           gperl_register_object().
595
596       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
603       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
607       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
611       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
621           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
635           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
644           Returns the blessed perl object, or #&PL_sv_undef if object was
645           #NULL.
646
647       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
651           Note, this one is not safe -- in general you want to use
652           gperl_get_object_check().
653
654       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
660       SV * gperl_object_check_type (SV * sv, GType gtype)
661           Essentially the same as gperl_get_object_check().
662
663           This croaks if the types aren't compatible.
664
665       typedef GObject GObject_noinc
666       typedef GObject GObject_ornull
667       newSVGObject(obj)
668       newSVGObject_noinc(obj)
669       SvGObject(sv)
670       SvGObject_ornull(sv)
671
672   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
678       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
682       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
686           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
691       SV * gperl_sv_from_value (const GValue * value)
692           Coerce whatever is in value into a perl scalar and return it.
693
694           Croaks if the code doesn't know how to perform the conversion.
695
696           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
700   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
706       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
710       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
716           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
720       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
728           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
737   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
746       additionally, generic callbacks aren't always kind to the GClosure
747       paradigm.
748
749       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
755       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
761       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
766           func: perl subroutine to call.  this SV will be copied, so don't
767           worry about reference counts.  must not be #NULL.
768
769           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
773           n_params: the number of elements in param_types.
774
775           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
781           return_type: the #GType of the return value, or 0 if the function
782           has void return.
783
784       void gperl_callback_destroy (GPerlCallback * callback)
785           Dispose of callback.
786
787       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
795           A typical callback handler would look like this:
796
797             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
811   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
822       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
829           The return value is an integer id tag that may be passed to
830           gperl_removed_exception_handler().
831
832       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
837           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
842       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
847   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
857           A canonical form of detailed_signal will be used so that marshaller
858           is applied for all possible spellings of the signal name.
859
860           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
866           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
873       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
883           Returns the id of the installed callback.
884

SEE ALSO

886       perlapi(1), perlguts(1), GLib Reference Manual, Glib(3pm),
887       Glib::devel(3pm).
888

AUTHORS

890       This file was automatically generated from the source code of the Glib
891       module, which is maintained by the gtk2-perl team.
892

LICENSE

894       Copyright (C) 2003 by the gtk2-perl team (see the file AUTHORS for the
895       full list)
896
897       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
902       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
907       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.
911
912
913
914perl v5.38.0                      2023-08-01                    Glib::xsapi(3)
Impressum