Commit Graph

180 Commits

Author SHA1 Message Date
Emmanuele Bassi
f62622fc7b docs: Start stanzas with a single paragraph
When rendering the contents of the GLib documentation stored inside the
introspection data, a common behaviour is to take the first paragraph as
a summary of the symbol being documented.

The documentation is assumed to be in Markdown format, which means:

 - paragraphs must be separated by newlines
 - lines that have an indentation of four or more spaces are considered
   code blocks
 - lines that start with a `#` are considered titles

This means we need to slightly tweak the documentation in our sources to
ensure that it can be rendered appropriately by tools that are not
gtk-doc.

See issue: #2365
2021-08-02 13:22:23 +01:00
Emmanuele Bassi
d1861c8fda Add G_DEFINE_* macros for final types
These should match the G_DECLARE_FINAL_* macros used in a header file.
2021-07-26 20:13:32 +01:00
Emmanuele Bassi
c07dd416cf gtype: Add a "final" flag
We want to have the ability to mark types that should not be derivable
even if they are in a deeply derivable type hierarchy; in other words,
leaf nodes in the types tree.
2021-07-26 20:13:32 +01:00
DarkTrick
ea365b7ea6 g_boxed_type_register_static: added reference to G_DEFINE_BOXED_TYPE 2021-07-22 12:16:41 +00:00
Nishal Kulkarni
98050b756b gtype: use G_GNUC_CHECK_VERSION
Replace `__GLIBC__` with `G_GNUC_CHECK_VERSION`
2021-04-29 17:40:14 +05:30
Philip Withnall
d4a875d8cd gtype: Improve formatting of GType documentation
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
2021-01-20 15:42:55 +00:00
Philip Withnall
fab561f8d0 gobject: Drop use of volatile from get_type() macros
http://isvolatileusefulwiththreads.in/c/

It’s possible that the variables here are only marked as volatile
because they’re arguments to `g_once_*()`. Those arguments will be
modified in a subsequent commit.

Signed-off-by: Philip Withnall <pwithnall@endlessos.org>

Helps: #600
2020-11-20 14:40:19 +00:00
Sebastian Dröge
ddef9ba2f8 Merge branch 'instantiatable' into 'master'
gobject: Standardise on the term ‘instantiatable’

See merge request GNOME/glib!1735
2020-11-13 15:29:07 +00:00
Benjamin Otte
98f0a5a7da gtype: Add g_type_interface_instantiatable_prerequisite()
This function returns the most specific instantiatable type
that is a prerequisite for a given interface.

This type is necessary in particular when dealing with GValues
because a GValue contains an instance of a type.

This commit includes tests for the new API.
2020-11-02 17:36:18 +00:00
Philip Withnall
4f2b1e250d gobject: Standardise on the term ‘instantiatable’
Rather than using a mixture of ‘instantiable’ and ‘instantiatable’
everywhere, standardise on the term which is already in the public API.

Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
2020-11-02 17:22:01 +00:00
Edward Hervey
898baa07b1 gobject: Handle runtime checks as such
The various `g_strdup_printf()` returns values in the implementations of GValue
lcopy_func are runtime checks which could be disabled if one wants and therefore
should be handled as such with g_return_val_if_fail()
2020-05-20 17:37:46 +02:00
Marco Trevisan (Treviño)
ab25fa42cc gtype: Define auto-cleanup functions for Module class
While we automatically define cleanup functions for the module, we don't
do it for the module class.

This will allow to manage the ownership of the class when reffing it
without having to cast it to GTypeClass.
2019-12-13 20:07:51 +01:00
Benjamin Otte
276e927fd4 Revert last 4 commits
This reverts commits:
  5899c61ed2
  e994d45352
  eb20dec144
  ebec0dd359
which wer accidentally pushed to master instead of a branch
2019-11-26 00:54:15 +01:00
Benjamin Otte
eb20dec144 gtype: Add g_type_interface_instantiable_prerequisite()
There is (at most) a single GType that is instantiable and a
prerequisite for an interface. This function returns that type.

This type is necessary in particular when dealing with GValues because a
GValue contains an instance of a type.
2019-11-25 20:06:39 +01:00
Matthew Waters
90f93a64f2 gtype: mark the inline functions in G_DECLARE_*_TYPE() as UNUSED
clang will warn about static inline functions where gcc will not.  Fixes
-Werror=unused-function with clang in dependant projects.
2019-08-28 18:08:29 +10:00
Emmanuele Bassi
4d73e1f014 Use GitLab to reserve a new fundamental type slot
Even though you *really* shouldn't do that at all.
2019-07-23 11:27:30 +01:00
Emmanuel Fleury
79da3551e3 Fix typo in G_DECLARE_DERIVABLE_TYPE documentation
Closes issue #1838
2019-07-20 16:05:12 +02:00
Emmanuele Bassi
87016536a6 Improve the documentation for G_DEFINE_TYPE_WITH_PRIVATE
Connect the dots between G_ADD_PRIVATE and the various G_DEFINE_* macros
that use it, as well as expanding the code example for
G_DEFINE_TYPE_EXTENDED with a private instance data declaration.

Closes: #943
2019-07-14 17:50:35 +01:00
Philip Withnall
40ff475977 Annotate various types and macros as deprecated
These have all been documented as deprecated for a long time, but we’ve
never had a way to programmatically mark them as deprecated. Do that
now.

This is based on the list of deprecations from the reverted commit
80fcb1bc2.

Signed-off-by: Philip Withnall <withnall@endlessm.com>

Fixes: #638
2019-05-30 10:39:11 +01:00
Emmanuele Bassi
e5ba5845a1 Revert "headers: Add various missing G_DISABLE_DEPRECATED guards"
This reverts commit 80fcb1bc26.

G_DISABLE_DEPRECATED should never be used by anybody, least of all by
GLib. We have deprecation annotations for the compiler, these days, and
they are much better suited than a macro that makes symbols appear and
disappear. The fact that gtk-doc doesn't understand the deprecation
annotations is a limitation of gtk-doc, and it's gtk-doc that ought to be
fixed.

Commit 80fcb1bc broke GStreamer, which disables old API that was
deprecated before the introduction of the deprecation annotations, but
still uses newly deprecated one, and relies on the deprecation
annotations to do their thing. It also broke libsoup, as it uses
GValueArray in its own API.
2019-03-16 11:30:13 +00:00
Philip Withnall
80fcb1bc26 headers: Add various missing G_DISABLE_DEPRECATED guards
As pointed out by gtk-doc, these are all symbols which have been marked
as deprecated, but which aren’t protected by a deprecation guard. We
can’t use G_DEPRECATED_IN_* for them, as they are all non-function
symbols. Instead, wrap them in #ifndef G_DISABLE_DEPRECATED.

In some cases, we also need to wrap one or two functions which use the
deprecated types in G_DISABLE_DEPRECATED too.

Signed-off-by: Philip Withnall <withnall@endlessm.com>
2019-03-15 11:09:32 +00:00
Emmanuele Bassi
4f5f34689f Merge branch 'interface-docs' into 'master'
gtype: Clarify type of GInterfaceInitFunc

See merge request GNOME/glib!512
2019-01-07 14:40:44 +00:00
Philip Withnall
154b24c055 gtype: Document type for iface_default_init() function
And mention why it’s not a GInterfaceInitFunc as people who have read
the GObject docs cover-to-cover might expect.

Signed-off-by: Philip Withnall <withnall@endlessm.com>
2018-12-27 23:46:42 +00:00
Kouhei Sutou
b8ac6e146a Suppress -Wint-in-bool-context warning with G_DEFINE_INTERFACE and g++
Note that it's not reported with gcc. It's only reported with g++.

C++ code to reproduce this warning:

    #include <glib-object.h>

    G_BEGIN_DECLS

    #define GARROW_TYPE_FILE (garrow_file_get_type())
    G_DECLARE_INTERFACE(GArrowFile,
                        garrow_file,
                        GARROW,
                        FILE,
                        GObject)

    struct _GArrowFileInterface {
      GTypeInterface g_iface;
    };

    G_DEFINE_INTERFACE(GArrowFile,
                       garrow_file,
                       G_TYPE_OBJECT)

    static void
    garrow_file_default_init(GArrowFileInterface *iface)
    {
    }

    G_END_DECLS

Build command line:

    % g++ -Wall -shared -o liba.so a.cpp $(pkg-config --cflags --libs gobject-2.0)

Message:

    In file included from /tmp/local.glib/include/glib-2.0/gobject/gobject.h:24,
                     from /tmp/local.glib/include/glib-2.0/gobject/gbinding.h:29,
                     from /tmp/local.glib/include/glib-2.0/glib-object.h:23,
                     from a.cpp:1:
    a.cpp: In function 'GType garrow_file_get_type()':
    /tmp/local.glib/include/glib-2.0/gobject/gtype.h:219:50: warning: '<<' in boolean context, did you mean '<' ? [-Wint-in-bool-context]
     #define G_TYPE_MAKE_FUNDAMENTAL(x) ((GType) ((x) << G_TYPE_FUNDAMENTAL_SHIFT))
                                                 ~~~~~^~~~~~~~~~~~~~~~~~~~~~~~~~~~
    /tmp/local.glib/include/glib-2.0/gobject/gtype.h:2026:11: note: in definition of macro '_G_DEFINE_INTERFACE_EXTENDED_BEGIN'
           if (TYPE_PREREQ) \
               ^~~~~~~~~~~
    /tmp/local.glib/include/glib-2.0/gobject/gtype.h:1758:47: note: in expansion of macro 'G_DEFINE_INTERFACE_WITH_CODE'
     #define G_DEFINE_INTERFACE(TN, t_n, T_P)      G_DEFINE_INTERFACE_WITH_CODE(TN, t_n, T_P, ;)
                                                   ^~~~~~~~~~~~~~~~~~~~~~~~~~~~
    a.cpp:16:1: note: in expansion of macro 'G_DEFINE_INTERFACE'
     G_DEFINE_INTERFACE(GArrowFile,
     ^~~~~~~~~~~~~~~~~~
    /tmp/local.glib/include/glib-2.0/gobject/gtype.h:178:25: note: in expansion of macro 'G_TYPE_MAKE_FUNDAMENTAL'
     #define G_TYPE_OBJECT   G_TYPE_MAKE_FUNDAMENTAL (20)
                             ^~~~~~~~~~~~~~~~~~~~~~~
    a.cpp:18:20: note: in expansion of macro 'G_TYPE_OBJECT'
                        G_TYPE_OBJECT)
                        ^~~~~~~~~~~~~
2018-12-20 11:24:53 +09:00
Philip Withnall
21adb30a83 gtype: Clarify type of GInterfaceInitFunc
When passing a function to G_IMPLEMENT_INTERFACE, it actually has to
take two arguments. Who knew?

Signed-off-by: Philip Withnall <withnall@endlessm.com>
2018-12-05 14:09:35 +00:00
Emmanuele Bassi
7e5db31d36 Deprecate g_type_class_add_private()
It's been 4 years and 8 development cycles since we introduced
G_ADD_PRIVATE and offset-based private data access. It is now
time to finally deprecate the old mechanism.

Closes: #699
2018-06-14 11:33:53 +01:00
Christian Hergert
e924f77736 gtype: improve get_type fast path
The -fstack-protector-strong used in many distributions by default has a
rather drastic slowdown of the fast path in generated _get_type()
functions using G_DEFINE_* macros. The amount can vary by architecture,
GCC version, and compiler flags.

To work around this, and ensure a higher probability that our fast-path
will match what we had previously, we need to break out the slow-path
(registering the type) into a secondary function that is not a candidate
for inlining.

This ensures that the common case (type registered, return the GType id)
is the hot path and handled in the prologue of the generated assembly even
when -fstack-protector-strong is enabled.

https://bugzilla.gnome.org/show_bug.cgi?id=795180
2018-05-09 12:25:06 +01:00
Philip Withnall
55e1c6185f gtype: Fix use of potentially undefined GVoidFunc
It’s defined in gutils.h, but various users of GLib might not have
access to that.

Signed-off-by: Philip Withnall <withnall@endlessm.com>
Reviewed-by: nobody

https://bugzilla.gnome.org/show_bug.cgi?id=793272
2018-02-16 17:42:55 +00:00
Lubomir Rintel
c1f5e52844 gtype: cast *_init functions to void(*)(void) first
The *_init() functions have prototypes incompatible with *InitFunc types they
are being cast to. This upsets GCC 8's -Wcast-function-type that's enabled by
default with -Wextra.

Let's not have the public header files emit a warning and neutralize it by
doing a void(*)(void) cast first.

https://bugzilla.gnome.org/show_bug.cgi?id=793272
2018-02-16 15:48:15 +00:00
Simon McVittie
0c0b1bdd0a g_type_check_value, g_type_check_value_holds: accept const argument
Conceptually, these functions clearly ought to be fine for a const
structure. This avoids _G_TYPE_CVH (the implementation of
G_TYPE_CHECK_VALUE_TYPE, G_VALUE_HOLDS, G_VALUE_HOLDS_BOXED etc.)
needing to cast to a mutable GValue, which causes
G_VALUE_HOLDS (cv, type) to issue warnings under gcc -Wcast-qual if
cv is a const GValue *.

https://bugzilla.gnome.org/show_bug.cgi?id=734479
2017-12-13 17:15:16 +00:00
Colin Walters
017f78d77f gtype: Add private DEFINE_TYPE with prelude to workaround gtype deadlocks
And use it in GSocket, as it had a real-world case reported.

https://bugzilla.gnome.org/show_bug.cgi?id=674885
2017-06-14 14:45:45 -04:00
Sébastien Wilmet
6b948d9613 gobject/: LGPLv2+ -> LGPLv2.1+
All gobject/*.{c,h} files have been processed.

gmarshal.c and gmarshal.h don't have a license header.

https://bugzilla.gnome.org/show_bug.cgi?id=776504
2017-05-24 11:58:19 +02:00
Philip Withnall
953c182d25 gobject: Document behaviour of GType checking macros on NULL
The macros differ in their handling of NULL values — some macros ignore
them and pass through (e.g. G_TYPE_CHECK_INSTANCE_CAST) while others
will explicitly emit a warning if passed NULL (e.g.
G_TYPE_CHECK_INSTANCE).

Document their behaviour, so people don’t end up putting unnecessary
NULL checks in their code when doing checked type casts.

https://bugzilla.gnome.org/show_bug.cgi?id=735731
2017-01-07 23:43:06 +00:00
Emmanuele Bassi
85a23529ab Revert "make *_get_instance_private const-compliant"
This reverts commit a3a9664ed2.

Constifying the autogenerated get_instance_private functio makes C++
compilers and GCC with -Wcast-qual warn during compilation of GLib and
projects depending on GLib.

Since using const with GObject instances is not a common coding
practice, it's better to revert than trying to make every sigle GType
function const-safe (and possibly add more compiler warnings in the
process).

https://bugzilla.gnome.org/show_bug.cgi?id=745068
2016-01-18 18:48:42 +00:00
Emmanuele Bassi
617189f28c Revert "G_DECLARE_*: be const-compliant"
This reverts commit 52f23db74a.

Constifying these macros make C++ compilers and GCC with -Wcast-qual
warn during compilation of GLib and projects depending on GLib.

Since using const with GObject instances is not a common coding
practice, it's better to revert than trying to make every sigle GType
function const-safe (and possibly add more compiler warnings in the
process).

https://bugzilla.gnome.org/show_bug.cgi?id=745068
2016-01-18 18:46:12 +00:00
Philip Withnall
25a7c817d3 glib: Add missing (nullable) and (optional) annotations
Add various (nullable) and (optional) annotations which were missing
from a variety of functions. Also port a couple of existing (allow-none)
annotations in the same files to use (nullable) and (optional) as
appropriate instead.

Secondly, add various (not nullable) annotations as needed by the new
default in gobject-introspection of marking gpointers as (nullable). See
https://bugzilla.gnome.org/show_bug.cgi?id=729660.

This includes adding some stub documentation comments for the
assertion macro error functions, which weren’t previously documented.
The new comments are purely to allow for annotations, and hence are
marked as (skip) to prevent the symbols appearing in the GIR file.

https://bugzilla.gnome.org/show_bug.cgi?id=719966
2015-11-07 10:48:32 +01:00
Xavier Claessens
32811598f3 doc: clarify that _get_instance_private() is NULL-safe
https://bugzilla.gnome.org/show_bug.cgi?id=755083
2015-09-22 11:15:19 -04:00
Emmanuele Bassi
5e7e058a9c docs: Add an example of G_DEFINE_BOXED_TYPE
Mention that the GType of the boxed type is stored inside the
g_define_type_id variable.

See bug: https://bugzilla.gnome.org/show_bug.cgi?id=723394
2015-05-25 14:02:43 +01:00
Marc-Antoine Perennou
a3a9664ed2 make *_get_instance_private const-compliant
This is pure read-only access to an external struct
so void warnings for people calling it from const
contexts such as accessors

https://bugzilla.gnome.org/show_bug.cgi?id=745068

Signed-off-by: Marc-Antoine Perennou <Marc-Antoine@Perennou.com>
2015-02-27 08:51:08 +01:00
Marc-Antoine Perennou
52f23db74a G_DECLARE_*: be const-compliant
switching to the old macros boilerplate to G_DECLARE_*
a lot of warnings start to pop when *_IS_A_* or such are
called from a const context.
Fix this by taking const pointers as parameters

https://bugzilla.gnome.org/show_bug.cgi?id=745068

Signed-off-by: Marc-Antoine Perennou <Marc-Antoine@Perennou.com>
2015-02-27 08:51:08 +01:00
Xavier Claessens
3d39b8eb01 Add G_DECLARE_INTERFACE
https://bugzilla.gnome.org/show_bug.cgi?id=743939
2015-02-06 12:18:37 +01:00
Xavier Claessens
6a97275c45 docs: fix many documentation issues in gobject/ 2015-02-05 16:01:17 +01:00
Xavier Claessens
2b536d3cbb docs: fix typos in G_DECLARE_*_TYPE
https://bugzilla.gnome.org/show_bug.cgi?id=743656
2015-02-03 15:57:54 +01:00
Chun-wei Fan
6161b285da gtype.h: Fix Build on non-GCC
Use the (private) _GLIB_DEFINE_AUTOPTR_CHAINUP macro for
G_DECLARE_DERIVABLE_TYPE and G_DECLARE_FINAL_TYPE so that we will
attempt to typedef and define items necessary for GCC
__attribute__((cleanup)) on, well, GCC only.

This fixes the build on non-GCC.

https://bugzilla.gnome.org/show_bug.cgi?id=743640
2015-02-03 20:20:46 +08:00
Chun-wei Fan
407adc6ea1 gobject\gtype.h: Make up for Missing '\'
The macro definition for G_DECLARE_DERIVABLE_TYPE was missing a '\' when
we wanted to ignore deprecation warnings for it.
2015-02-02 11:16:29 +08:00
Ryan Lortie
8ea414c8c6 G_DECLARE_*_TYPE: add auto cleanup support
Automatically add support for the new cleanup macros to the type
declaration macros.

This is an API break because now your parent class needs to support
cleanup if you want to use G_DECLARE_*_TYPE.  These macros are only 1
day old, however, so that's probably not a big problem (and we are
already busy adding the macros all over GLib and Gtk+).

https://bugzilla.gnome.org/show_bug.cgi?id=743640
2015-01-30 16:52:36 +01:00
Ryan Lortie
b5e1ea6fee DECLARE_TYPE: ignore deprecations in inlines
Prevent complaints about deprecations in the inline functions emitted by
the new G_DECLARE_*_TYPE macros.
2015-01-30 16:49:53 +01:00
Ryan Lortie
9d0389b3b5 G_DECLARE_FINAL_TYPE: trivial fix in docs comment
https://bugzilla.gnome.org/show_bug.cgi?id=743640
2015-01-30 16:49:53 +01:00
Christian Hergert
f3c604d273 G_DECLARE_DERIVED_TYPE: allow forward declarations
This allows multiple declarations such as:

 typedef struct _Foo Foo;

as is needed when you have systems with circular referencing.

https://bugzilla.gnome.org/show_bug.cgi?id=743596
2015-01-28 13:22:23 +00:00
Ryan Lortie
3b4cb28e17 gtype: add type declaration macros for headers
Add G_DECLARE_DERIVABLE_TYPE() and G_DECLARE_FINAL_TYPE() to allow
skipping almost all of the typical GObject boilerplate code.

These macros make some assumptions about GObject best practice that mean
that they may not be usable with older classes that have to preserve
API/ABI compatibility with a time before these practices existed.

https://bugzilla.gnome.org/show_bug.cgi?id=389585
2015-01-27 11:07:52 +00:00