Move them to a separate page as they don’t really have a ‘class’ struct
each to hang docs off.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3037
Move it to a separate page, with a massive great list of all the misc
utils. Not a great documentation page, but equivalent to what we had
before, and it can be improved in future.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3037
Move it to a separate documentation file, since most of what’s covered
isn’t introspectable.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3037
Move it to a separate page so the difference between `g_rand_*()` and
`g_random_*()` can be explained.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3037
Move it to a separate page so more detail can be provided about all the
groups of API.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3037
Move it to a separate page so an overview of the deprecated threading
API can be given.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3037
This is a variant of `g_test_trap_subprocess()` which allows the
environment for the child process to be specified. This is quite useful
when you want to test code which reads environment variables, as it’s
not safe to set those after the start of `main()`.
This will be useful within and outwith GLib for testing such code.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #1618
Move it to a separate page, since it doesn’t quite make sense to
incorporate into the `GDBusConnection` docs.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3037
Move it to a separate page, as there isn’t a `GIOScheduler` struct.
Ensure that all its functions/methods/types are correctly marked as
deprecated. Fix a few broken links about I/O priority which pointed to
it.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3037
Move it to a separate content page as there is no `GDBusIntrospection`
type to hang the rest of the documentation off.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3037
Adding it all to the docs for the `GDBusError` enum seemed a bit much,
so I moved it to its own content page.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3037
The GIR files are now built by GLib itself, so they will be in the build
directories of each sub-library, except for GLib-2.0 which is built
alongside GObject-2.0.
On CHERI-enabled systems we use uintptr_t as the underlying storage for
GType and therefore casting to gsize strips the upper bits from a pointer.
Fix this by casting via uintptr_t instead and introduce a new set of
macros to convert between GType and pointers.
It needs to be in a separate page because there isn’t actually a
`GFileAttribute` type.
Signed-off-by: Philip Withnall <philip@tecnocode.co.uk>
Helps: #3037
It needs to be in a separate page because it’s all macros and they have
no type/class associated with them.
Signed-off-by: Philip Withnall <philip@tecnocode.co.uk>
Helps: #3037
Gate the API reference on the availability of the introspection data as
well, so we don't accidentally try and generate the documentation
without a description of our API.
g_strv_builder_take() allows to transfer ownership of the passed in
string.
This can be useful to avoid additional allocations when using functions
that transfer ownership to the caller like g_strdup_printf().
The testcase uses g_strv_builder_take and g_strv_builder_add to demo
that calls can be mixed.
This copies the test code inline into the Markdown, which means it could
diverge from the test code which is compiled and run as part of the
tests. That needs improving, but that can happen in a subsequent commit.
Helps: #3037
As we start moving documentation over from gtk-doc to gi-docgen, the
gtk-doc coverage is going to go down and things are going to start
breaking. That’s OK; we don’t need to test it any more.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
Helps: #3037
The files here are copied from the docs-gtk-org
branch of gtk.
This adds gi-docgen to the CI Dockerfiles and ensures the new versions
(including the OS upgrades from the previous commit) are used during CI.
Helps: #3037
We can't easily use g_autofd with g_unix_open_pipe, because its
parameter is an array of two fds that both need closing. Add an inline
convenience wrapper providing the obvious semantics.
Signed-off-by: Simon McVittie <smcv@collabora.com>
These functions can be used to initalize pointer-type variables rather
than a gsize. This is required to support CHERI-enabled platforms where
gsize cannot be used to store pointers. Follow-up changes will migrate
the uses of g_once_init that store pointers to the new API
Helps: https://gitlab.gnome.org/GNOME/glib/-/issues/2842
The `GTK_USE_PORTAL` environment variable has started to be misused by
users, which is causing deployment issues (such as portal services
themselves ending up being forced to use portals, which is never going
to work).
Try and sidestep users’ broken configurations by renaming the
environment variable, and also separating it from the old GTK
environment variable, since the GLib one affects a lot more processes.
This environment variable is meant to be used for
debugging and development, and never in production.
GTK already renamed their environment variable in
https://gitlab.gnome.org/GNOME/gtk/-/merge_requests/4829, so keeping the
`GTK_USE_PORTAL` name in GLib doesn’t make sense anyway.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
Fixes: #3107
The introspection scanner cannot deal very well with function pointers
into a plain structure. In order to document the various function
pointers in GTypeValueTable we need to create typed callbacks, and
use them to replace the anonymous function pointers inside the
structure. This not only allows us to properly document the function
pointers, but it also allows us to annotate the arguments and return
value of those function pointers.
See also: https://gitlab.gnome.org/GNOME/gobject-introspection/-/merge_requests/400#note_1721707
Since we have a convenience method to add actions let's allow to remove
them just as easily. This makes resource cleanup as simple as initially
adding the entries.
Adds a helper to truncate UTF8 strings in the middle, allowing to make
them fit certain size constraints.
This function is modeled after similar functionality that has existed
since 2008 in nautilus and in eel before that.
GTK lost it's '+' suffix back in 2019, according to
<https://mail.gnome.org/archives/gtk-devel-list/2019-February/msg00000.html>
This commit can be re-generated with:
git grep -l GTK+ \
| grep -v -e ^NEWS -e ^glib/tests/collate.c \
| xargs sed -i 's/GTK+/GTK/g'
Most of the changes are in comments and documentation.
While x86_64 has enough precision in long double to do a round trip
from guint64 to long double and back, this is platform-specific, and
is a disservice to users trying to debug failing unit tests on other
architectures where it loses precision for g_assert_cmp{int,uint,hex}.
See also https://bugzilla.gnome.org/show_bug.cgi?id=788385 which
mentions having to add casts to specifically silence the compiler on
platforms where the precision loss occurs.
Meanwhile, g_assert_cmpuint() does an unsigned comparison, but outputs
signed values if the comparison fails, which is confusing.
Fix both issues by introducing a new g_assertion_message_cmpint()
function with a new 'u' numtype. For backwards compatibility, the
macros still call into the older g_assertion_message_cmpnum() when not
targetting 2.78, and that function still works when passed 'i' and 'x'
types even though code compiled for 2.78 and later will never invoke
it with numtype anything other than 'f'. Note that g_assert_cmpmem
can also take advantage of the new code, even though in practice,
comparison between two size_t values representing array lengths that
can actually be compiled is unlikely to have ever hit the precision
loss. The macros in signals.c test code does not have to worry about
versioning, since it is not part of the glib library proper.
Closes#2997
Signed-off-by: Eric Blake <eblake@redhat.com>
I’ve finally found the right place in the docs to put this stuff.
This doesn’t auto-link this section from every string in the GLib
documentation, but I think that at this point (with gtk-doc in
maintenance mode, and gi-docgen not fully applied to GLib) I don’t think
we can do any better. The perfect is the enemy of the good, and having
this stuff documented somewhere means that someone can link to it from
multiple places in future *somehow*.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
Fixes: #116
By default, if a host environment has the `rst2html5` application
available, builds will automatically perform some HTML documentation
generation from the documentation's glib reference content (e.g.
creating `gvariant-specification-1.0.html`). The creation of this
documentation is not required for all use cases.
This commit tweaks the building of the HTML-based GLIB specification
document to be guarded by `gtk_doc`.
Signed-off-by: James Knight <james.d.knight@live.com>
Without a timeout, some lookup requests can go on forever, typically due
to bugs in underlying systems.
This can have particularly significant effects on the Happy Eyeballs
algorithm in `GSocketClient`, which relies on multiple name lookups as
its first step.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
Helps: #2866
We need a way to initialise refcounted types placed in static storage,
or on the stack. Using proper macros avoids knowing the magic constant
used for grefcount and gatomicrefcount.
The documentation previously implicitly said in a few places that
interfaces are classed, but reading through the implementation of
`GType`, I don’t think they are. If they were, the registration of the
fundamental `G_TYPE_INTERFACE` in `gobject_init()` would specify
`G_TYPE_FLAG_CLASSED`. It only specifies `G_TYPE_FLAG_DERIVABLE`.
I think this makes sense, because you can’t subclass an interface.
Subclassing is a key property of being classed.
Tweak the `GType` tutorial to remove that implicit statement, and expand
the documentation for `G_TYPE_IS_CLASSED`.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
Fixes: #252
Keep the API for ABI compatibility.
See
https://gitlab.gnome.org/GNOME/glib/-/merge_requests/2935#note_1650099
for a summary of the reasoning for this change:
- The performance of system-provided allocators has improved since
GSlice was written, and they are now similarly as performant, or more
performant, than GSlice.
- The code is unmaintained and nobody understands it.
- It doesn’t integrate with tooling and system security features which
have been written for the system `malloc()` implementation (such as
sanitisers, valgrind, etc.).
- It’s confusing for developers: should they use `g_slice_new()` or
`g_new()`?
- GSlice is faster than the libc allocator for allocating and
(particularly) freeing linked lists, but since these are a rubbish
data structure, that’s not a great thing to optimise for.
For the cases where application performance is negatively impacted by
the implementation of GSlice being dropped (and we don’t think there’ll
be many), applications can use a drop-in `malloc()` replacement which is
more suited to their particular workload. Choosing an allocator in GLib
to suit all application workloads is not possible.
Including documentation updates and cleanups by Philip Withnall.
Fixes: #1079
Historically GPtrArray made possible to compare pointers of pointers values
that it holds, however this is inconvenient in most cases as it requires
wrapper functions and not friendly castings.
So, add two functions that allow to perform the comparisons between the
pointer values that a GPtrArray holds following the same syntax that we
share everywhere in the codebase.
It allows to create a GPtrArray from a null-terminated C array computing its
size and in case performing copies of the its values using the provided
GCopyFunc.
