This is a verbatim conversion of the GVariant Specification from
https://people.gnome.org/~desrt/gvariant-serialisation.pdf /
https://raw.githubusercontent.com/ostreedev/gvariant-rs/master/docs/gvariant-serialisation.pdf
to reStructuredText.
This is for several reasons:
1. The canonical copy has gone offline due to people.gnome.org being
shut down.
2. GLib is the reference implementation of GVariant, so should probably
host the specification (unless someone wants to host it on
freedesktop-specs).
3. Moving it out of a PDF and into reStructuredText should allow for
amendments. The specification has a few problems, typos and
oversights in its original form, and it would be good to canonically
fix them without having to write a separate addendum document.
This conversion is verbatim, and does not change the content of the
document at all, even to fix typos and broken links (which there are a
small number of in the PDF).
This describes what I’m labelling as version 1.0 of the GVariant
serialisation format. Updates to the specification can bump this version
number, in subsequent commits.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
Similar to g_source_set_static_name, this avoids
strdup overhead for debug-only information in
possibly hot code paths.
We also add a macro wrapper for g_task_set_name that
uses __builtin_constant_p to decide whether to use
g_task_set_name or g_task_set_static_name.
Given that it can be computed using an error-prone strings comparisons it
is better to provide a variable everywhere, so that we don't have the
risk of comparing values that are always false.
Inspired by libglnx's glnx_close_fd() and glnx_autofd, these let us
have the same patterns as g_clear_object() and g_autoptr(GObject), but
for file descriptors. g_clear_fd() is cross-platform, while g_autofd
is syntactic sugar requiring a supported compiler (gcc or clang).
Now that g_close() checks for EBADF as a programming error, we can
implement the equivalent of glnx_autofd as an inline function without
needing to have errno and EBADF in the header file.
g_clear_fd() is like glnx_close_fd(), but with error checking.
The private _g_clear_fd_ignore_error() function used to implement
g_autofd is a closer equivalent of glnx_close_fd().
Signed-off-by: Simon McVittie <smcv@collabora.com>
GBookmarkFile has everything for being introspectable, but it lacks a
GType, because it can't be copied. So provide a copy function that
deeply copies all the bookmark structures.
Add tests for this.
This is like our other suite of g_set_*() based APIs to simplify and
improve correctness of setters for fields, properties, and more.
This implementation specifically handles setting string values that may
point to an offset within the current string by copying before free.
strcmp() is used directly (as opposed to g_strcmp0() due to it being in
gtestutils.h as well as to increase the chance that the compiler will
hoist the implementation.
Fixes#2747
There is currently no `dllimport` attribute on any of our function,
which prevents MSVC to optimize function calls.
To fix that issue, we need to redeclare all our visibility macros for
each of our libraries, because when compiling e.g. GIO code, we need
dllimport in GLIB headers and dllexport in GIO headers. That means they
cannot use the same GLIB_AVAILABLE_* macro.
Since that's a lot of boilerplate to copy/paste after each version bump,
this MR generate all those macros using a python script.
Also simplify the meson side by using `gnu_symbol_visibility : 'hidden'`
keyword argument instead of passing the cflag manually.
This leaves only API index to add manually into glib-docs.xml when
bumping GLib version. That file cannot be generated because Meson does
not allow passing a buit file to gnome.gtkdoc()'s main_xml kwarg
unfortunately.
Building the references requires libraries with all their symbols
available. Passing `-Dgtk_doc=true` and `-Ddefault_library=static`
should be considered a configuration error.
glib_debug is an auto option. This is clever because it allows us to
guess the best default based on the build type, while also allowing an
easy way to override if the guess is not good. Sadly, the attempt to
guess based on the build type does not work well. For example, it
considers debugoptimized builds to be debug builds, but despite the
name, it is definitely a release build type (except on Windows, which
we'll ignore here). The minsize build type has the exact same problem.
The debug option is true for both build types, but this only controls
whether debuginfo is enabled, not whether debug extras are enabled.
The plain build type has a different problem: debug is off, but the
optimization option is off too, even though plain builds are distro
builds are will almost always use optimization.
I've outlined an argument for why we should make these changes here:
https://blogs.gnome.org/mcatanzaro/2022/07/15/best-practices-for-build-options/
Specifically, Rule 4 shows all the build types and whether they
correspond to release builds or debug builds. Rule 6 argues that we
should provide good defaults for plain builds.
We had gcc-only implementations for them while both can be used in all
the supported platforms we have.
So let's just provide generic definitions, while we keep the old ones
for both consistency and retro-compatibility.
We should mention glib-mkenums in the documentation for
G_DEFINE_ENUM_TYPE and G_DEFINE_FLAGS_TYPE.
We should also mention the macros in the documentation for glib-mkenums.
This way, developers can choose the most appropriate tool for their use
case.
Atomic primitives allow to do conditional compare and exchange but also
to get the value that was previously stored in the atomic variable.
Now, we provided an exchange function that allows to do an exchange if
the atomic value matches an expected value but we had no way to know
at the same time what was the value in the atomic at the moment of the
exchange try, an this can be useful in case that the operation fails,
for example if the current value is still acceptable for us, allowing
to do a kind of "OR" check:
gint old_value;
gint valid_value = 222;
while (!g_atomic_pointer_compare_and_exchange_value (&atomic,
valid_value, 555,
&old_value)
{
if (old_value == 555 || old_value == 222)
valid_value = old_value;
}
While it's possible to create a directory synchronously via
g_dir_make_tmp(), there's no such API that performs it asynchronously.
So implement it using GFile, using a thread to perform such task.
iconv is complicated to look up. That complexity now resides in
Meson, since 0.60.0, via a `dependency('iconv')` lookup, so use that
instead.
No effort is made to support the old option for which type of iconv to
use. It was a false choice, because if only one was available, then
that's the only one you can use, and if both are available, the external
iconv shadows the builtin one and renders the builtin one unusable,
so there is still only one you can use.
This meant that when configuring glib with -Diconv=libc on systems that
had an external iconv, the configure check would detect a valid libc
iconv, try to use it, and then fail during the build because iconv.h
belongs to the external iconv and generates machine code using the
external iconv ABI, but fails to link to the iconv `find_library()`.
Meson handles this transparently.
Rather than carrying the copylib around inside GLib, which is a pain to
synchronise and affects our code coverage statistics.
This requires updating the CI images to cache the new subproject,
including updating the `cache-subprojects.sh` script to pull in git
submodules.
It also requires adding `gioenumtypes_dep` to be added to the
dependencies list of `libgio`, since it needs to be build before GVDB as
it’s pulled in by the GIO headers which GVDB includes.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
Helps: #2603
The interface was ready for this API but it was not provided.
So implement this, using a thread that calls the sync API for now.
Add tests.
Helps with: GNOME/glib#157
Atomic APIs provide a way to exchange values only if we compare a value
that is equal to the old value, but not to just exchange the value
returning the old one.
However, compilers provide such built-in functions, so we can use them
to expose such functionality to GLib.
The only drawback is that when using an old version of gcc not providing
atomic APIs to swap values, we need to re-implement it with an
implementation that may not be fully atomic, but that is safe enough.
However this codepath should really not be used currently as gcc
introduced __atomic_exchange_n() at version 4.7.4, so 8 years ago.
GArray supports a "zero_terminated" flag, but GPtrArray doesn't.
This is odd, because especially for a pointer array it makes sense
to have a %NULL sentinel. This would be for example useful to track
or construct a strv array with a GPtrArray.
As workaround for this missing feature you could use a GArray instead
(ugly) or to explicitly add the %NULL element. However the latter increases
the "len" of the array, which can be problematic if you want to still use
the GPtrArray for other purposes.
Add API for marking a GPtrArray as %NULL terminated. In that case, the
API will ensure that there is always a valid %NULL sentinel after the
array. Note that the API does not enforce that a %NULL terminated API
actually has any data allocated. That means, even with a %NULL terminated
array, pdata can still be %NULL (only if len is zero).
Add g_ptr_array_new_null_terminated() constructor. The null-terminated flag
cannot be cleared. Once the GPtrArray is flagged to be %NULL terminated, it
sticks. The purpose is that once a user checks whether a GPtrArray instance
is safe to be treated as a %NULL terminated array, the decision does
not need to be re-evaluated.
Also add a g_ptr_array_is_null_terminated(). That is useful because it
allows you to check whether a GPtrArray created by somebody else is safe
to use as a %NULL terminated array. Since there is no API to make an
array not %NULL terminated anymore, this is not error prone.
The new flag is tracked as a guint8 in GRealPtrArray. On common 64 bit
architectures this does not increase the size of the struct as it fits
in an existing hole. Note that this is not a bitfield because it's
probably more efficient to access the entire guint8. However, there is
still a 3 bytes hole (on common 32 and 64 architectures), so if we need
to add more flags in the future, we still have space for 24 bits,
despite the new flag not being a bitfield.
The biggest downside of the patch is the runtime overhead that most
operations now need to check whether %NULL termination is requested.
Includes some tweaks and additional tests by Philip Withnall.
https://gitlab.gnome.org/GNOME/glib/-/issues/353
Many idle and timeout sources are installed as "one shot": called once
and immediately removed. While it's easy to write a simple callback that
returns G_SOURCE_REMOVE, it would also be useful to have some sort of
"visual" marker when reading the code; a way to immediately see that a
callback (which may be defined elsewhere in the code) is meant to be
invoked just once.
Includes additional unit tests by Philip Withnall.
This is more efficient than calling
g_datalist_id_remove() multiple times
in a row, since it only takes the locks
once.
Allow up to 16 keys to be removed in one go.
That is enough for the use we have in GObject,
and it avoids any danger of blowing the stack.
Make it a bit clearer in the documentation that using
`G_PARAM_STATIC_STRINGS` everywhere is a good thing.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
libgamin was last released in 2007 and is dead
[upstream](https://gitlab.gnome.org/Archive/gamin). Distributions may
still ship it (although Fedora no longer does), but we want people to
use inotify on Linux since it’s actively supported.
BSDs use kqueue. Windows uses win32filemonitor.
FAM might still be used on some commercial Unix distributions, but there
are no contributors from those distributions, and certainly no CI for
them to prevent regressions.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
Fixes: #2614
It used to exist on Solaris, but GLib’s support for it was mostly
removed in 2015 in commit 21ab660cf8.
Remove the final few references.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
This allows the controller to explicitly be removed from the bus, in a
way that allows the caller to synchronise with it and know that all
other references to the controller should have been dropped (i.e. after
this method returns, there should be no in-flight D-Bus calls still
holding a reference to the object).
This is needed to be able to guarantee finalisation of the controller in
unit tests (and comparable real-world situations).
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
Helps: #1190
The resources data is generated for both GCC and MSVC toolchains, even
though we know beforehand which toolchain we're going to compile it for.
By dropping the data duplication we make the generated resources file
faster to compile, especially when dealing with large embedded data,
instead of relying on the C pre-processor to walk the whole file and
discard the branch we're not using.
When working with storage (especially GInputStream or GOutputStream) it
is preferred to use page-aligned buffers so that the operating system
can do page-mapping tricks as the operation passes through the kernel.
Another use case is allocating memory used for vectorised operations,
which must be aligned to specific boundaries.
POSIX and Windows, as well as the C11 specification, provide this kind
of allocator functions, and GLib already makes use of it inside GSlice.
It would be convenient to have a public, portable wrapper that other
projects can use.
Fixes: #2574
If `GDebugControllerDBus` remains as the only, or default,
implementation of `GDebugController`, `dup_default()` cannot work.
`GDebugControllerDBus` requires a `GDBusConnection` at construction
time, which the `GIOModule` construction code can’t provide it.
Either we use a default D-Bus connection (but which one? and how would
it be changed by the user later if it was the wrong one?), or delegate
singleton handling of the `GDebugController` to the user.
The latter approach seems more flexible.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
Helps: #1190
Much like GBindingGroup, the GSignalGroup object allows you to connect many
signal connections for an object and connect/disconnect/block/unblock them
as a group.
This is useful when using many connections on an object to ensure that they
are properly removed when changing state or disposing a third-party
object.
This has been used for years in various GNOME projects and makes sense to
have upstream instead of multiple copies.
Originally, GBindingGroup started with Builder as a way to simplify all
of the third-degree object bindings necessary around Model-Controller
objects such as TextBuffer/TextView.
Over time, it has grown to be useful in a number of scenarios outside
of Builder and has been copied into a number of projects such as GNOME
Text Editor, GtkSourceView, libdazzle, and more.
It makes sense at this point to unify on a single implementation and
include that upstream in GObject directly alongside GBinding.
This is intended to provide a uniform interface for controlling whether
the debug output from an application (or service) is emitted, typically
to journald, but actually to wherever the application chooses to output
it.
The main implementation of `GDebugController` is `GDebugControllerDBus`,
which is intended to be used on Linux. Other implementations may be
added in future for other platforms, or larger applications may want to
provide their own implementation which integrates with their ecosystem.
The `GDebugControllerDBus` implementation exposes a D-Bus interface at
`/org/gtk/Debugging` with a method to enable or disable debug
output at runtime.
This could be used by external harnesses, such as GNOME Builder or
systemd, to give a uniform way to get debug output from an application.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
Fixes: #1190
This is an API analogue of the G_MESSAGES_DEBUG environment variable. It
is intended to be exposed outside applications (for example, as a D-Bus
interface — see follow-up commits) so that there is a uniform interface
for controlling the debug output of an application.
Helps: #1190
On !UNIX, return an error for send_fd() & receive_fd().
(the unixfdmessage unit is not compiled on !UNIX)
The header is installed under the common GIO include directory.
Ensure G_TYPE_UNIX_CONNECTION is registered on all platforms.
Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
The header is now also installed under the common GIO include directory.
Sorry if it breaks any build, you had to use the correct header path.
Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Move the header under the common GIO include directory.
Sorry if it breaks any build, you had to use the correct header path.
Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
This function creates a new hash table, but inherits the functions used
for the hash, comparison, and key/value memory management functions from
another hash table.
The primary use case is to implement a behaviour where you maintain a
hash table by regenerating it, letting the values not migrated be freed.
See the following pseudo code:
```
GHashTable *ht;
init(GList *resources) {
ht = g_hash_table_new (g_str_hash, g_str_equal, g_free, g_free);
for (r in resources)
g_hash_table_insert (ht, strdup (resource_get_key (r)), create_value (r));
}
update(GList *resources) {
GHashTable *new_ht = g_hash_table_new_similar (ht);
for (r in resources) {
if (g_hash_table_steal_extended (ht, resource_get_key (r), &key, &value))
g_hash_table_insert (new_ht, key, value);
else
g_hash_table_insert (new_ht, strdup (resource_get_key (r)), create_value (r));
}
g_hash_table_unref (ht);
ht = new_ht;
}
```
Added `g_alloca0()` which wraps `g_alloca()` and initializes
allocated memory to zeroes.
Added `g_newa0()` which wraps `g_alloca0()` in a typesafe manner.
Refreshed and tweaked by Nishal Kulkarni.
Use g_macro__has_attribute to detect it instead of
hardcoding __GNUC__ || __clang__. This adds support
for a few compiler and is consistent with the rest
of the gmacros.h file.
This allows the flag to allow interactive auth to be set. Previously, it
was unconditionally unset.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
This allows a pattern like
g_test_message ("cannot reticulate splines: %s", error->message);
g_test_fail ();
to be replaced by the simpler
g_test_fail_printf ("cannot reticulate splines: %s", error->message);
with the secondary benefit of making the message available to TAP
consumers as part of the "not ok" message.
Signed-off-by: Simon McVittie <smcv@collabora.com>
Forming the g_test_skip() message from printf-style arguments seems
common enough to deserve a convenience function.
g_test_incomplete() is mechanically almost equivalent to g_test_skip()
(the semantics are different but the implementation is very similar),
so give it a similar mechanism for symmetry.
Signed-off-by: Simon McVittie <smcv@collabora.com>
g_source_set_name duplicates the string, and this is
showing up as one of the more prominent sources of strdups
in GTK profiles, despite all the names we use being literals.
Add a variant that avoids the overhead.
