7a795de4d6
Add API g_object_weak_ref_full() and g_object_weak_unref_full(). The documentation elaborates how g_object_weak_ref() cannot be used (naively) in a thread-safe way, when another thread is invoking dispose (e.g. by running g_object_run_dispose() or by unrefing the last reference). The suggestion is to combine that with GWeakRef. Note that usually you cannot use GWeakRef alone, since you get no notification when the reference count drop to zero. So a complete solution uses g_object_weak_ref() and GWeakRef together. The problem is that the user must not call g_object_weak_unref() when another thread might just dispose() the instance. Presumably, they use GWeakRef to first obtain a strong reference. That ensures that no other thread can trigger dispose via a g_object_unref(). That however does not help against another thread calling g_object_run_dispose(). In fact, there is no way to safely call g_object_weak_unref() when another thread might call g_object_run_dispose() (unless the user coordinates/synchronizes that at a higher level). The new API can avoid that problem. Note that calling g_object_weak_unref() asserts that it finds the notification. Which might be violated by another thread calling g_object_run_dispose() at the wrong time. But the assertion is not the only problem. Often, the weak notification might hold resources (e.g. an allocated data) that needs to be released -- either by the weak notification callback or during g_object_weak_unref(). For example, see "gobject/gbinding.c". It calls `g_object_weak_unref (source, weak_unbind, context);` while holding a strong reference on source. But if another thread runs g_object_run_dispose() at the wrong moment, we will call binding_context_unref() twice (and crash). You might think, we cannot possibly support that another thread calls g_object_run_dispose() while we still want to do something on an object. Maybe in many cases that is not supportable. However, the user could have a thread-safe GObject that handles that correctly. Also, see for example GBinding, which operates on the basics of GObject (weak notifications, GWeakRef, property notification subscription). Those parts all all supposed to be thred-safe, and a low-level object like GBinding should also work with objects that can be disposed by other threads (including via g_object_run_dispose()). In general, while it's often difficult to support multi threadded g_object_run_dispose(), the basic g_object_weak_ref() should not fail to support such pattern. Add new API that solves this. g_object_weak_ref_full() takes a GDestroyNotify, which is guaranteed to be called exactly once -- unless the data is stolen during g_object_weak_unref_full(). This can be convenient for cleanup. But more importantly, doing the cleanup once is also a place to synchronize and ensure we do something on the object, while it is still alive. We may combine g_object_weak_ref_full() with GWeakRef for a thread-safe solution, like GBinding does. But you can now also have a fully thread-safe solution without using GWeakRef. The benefit of that is that you never need to acquire a strong reference on the object and never emit a toggle notification, while still knowing the object is alive. The unit test shows how that can be done. The downside is that the size of WeakRefTuple increases by one pointer size. Optimizing that would be cumbersome and is not done.
GLib
GLib is the low-level core library that forms the basis for projects such as GTK and GNOME. It provides data structure handling for C, portability wrappers, and interfaces for such runtime functionality as an event loop, threads, dynamic loading, and an object system.
The official download locations are: https://download.gnome.org/sources/glib
The official web site is: https://www.gtk.org/
Installation
See the file ‘INSTALL.md’. There is separate and more in-depth documentation for building GLib on Windows.
Supported versions
Upstream GLib only supports the most recent stable release series, the previous stable release series, and the current development release series. All older versions are not supported upstream and may contain bugs, some of which may be exploitable security vulnerabilities.
See SECURITY.md for more details.
Documentation
API documentation is available online for GLib for the:
Discussion
If you have a question about how to use GLib, seek help on GNOME’s Discourse
instance. Alternatively, ask a question
on StackOverflow and tag it glib.
Reporting bugs
Bugs should be reported to the GNOME issue tracking system. You will need to create an account for yourself. You may also submit bugs by e-mail (without an account) by e-mailing incoming+gnome-glib-658-issue-@gitlab.gnome.org, but this will give you a degraded experience.
Bugs are for reporting problems in GLib itself, not for asking questions about how to use it. To ask questions, use one of our discussion forums.
In bug reports please include:
- Information about your system. For instance:
- What operating system and version
- For Linux, what version of the C library
- And anything else you think is relevant.
- How to reproduce the bug.
- If you can reproduce it with one of the test programs that are built
in the
tests/subdirectory, that will be most convenient. Otherwise, please include a short test program that exhibits the behavior. As a last resort, you can also provide a pointer to a larger piece of software that can be downloaded.
- If you can reproduce it with one of the test programs that are built
in the
- If the bug was a crash, the exact text that was printed out when the crash occurred.
- Further information such as stack traces may be useful, but is not necessary.
Contributing to GLib
Please follow the contribution guide to know how to start contributing to GLib.
Patches should be submitted as merge requests to gitlab.gnome.org. Note that you will need to be logged in to the site to use this page. If the patch fixes an existing issue, please refer to the issue in your commit message with the following notation (for issue 123):
Closes: #123
Otherwise, create a new merge request that introduces the change. Filing a separate issue is not required.