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.
GPtrArray is a nice interface to handle pointer arrays, however if a classic
array needs to be converted into a GPtrArray is currently needed to manually
go through all its elements and do new allocations that could be avoided.
So add g_ptr_array_new_take() which steals the data from an array of
pointers and allows to manage it using the GPtrArray API.
Add functions to steal all the keys or values from a ghash (especially
useful when it's used as a set), passing the ownership of then to a
GPtrArray container that preserves the destroy notify functions.
GPtrArray's are faster than lists and provide more flexibility, so add
APIs to get hash keys and values using these containers too.
Given that we know the size at array initialization we can optimize the
allocation quite a bit, making it faster than the API using GList both at
creation time and for consumers.
It’s been broken since we ported to Meson and nobody has complained, so
let’s deprecate it this cycle and remove it in GLib ≥ 2.78.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
Fixes: #2786
Sadly, in C++ there's not an universal way to get what language standard
is used to compile GLib-based programs, in fact while most compilers
relies on `__cplusplus`, MSVC is defining that, but it does not use it
to expose such information (unless `/Zc:__cplusplus` arg is used).
On the other side, MSVC reports the language standard via _MSVC_LANG [1].
This complication makes us defining some macros in a very complex way
(such as glib_typeof()), because we need to perform many checks just to
understand if a C++ compiler is used and what standard is expecting.
To avoid this, define multiple macros that can be used to figure out
what C++ standard is being used.
[1] https://docs.microsoft.com/en-us/cpp/build/reference/zc-cplusplus?view=msvc-170
This will make it clear what the bigger changes are between versions.
Kind of like a `NEWS` file for the specification.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
This should clarify object paths and signatures a little, if anyone
needs that. This introduces no semantic changes.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
reStructuredText doesn’t support cross-references unless always built
with Sphinx (as I understand it). `rst2html5` doesn‘t support them.
So reword this (currently manual) cross-reference so it’s less awkward.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
I believe the specification was originally a shorter extract of
Allison’s thesis. This left a few dangling references to requirements
which were listed in a part of the thesis not included in the
specification.
Reword them slightly so they’re not quite so awkward.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
The licensing for the original GVariant specification was not specified
in the original PDF.
However, CC-BY-SA-3.0 has been agreed by Allison, the sole copyright
holder, here:
https://gitlab.gnome.org/Teams/documentation/developer-www/-/merge_requests/108/#note_1586866
The diagrams were redrawn by me, so their licensing/copyright status is
clear.
Tested with `reuse lint` to ensure the data is machine-readable.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
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>
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.
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.
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;
}
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.
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
