Plain Old Data (POD) types with or without a representation in the GType
type system can still have a copy and/or a free function. We should
allow annotating these types with their corresponding functions for
copying their data into a new instance, and freeing their data.
From a language bindings perspective, POD types should have a boxed
GType wrapper around them, so they can use the generic GBoxed API to
copy and free instances; from a documentation perspective, though, it'd
be good to have a way to match a structured type, like a struct or a
union, with its copy and free functions.
In order to do that, we add two new header block annotations:
- (copy-func function_name)
- (free-func function_name)
These annotations work exactly like ref-func and unref-func for typed
instances:
/**
* GdkRGBA: (copy-func gdk_rgba_copy)
* (free-func gdk_rgba_free)
* @red: ...
* @green: ...
* @blue: ...
* @alpha: ...
*
* ...
*/
The function is stored in the GIR data as two new attributes for the
`<record>` and `<union>` elements:
<record name="RGBA"
c:type="GdkRGBA"
copy-function="gdk_rgba_copy"
free-function="gdk_rgba_free"
glib:type-name="GdkRGBA"
glib:get-type="gdk_rgba_get_type"
c:symbol-prefix="gdk_rgba">
The annotations are not mandatory.
See: #14
The documentation comment for SimpleTypeBlob seemed to imply that a basic
type was embedded if the reserved fields were nonzero. After examining the
code, I believe that was actually due to some words missing, and the
comment should say that the type is embedded if the fields are zero.
A GObject property can be accessed generically through the GObject API,
e.g. g_object_set_property() and g_object_get_property(). Properties
typically also have public accessor functions, which are (according to
our own best practices) called through the generic API.
The introspection data is currently missing the relation between a
property and its public accessor functions. With this information, a
language binding could, for instance, avoid exposing the C API entirely,
thus minimizing the chances of collisions between property names and
accessor functions; alternatively, a binding could call the C API
directly instead of going through the generic GObject API, thus avoiding
the boxing and unboxing from a native type to a GIArgument and finally
into a GValue, and vice versa.
In the GIR, we add two new attributes to the `property` element:
- setter="SYMBOL"
- getter="SYMBOL"
where "symbol" is the C function identifier of the setter and getter
functions, respectively. The `setter` attribute is only applied to
writable, non-construct-only properties; the `getter` attribute is only
applied to readable properties.
We maintain the ABI compatibility of the typelib data by using 20 bits
of the 25 reserved bits inside the PropertyBlob structure. The data is
exposed through two new GIPropertyInfo methods:
- g_property_info_get_setter()
- g_property_info_get_getter()
which return the GIFunctionInfo for the setter and getter functions,
respectively.
A "final" class is a leaf node in a derivable type hierarchy, and cannot
be derived any further.
This matches the changes in libgobject that introduced G_TYPE_FLAG_FINAL
to the type flags.
The gtk-doc docs were including some bits of overal g-i docs but mostly unfinished
and outdated.
We now have the general docs in sphinx so remove the duplication and make the gtk-docs
just about the libgirepository API and nothing more.
This also renames some titles and fixes some missing links in the struct hierarchy
while at it.
Move things around and rename things until gtk-doc is happy.
This also moves the "Since" annotations to the next stable releases and
adds version added info for g_callable_info_get_instance_ownership_transfer()
and g_struct_info_find_field().
Add "n_field_callbacks" to ObjectBlob which represents the number of object
fields which are also callbacks. This a allows a constant time computation
for accessing sections after fields. Track writing of this field by passing
an extra argument through the girnode writers recursive call structure. This
essentally reverts a portion of commit 7027bb256d0d1ab which added a linear
time computation for accessing sections after fields.
Update typelib validator to also ensure n_field_callbacks is properly set.
https://bugzilla.gnome.org/show_bug.cgi?id=700338
Generalize "throws" attribute to SignatureBlob which can be used by all
callable blob types. Keep FunctionBlob and VFuncBlob throw attributes
around and functional for compatibility. Refactor girwriter.c to write
out throws attribute for all callable types.
Based on a patch by Simon Feltman.
https://bugzilla.gnome.org/show_bug.cgi?id=729543
Make it clear that both the dependencies field in the typelib, and the
include elements in the GIR AST, are for immediate dependencies, not
transitive ones.
https://bugzilla.gnome.org/show_bug.cgi?id=743782
This adds a header to the girepository library, which is then included
either directly or indirectly by the other headers so that all the public
symbols (and the 2 symbols in gitypelib-internal.h used by the tools) are
decorated by a macro, that can later be used to export the symbols and also
to be used to display compile-time warnings for usage of deprecated APIs,
which is like what is now being done in GLib (and GTK+, Clutter, and so
on).
This marks the first step that we begin to stop depending on the .symbols/
.def files to export the symbols.
https://bugzilla.gnome.org/show_bug.cgi?id=732669
Knowing the ownership transfer for instance parameters is
necessary for correct memory management of functions which
"eat" their instance argument, such as g_dbus_method_invocation_return_*.
Parse this information from the gir file and store in the
typelib, and then provide new API on GICallableInfo to
retrieve this.
https://bugzilla.gnome.org/show_bug.cgi?id=729662
- require GTK-Doc 1.19
- remove sgml mode
- automatically generate gi.types (needs GTK-Doc 1.19)
- fix https://bugzilla.gnome.org/show_bug.cgi?id=700025
[WIP] - rearange sections a bit
[WIP] - add gi-building, gi-programming sections
[WIP] - mark missing docs with TODO, which is only marginaly
better than nothing but at least can be grepped :)
https://bugzilla.gnome.org/show_bug.cgi?id=571648
When g_irepository_find_by_gtype() doesn't succeed on a simple prefix
match (the current 'fastpass' mechanism), it ends up taking a
considerable amount of CPU time, traversing the contents of all typelibs.
I imagine that the reasons to have the exhaustive search fallback are
not as strong as they used to be. For example, the case mentioned
(Clutter including Cogl) no longer seems to be true.
Also, typelibs (as generated by g-ir-scanner) now provide
comma-separated C prefix info for cases when the typelib includes
introspection info for multiple prefixes. For example, the Sugar typelib
has a c_prefix string of Sugar,EggSM,Gsm,Acme. So I imagine there are
not many remaining justified cases where the exhaustive search is needed.
With that in mind, I found two ways to optimize this function:
1. Support comma-separated C prefixes
2. Don't bother with an exhaustive search if we did find a typelib
claiming support for the prefix. For example, if we're looking for
GdkDeviceManagerXI2 (currently non-introspectable) and we already found
typelib files providing the 'Gdk' prefix that didn't offer this, lets
not bother with the exhaustive search, we aren't going to find anything.
It appears that cmph library can return (n+1) when querying item not
present in its original n-item-sized set. Adjust code so that it
detects this condition and do not chase stray pointers resulting from
this bogus(?) hash result.
https://bugzilla.gnome.org/show_bug.cgi?id=675939
The current source has invalid assumptions about structure alignment
that break on platforms like m68k where 32-bit integers are aligned to
16-bit only. Fix this by introducing explicit structure padding for
32-bit quantities following odd numbers of 16-bit quantities and
structure trail padding, to make the binary representation generated
by the compiler match the text of the specification exactly.
https://bugzilla.gnome.org/show_bug.cgi?id=661839
Virtual functions can definitely throw an error. Right now the
scanner omits the GError parameter for them and adds throws="1", but
g-ir-compiler ignores this.
https://bugzilla.gnome.org/show_bug.cgi?id=669332
This uses the same backcompat machinery that was introduced for static
methods for non-class types, so this change does not break users of the
existing presentations.
New libgirepository API:
g_enum_info_get_n_methods
g_enum_info_get_method
https://bugzilla.gnome.org/show_bug.cgi?id=656499
Instead of storing the name of the function to call to get the
error quark, store the string form of the error quark, which
we derive from the introspection binary during scanning.
Update EnumBlob and GIEnumInfo to include the new information.
This will allow determining a back-mapping from error quark
to error domain without having to dlsym() and call all the
known error quark functions.
Based on earlier patches from Owen Taylor and Maxim Ermilov.
https://bugzilla.gnome.org/show_bug.cgi?id=602516
The previous ErrorDomain blob was never actually scanned or used, and
it was kind of a lame API conceptually.
To keep some compatibility, rather than removing the enumeration
values, rename them to _INVALID, and don't bump the typelib version.
This should in theory allow a new libgirepository to read an old
typelib.
Based on a patch from Colin Walters
https://bugzilla.gnome.org/show_bug.cgi?id=602516
Use the internal perfect hashing API to add an index to the directory.
To support this, add the notion of additional "sections" to the
typelib. A section index is inserted between the header and the
directory.
https://bugzilla.gnome.org/show_bug.cgi?id=554943
In multiple places in the typelib, but most importantly the directory,
we need some fast indexing. Perfect hashing, as implemented by CMPH
(previous commit), is an exact fit for the problem domain.
Add an API built on top of CMPH which maps strings->guint16 (we just
need a guint16 for the typelib index).
https://bugzilla.gnome.org/show_bug.cgi?id=554943
The C compiler will pick an enumeration type that accomodates the specified
values for the enumeration, so ignoring 64-bit enumerations, we can
have enumeration values from MININT32 to MAXUINT32. To handle this properly:
- Use gint64 for holding eumeration values when scanning
- Add a 'unsigned_value' bit to ValueBlob so we can distinguish the
int32 vs. uint32 cases in the typelib
- Change the return value of g_value_info_get_value() to gint64.
https://bugzilla.gnome.org/show_bug.cgi?id=629704
This is a cleanup patch in preparation for future indexing
patches.
The lookup code was a mess trying to mash in the 3 different
cases of name, GType, and index into one mega-function.
Split it up properly, and move the core typelib internal-scanning
bits into gitypelib.c where it belongs.
This patch adds support for instantiable fundamental object types,
which are not GObject based. This is mostly interesting for being
able to support GstMiniObject's which are extensivly used in GStreamer.
Includes a big test case to the Everything module (inspired by
GstMiniObject) which should be used by language bindings who wishes to
test this functionallity.
This patch increases the size of the typelib and breaks compatibility
with older typelibs.
https://bugzilla.gnome.org/show_bug.cgi?id=568913
Any annotation where the key has a dot in the name will go into the
attribute list. For example
* @arg: (foo.bar baz): some arg
the parameter @arg will get the attribute with key foo.bar and value
baz. This also works for.
* Returns: (foo.bar2 baz2): the return value
Also add tests for this new feature.
See https://bugzilla.gnome.org/show_bug.cgi?id=571548
Signed-off-by: David Zeuthen <davidz@redhat.com>
* girepository/*: Add g_property_info_get_ownership_transfer() and write
the transfer attribute of properties into the typelib.
* giscanner/*: Parse the (transfer) annotation and write it into the .gir.
* tools/generate.c: Read the transfer annotation for properties and write
to the .tgir.
https://bugzilla.gnome.org/show_bug.cgi?id=620484
