| Next: Gnome2 | Previous: Glib::version | [Gtk2-Perl - Table of Contents] | [Gtk2-Perl - Index] |
Glib::xsapi - internal API reference for GPerl.
#include <gperl.h>
This is the binding developer's API reference for GPerl, automatically generated from the xs source files. This header defines the public interface for use when creating new Perl language bindings for GLib-based C libraries.
gperl.h includes for you all the headers needed for writing XSUBs (EXTERN.h, perl.h, and XSUB.h), as well as all of GLib (via glib-object.h).
Various useful utilities defined in Glib.xs.
in a perl extension which uses several xs files but only one pm, you need to bootstrap the other xs files in order to get their functions exported to perl. if the file has MODULE = Foo::Bar, the boot symbol would be boot_Foo__Bar.
GPERL_CALL_BOOT.
for the curious, this calls a perl sub by function pointer rather than by name; call_sv requires that the xsub already be registered, but we need this to call a function which will register xsubs. this is an evil hack and should not be used outside of the GPERL_CALL_BOOT macro. it's implemented as a function to avoid code size bloat, and exported so that extension modules can pull the same trick.
Do not under any circumstances attempt to call g_free(), free(), or any other deallocator on this pointer, or you will crash the interpreter.
If the called function(s) modified argv, you can call gperl_argv_update to update Perl's @ARGV in the same way.
Remember to call gperl_argv_free when you're done.
GError is a facility for propagating run-time error / exception information around in C, which is a language without native support for exceptions. GError uses a simple error code, usually defined as an enum. Since the enums will overlap, GError includes the GQuark corresponding to a particular error "domain" to tell you which error codes will be used. There's also a string containing a specific error message. The strings are arbitrary, and may be translated, but the domains and codes are definite.
Perl has native support for exceptions, using eval as "try", croak or
die as "throw", and if ($@) as "catch". $@ may, in fact, be
any scalar, including blessed objects.
So, GPerl maps GLib's GError to Perl exceptions.
Since, as we described above, error messages are not guaranteed to be unique everywhere, we need to support the use of the error domains and codes. The obvious choice here is to use exception objects; however, to support blessed exception objects, we must perform a little bit of black magic in the bindings. There is no built-in association between an error domain quark and the GType of the corresponding error code enumeration, so the bindings supply both of these when specifying the name of the package into which to bless exceptions of this domain. All GError-based exceptions derive from Glib::Error, of course, and this base class provides all of the functionality, including stringification.
All you'll really ever need to do is register error domains with
gperl_register_error_domain, and throw errors with gperl_croak_gerror.
gperl_set_isa on package to add "Glib::Error" to
package's @ISA.
domain may not be 0, and package may not be NULL; what would be the point? error_enum may be 0, in which case you'll get no fancy stringified error values.
g_error_new_literal() and writes
through error; the caller is responsible for calling g_error_free().
(gperl_croak_gerror() does this, for example.)
Since croak() does not return, this function handles the magic behind not leaking the memory associated with the #GError. To use this you'd do something like
PREINIT:
GError * error = NULL;
CODE:
if (!funtion_that_can_fail (something, &error))
gperl_croak_gerror (NULL, error);
It's just that simple!
GLib has a message logging mechanism which it uses for the g_return_if_fail() assertion macros, etc.; it's really versatile and allows you to set various levels to be fatal and whatnot. Libraries use these for various types of message reporting.
These functions let you reroute those messages from Perl. By default, the warning, critical, and message levels go through perl's warn(), and fatal ones go through croak(). [i'm not sure that these get to croak() before GLib abort()s on them...]
And, technically, this traps all the predefined log levels, not any of the ones you (or your library) may define for yourself.
In order for this to make sense, another package name should be registered for type with gperl_register_fundamental or gperl_register_fundamental_full.
typedef struct _GPerlValueWrapperClass GPerlValueWrapperClass;
struct _GPerlValueWrapperClass {
GPerlValueWrapFunc wrap;
GPerlValueUnwrapFunc unwrap;
};
The members are function pointers, each of which serves a specific purpose:
typedef SV* (*GPerlValueWrapFunc) (const GValue * value);
g_value_set_*() functions must be used or the value->data
pointer must be modifed directly.
typedef void (*GPerlValueUnwrapFunc) (GValue * value,
SV * sv);
gperl_register_fundamental_full does not copy the contents of wrapper_class -- it assumes that wrapper_class is statically allocated and that it will be valid for the whole lifetime of the program.
you'll need this only in esoteric cases.
push @{$parent_package}::ISA, $child_package;
unshift @{$parent_package}::ISA, $child_package;
In order to allow GValues to hold perl SVs we need a GBoxed wrapper.
newSVsv (sv).
SvREFCNT_dec (sv).
By convention, gchar* is assumed to point to UTF8 string data, and char* points to ascii string data. Here we define a pair of wrappers for the boilerplate of upgrading Perl strings. They are implemented as functions rather than macros, because comma expressions in macros are not supported by all compilers.
These functions should be used instead of newSVpv and SvPV_nolen in all cases which deal with gchar* types.
On 32 bit machines and even on some 64 bit machines, perl's IV/UV data type can only hold 32 bit values. The following functions therefore convert 64 bit integers to and from Perl strings if normal IV/UV conversion does not suffice.
SvIV instead.
newSViv instead.
SvUV instead.
newSVuv instead.
typedef struct _GPerlBoxedWrapperClass GPerlBoxedWrapperClass;
struct _GPerlBoxedWrapperClass {
GPerlBoxedWrapFunc wrap;
GPerlBoxedUnwrapFunc unwrap;
GPerlBoxedDestroyFunc destroy;
};
The members are function pointers, each of which serves a specific purpose:
typedef SV* (*GPerlBoxedWrapFunc) (GType gtype,
const char * package,
gpointer boxed,
gboolean own);
typedef gpointer (*GPerlBoxedUnwrapFunc) (GType gtype,
const char * package,
SV * sv);
typedef void (*GPerlBoxedDestroyFunc) (SV * sv);
In normal usage, the standard opaque wrapper supplied by the library is
sufficient and correct. In some cases, however, you want a boxed type to map
directly to a native perl type; for example, some struct may be more
appropriately represented as a hash in perl. Since the most necessary place
for this conversion to happen is in gperl_value_from_sv() and
gperl_sv_from_value(), the only reliable and robust way to implement this
is a hook into gperl_get_boxed_check() and gperl_new_boxed(); that is
exactly the purpose of wrapper_class. See GPerlBoxedWrapperClass.
gperl_register_boxed does not copy the contents of wrapper_class -- it assumes that wrapper_class is statically allocated and that it will be valid for the whole lifetime of the program.
In order for this to make sense, another package name should be registered for type with gperl_register_boxed.
gperl_new_boxed.
To deal with the intricate interaction of the different reference-counting semantics of Perl objects versus GObjects, the bindings create a combined PerlObject+GObject, with the GObject's pointer in magic attached to the Perl object, and the Perl object's pointer in the GObject's user data. Thus it's not really a "wrapper", but we refer to it as one, because "combined Perl object + GObject" is a cumbersome and confusing mouthful.
GObjects are represented as blessed hash references. The GObject user data mechanism is not typesafe, and thus is used only for unsigned integer values; the Perl-level hash is available for any type of user data. The combined nature of the wrapper means that data stored in the hash will stick around as long as the object is alive.
Since the C pointer is stored in attached magic, the C pointer is not available to the Perl developer via the hash object, so there's no need to worry about breaking it from perl.
Propers go to Marc Lehmann for dreaming most of this up.
note that @ISA will not be created for gtype until gtype's parent has been registered. if you are experiencing strange problems with a class' @ISA not being set up, change the order in which you register them.
In order for this to make sense, another package name should be registered for type with gperl_register_object.
gperl_new_object() always refs a GObject when wrapping it for the first time.
To have the Perl wrapper claim ownership of a GObject as part of
gperl_new_object(), you unref the object after ref'ing it. however, different
GObject subclasses have different ways to claim ownership; for example,
GtkObject simply requires you to call gtk_object_sink(). To make this concept
generic, this function allows you to register a function to be called when then
wrapper should claim ownership of the object. The func registered for a
given type will be called on any object for which g_type_isa
(G_TYPE_OBJECT (object), type) succeeds.
If no sinkfunc is found for an object, g_object_unref() will be used.
Even though GObjects don't need sink funcs, we need to have them in Glib as a hook for upstream objects. If we create a GtkObject (or any other type of object which uses a different way to claim ownership) via Glib::Object->new, any upstream wrappers, such as gtk2perl_new_object(), will not be called. Having a sink func facility down here enables us always to do the right thing.
With 1.12x, the bindings will automatically register unknown classes into the namespace Glib::Object::_Unregistered to avoid possible breakage resulting from unknown ancestors of known children. To preserve the old registered-as-unregistered behavior, the value installed by this function is used to prevent the _Unregistered mapping for such private backend classes.
Note: this assumes gtype has already been registered with gperl_register_object().
Glib::Object::_Unregistered::$c_type_name
will be created, used to register the class, and then returned.
blessing.
The perl object will be blessed into the package corresponding to the GType returned by calling G_OBJECT_TYPE() on object; if that class has not been registered via gperl_register_object(), this function will emit a warning to that effect (with warn()), and attempt to bless it into the first known class in the object's ancestry. Since Glib::Object is already registered, you'll get a Glib::Object if you are lazy, and thus this function can fail only if object isn't descended from GObject, in which case it croaks. (In reality, if you pass a non-GObject to this function, you'll be lucky if you don't get a segfault, as there's not really a way to trap that.) In practice these warnings can be unavoidable, so you can use gperl_object_set_no_warn_unreg_subclass() to quell them on a class-by-class basis.
However, when perl code is calling a GObject constructor (any function which returns a new GObject), call gperl_new_object() with own set to %TRUE; this will cause the first matching sink function to be called on the GObject to claim ownership of that object, so that it will be destroyed when the perl object goes out of scope. The default sink func is g_object_unref(); other types should supply the proper function; e.g., GtkObject should use gtk_object_sink() here.
Returns the blessed perl object, or #&PL_sv_undef if object was #NULL.
Note, this one is not safe -- in general you want to use gperl_get_object_check().
This croaks if the types aren't compatible.
Client code will run into uses for gperl_sv_from_value() and gperl_value_from_sv() when trying to convert lists of parameters into GValue arrays and the like.
Return value is always TRUE; if the code knows how to perform the conversion, it croaks. (The return value is for backward compatibility.) In reality, this really ought to always succeed; a failed conversion should be considered a bug or unimplemented code!
Croaks if the code doesn't know how to perform the conversion.
GPerlClosure is a wrapper around the gobject library's GClosure with special handling for marshalling perl subroutines as callbacks. This is specially tuned for use with GSignal and stuff like io watch, timeout, and idle handlers.
For generic callback functions, which need parameters but do not get registered with the type system, this is sometimes overkill. See GPerlCallback, below.
If compiled under a thread-enabled perl, the closure will be created and marshaled in such a way as to ensure that the same interpreter which created the closure will be used to invoke it.
gperl_closure_new, but uses a caller-supplied marshaller. This is
provided for use in those sticky circumstances when you just can't do it
any other way; in general, you want to use the default marshaller, which you
get if you provide NULL for marshaller.
If you use you own marshaller, you need to take care of everything yourself,
including swapping the instance and data if GPERL_CLOSURE_SWAP_DATA
(closure) is true, calling gperl_run_exception_handlers if ERRSV is true
after invoking the perl sub, and ensuring that you properly use the
marshal_data parameter as the perl interpreter when PERL_IMPLICIT_CONTEXT is
defined. See the implementation of the default marshaller,
gperl_closure_marshal, in Glib/GClosure.xs for inspiration.
generic callback functions usually get invoked directly, and are not passed parameter lists as GValues. we could very easily wrap up such generic callbacks with something that converts the parameters to GValues and then channels everything through GClosure, but this has two problems: 1) the above implementation of GClosure is tuned to marshalling signal handlers, which always have an instance object, and 2) it's more work than is strictly necessary.
additionally, generic callbacks aren't always kind to the GClosure paradigm.
so, here's GPerlCallback, which is designed specifically to run generic callback functions. it reads parameters off the C stack and converts them into parameters on the perl stack. (it uses the GValue to/from SV mechanism to do so, but doesn't allocate any temps on the heap.) the callback object itself stores the parameter type list.
unfortunately, since the data element is always last, but the number of arguments is not known until we have the callback object, we can't pass gperl_callback_invoke directly to functions requiring a callback; you'll have to write a proxy callback which calls gperl_callback_invoke.
func: perl subroutine to call. this SV will be copied, so don't worry about reference counts. must not be #NULL.
data: scalar to pass to func in addition to all other arguments. the SV will be copied, so don't worry about reference counts. may be #NULL.
n_params: the number of elements in param_types.
param_types: the #GType of each argument that should be passed from the invocation to func. may be #NULL if n_params is zero, otherwise it must be n_params elements long or nasty things will happen. this array will be copied; see gperl_callback_invoke() for how it is used.
return_type: the #GType of the return value, or 0 if the function has void return.
A typical callback handler would look like this:
static gint
real_c_callback (Foo * f, Bar * b, int a, gpointer data)
{
GPerlCallback * callback = (GPerlCallback*)data;
GValue return_value = {0,};
gint retval;
g_value_init (&return_value, callback->return_type);
gperl_callback_invoke (callback, &return_value,
f, b, a);
retval = g_value_get_int (&return_value);
g_value_unset (&return_value);
return retval;
}
Like Event, Tk, and most other callback-using, event-based perl modules, Glib traps exceptions that happen in callbacks. To enable your code to do something about these exceptions, Glib stores a list of exception handlers which will be called on the trapped exceptions. This is completely distinct from the $SIG{__DIE__} mechanism provided by Perl itself, for various reasons (not the least of which is that the Perl docs and source code say that $SIG{__DIE__} is intended for running as the program is about to exit, and other behaviors may be removed in the future (apparently a source of much debate on p5p)).
The return value is an integer id tag that may be passed to gperl_removed_exception_handler().
WARNING: this function locks a global data structure, so do NOT call it recursively. also, calling this from within an exception handler will result in a deadlock situation. if you want to remove your handler just have it return FALSE.
gperl_signal_connect will look for marshallers
registered here, and apply them to the GPerlClosure it creates for the given
callback being connected.
Use the helper macros in gperl_marshal.h to help write your marshaller function. That header, which is installed with the Glib module but not #included through gperl.h, includes commentary and examples which you should follow closely to avoid nasty bugs. Use the Source, Luke.
WARNING: Bend over backwards and turn your head around 720 degrees before attempting to write a GPerlClosure marshaller without using the macros in gperl_marshal.h. If you absolutely cannot use those macros, be certain to understand what those macros do so you can get the semantics correct, and keep your code synchronized with them, or you may miss very important bugfixes.
GPerlClosure
wrapper for the given callback and data, and connects that closure to the
signal named detailed_signal on the given GObject instance. This is only
good for named signals. flags is the same as for g_signal_connect().
data may be NULL, but callback must not be.
Returns the id of the installed callback.
perlapi(1), perlguts(1), GLib Reference Manual, Glib(3pm), Glib::devel(3pm).
This file was automatically generated from the source code of the Glib module, which is maintained by the gtk2-perl team.
Copyright (C) 2003 by the gtk2-perl team (see the file AUTHORS for the full list)
This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details.
You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307 USA.