Category Archives: GNOME

Posts about GNOME and programming for it.

g_assert_finalize_object() in GLib 2.61.2

One more API in this mini-series! g_assert_finalize_object(), which is available in GLib 2.61.2, which was released today.

This one’s useful when writing tests (and only when writing tests). It’s been put together by Simon McVittie to implement the common pattern needed in tests, where you want to unref a GObject and assert that you just dropped the final reference to the object — i.e., check that no references to the object have been leaked in the test.

Use it in place of g_object_unref(). If G_DISABLE_ASSERT is defined, it will actually just be a call to g_object_unref().

Here’s an example usage of it, straight out of the GLib unit test for it:

static void
test_assert_finalize_object (void)
{
  GObject *obj = g_object_new (G_TYPE_OBJECT, NULL);

  /* do some things with the obj here */

  g_assert_finalize_object (obj);
}

g_array_binary_search in GLib 2.61.2

The final API so far in this mini-series on new APIs in the GLib 2.62 series is g_array_binary_search(), put together by Emmanuel Fleury and based on code by Christian Hergert. It’s due to be released in 2.61.2 soon. But first, a reminder about GLib version numbering.

Like the rest of GNOME’s official module set, GLib follows an odd/even versioning scheme, where every odd minor version number, like 2.61.x, is an unstable release building up to an even minor version number, like 2.62.x, which is stable. APIs may be added in unstable releases. They may be modified or even removed (if they haven’t been in a stable release yet). So all of the APIs I’ve blogged about recently still have a chance to be tweaked or dropped if people find problems with them. So if you see a problem or think that one of these APIs would be awkward to use in some way, please say, sooner rather than later! They need fixing before they’re in a stable release.

Back to today’s API, g_array_binary_search(). As its name suggests, this does a binary search on an array (which it requires is already sorted). You can use it like this:

static gint
compare_guint64 (gconstpointer a,
                 gconstpointer b)
{
  guint64 uint64_a = *((guint64 *) a);
  guint64 uint64_b = *((guint64 *) b);

  if (uint64_a < uint64_b)
    return -1;
  else if (uint64_a > uint64_b)
    return 1;
  else
    return 0;
}

g_autoptr(GArray) my_array = g_array_new (FALSE, TRUE, sizeof (guint64));

for (guint i = 0; i < 100; i++)
  {
    guint64 random_uint64 = ( (guint64) g_random_int () << 32) | g_random_int ();
    g_array_append_val (my_array, random_uint64);
  }

g_array_sort (my_array, compare_guint64);

/* Is ‘1234’ in the array? If so, where? */
const guint64 search_uint64 = 1234;
guint search_index;
if (g_array_binary_search (my_array, &amp;search_uint64, compare_guint64, &amp;search_index))
  g_message ("Found ‘1234’ at index %u", search_index);
else
  g_message ("Didn’t find ‘1234’");

As all computer science algorithms courses will tell you, a binary search is faster than a linear search, so you should use this in preference to iterating over an array to find an element in it, where possible.

(That’s not entirely true: the overheads of accounting for the binary search bounds, and the slowness of scattered memory loads from the array in a binary search vs sequential access in a linear search, will probably make it slower than a linear search for small arrays. But both will be fast, and if you need to care about that level of performance, you should be using a custom data structure rather than GArray.)

Array copying and extending in GLib 2.61.2

A slightly more in-depth post in the mini-series this time, about various new functions which Emmanuel Fleury has landed in GLib 2.61.2 (which is due to be released soon), based on some old but not-quite-finished patches from others.

There’s g_ptr_array_copy() and g_array_copy(); and also g_ptr_array_extend() and g_ptr_array_extend_and_steal().

g_ptr_array_copy() and g_array_copy() are obvious functions and it’s not clear why they haven’t been added before. They allow you to copy a GPtrArray or a GArray, including its contents.
When copying a GPtrArray, you pass in a GCopyFunc to copy each element (for example, by increasing its reference count). If the GCopyFunc is NULL, the element is copied by value.

For example,

g_autoptr(GPtrArray) object_array = g_ptr_array_new_with_free_func (g_object_unref);

for (gsize i = 0; i < 10; i++)
  g_ptr_array_add (object_array, create_new_object (i));

object_array_copy = g_ptr_array_copy (object_array, g_object_ref, NULL);
/* object_array and object_array_copy now contain copies of the same elements, but
 * modifying one array will not modify the other */

The g_ptr_array_extend() functions are used to join one array onto the end of another. This means you can turn the following code to join the GObject elements of array2 onto the end of array1 and ref them all:

for (gsize i = 0; i < array2->len; i++)
  g_ptr_array_add (array1, g_object_ref (g_ptr_array_index (array2, i)));

into

g_ptr_array_extend (array1, array2, g_object_ref, NULL);

If you no longer need array2, you can go further and use g_ptr_array_extend_and_steal() to avoid copying each element. This might be particularly beneficial when using string arrays, where each copy (a g_strdup()) is more expensive. So the following code:

g_autoptr(GPtrArray) array1 = g_ptr_array_new_with_free_func (g_free);
for (guint i = 0; i < 10; i++)
  g_ptr_array_add (array1, g_strdup_printf ("array1 %u", i));

g_autoptr(GPtrArray) array2 = g_ptr_array_new_with_free_func (g_free);
for (guint i = 100; i < 110; i++)
  g_ptr_array_add (array2, g_strdup_printf ("array2 %u", i));

for (gsize i = 0; i < array2->len; i++)
  g_ptr_array_add (array1, g_strdup (g_ptr_array_index (array2, i)));

would become:

g_autoptr(GPtrArray) array1 = g_ptr_array_new_with_free_func (g_free);
for (guint i = 0; i < 10; i++)
  g_ptr_array_add (array1, g_strdup_printf ("array1 %u", i));

g_autoptr(GPtrArray) array2 = g_ptr_array_new_with_free_func (g_free);
for (guint i = 100; i < 110; i++)
  g_ptr_array_add (array2, g_strdup_printf ("array2 %u", i));

g_ptr_array_extend_and_steal (array1, g_steal_pointer (&amp;array2));
/* array2 has now been destroyed */

g_test_summary and g_get_console_charset in GLib 2.61.2

Another short post about new APIs, this time from the upcoming 2.61.2 release. This time it’s two unrelated new APIs, which I’m covering together because they’re fairly short.

g_test_summary() is a new API along the same lines as the existing g_test_bug() function. It’s to be called from within a unit test to provide a summary of the test to the test harness. In contrast, g_test_bug() provides a bug reference for the unit test. In this fashion, the two can be used to provide documentation within the test code of what the test is testing, how it goes about testing it, and which bug it’s checking for regressions in. The summary passed to g_test_summary() might be printed out as a comment in the test logs.

The summary passed to g_test_summary() should contain a brief overview of what the test does, and should note any particularly non-obvious things about how the test is implemented.

For example:

g_test_summary ("Test g_queue_push_nth_link() with various combinations of position (before, "
                "in the middle of, or at the end of the queue) and various existing queues "
                "(empty, single element, multiple elements).");

or:

g_test_summary ("Ensure that we successfully return IPv4 results even when they come significantly later than an IPv6 failure.");

The second API, g_get_console_charset(), is more useful only on Windows. On Linux, it returns the same value as g_get_charset(). On Windows, its result may differ if the console the current process is attached to has a different character encoding from that of the current locale. In those situations, g_get_console_charset() will return something which should result in correct character decoding by the console. If the process is not attached to a console, it returns UTF-8.

When should you care? Use g_get_console_charset() whenever you need to work out the character encoding for printing to the console (stdout or stderr), even on Linux (if you want your code to be portable). Use g_get_charset() whenever you need the character encoding for other strings related to the system locale, such as dates or file names. GLib correctly uses the two functions internally so that you should generally never have to care (for example, you don’t need to care when you use g_log(), g_date_time_format() or g_filename_to_utf8()).

g_queue_insert_before_link() in GLib 2.61.1

The second post in a little mini-series on new APIs in the GLib 2.62 series, this one’s about Christian Hergert’s g_queue_insert_before_link().

This is a new helper function for inserting elements at arbitrary positions in a queue, without needing to allocate a new container element for them. Previously, using g_queue_insert_before(), a new GList container would have been allocated. The new function means that elements can be moved from one position in a queue to another, without any allocations; and statically allocated GList elements can be used in a GQueue correctly.

The new function comes with friends, too: g_queue_insert_after_link() and g_list_insert_before_link(). They behave similarly.

One example of using the new function would be to bump the priority of an element in the middle of a queue:

GList *element_to_bump = g_queue_find (queue, important_data);
GList *old_sibling = element_to_bump->prev;
if (old_sibling != NULL)
  {
    g_queue_unlink (queue, element_to_bump);
    g_queue_insert_before_link (queue, old_sibling, element_to_bump);
  }
else
  {
    g_debug ("Already at the head of the queue");
  }

Christian is using it in GNOME Builder to arrange embedded structures in a queue using embedded GList instances, kernel-style.

g_clear_signal_handler() in GLib 2.61.1

It’s been a long time since I’ve blogged, so I thought I’d do a quick series on new APIs in the upcoming 2.62 release series of GLib.

Today, it’s the g_clear_signal_handler() function added by Marco Trevisan. This is a simple helper function along the same lines as g_clear_pointer(), g_clear_error() and g_clear_handle_id(). Given a GObject and a signal handler ID, it disconnects the signal handler and clears the signal handler ID variable to zero.

This turns the following standard pattern of code:

if (obj != NULL && handler_id != 0)
  {
    g_signal_handler_disconnect (obj, handler_id);
    handler_id = 0;
  }

to this:

g_clear_signal_handler (&handler_id, obj);

Nothing earth-shattering, but it does allow code to become a little more compact.

Metered data hackfest

tl;dr: Please fill out this survey about metered data connections, regardless of whether you run GNOME or often use metered data connections.

We’re now into the second day of the metered data hackfest in London. Yesterday we looked at Endless’ existing metered data implementation, which is restricted to OS and application updates, and discussed how it could be reworked to fit in with the new control centre design, and which applications would benefit from scheduling their large downloads to avoid using metered data unnecessarily (and hence costing the user money).

The conclusion was that the first step is to draw up a design for the control centre integration, which determines when to allow downloads on metered connections, and which connections are actually metered. Then to upstream the integration of metered data with gnome-software, so that app and OS updates adhere to the policy. Integration with other applications which do large downloads (such as podcasts, file syncing, etc.) can then follow.

While looking at metered data, however, we realised we don’t have much information about what types of metered data connections people have. For example, do connections commonly limit people to a certain amount of downloads per month, or per day? Do they have a free period in the middle of the night? We’ve put together a survey for anyone to take (not just those who use GNOME, or who use a metered connection regularly) to try and gather more information. Please fill it out!

Today, the hackfest is winding down a bit, with people quietly working on issues related to parental controls or metered data, or on upstream development in general. Richard and Kalev are working on gnome-software issues. Georges and Florian are working on gnome-shell issues.

Parental controls hackfest

Various of us have been meeting in the Red Hat offices in London this week (thanks Red Hat!) to discuss parental controls and digital wellbeing. The first two days were devoted to this; today and tomorrow will be dedicated to discussing metered data (which is unrelated to parental controls, but the hackfests are colocated because many of the same people are involved in both).

Parental controls discussions went well. We’ve worked out a rough scope of what features we are interested in integrating into GNOME, and how parental controls relates to digital wellbeing. In this context, we’re considering parental controls to be allowing parents to limit what their children can do on a computer, in terms of running different applications or games, or spending certain amounts of time on the computer.

Digital wellbeing is many of the same concepts – limiting time usage of the computer or applications, or access to certain websites – but applied in a way to give yourself ‘speed bumps’ to help your productivity by avoiding distractions at work.

Allan produced some initial designs for the control centre UI for parental controls and digital wellbeing, and we discussed various minor issues around them, and how to deal with the problem of allowing people to schedule times when apps, or whole groups of apps, are to be blocked; without making the UI too complex. There’s some more work to do there.

On Tuesday evening, we joined some of the local GNOME developers in London for beers, celebrating the 3.32 GNOME release. ?

We’re now looking at metered data, which is the idea that large downloads should be limited and scheduled according to the user’s network tariff, which might limit what can be downloaded during a certain time period, or provide certain periods of the night when downloads are unmetered. More to come on that later.

For other write ups of what we’ve been doing, see Iain’s detailed write up of the first two days, or the raw hackfest notes.

Generate NEWS entries for GitLab projects

I’ve just published a small script to help generating NEWS file entries for projects which use GitLab:

https://gitlab.gnome.org/pwithnall/gitlab-changelog

Use it like this:

  1. Generate a GitLab api token at https://gitlab.gnome.org/profile/personal_access_tokens.
  2. Run gitlab-changelog.py GNOME/glib 2.58.2.. -H https://gitlab.gnome.org/ -t ${generated_token}.
  3. Copy the output (below the dashed line) into your NEWS file entry. There are some blanks (indicated by TODO) in the entry which you need to fill in yourself.

The next time you run the script, you don’t need to pass the -H or -t options, as the configuration is saved in ~/.config/gitlab-changelog.ini.

I’ve used it on the last few GLib releases, which have seen a lot of issues fixed and MRs merged, and it sped up writing the NEWS file.

I haven’t tested it on other projects, or other GitLab instances, but it should work with them. Merge requests with improvements are very welcome.

GUADEC 2018 thoughts

GUADEC this year was another good one; thank you to the organisers for putting on a great and welcoming conference, and to Endless for sending me.

Unfortunately I couldn’t make the first two days due to a prior commitment, but I arrived on the Sunday in time to give my talks. I’ve got a lot of catching up to do with the talks on Friday and Saturday — looking forward to seeing the recordings online!

The slides for my talk on the state of GLib are here and the notes are here (source for them is here). I think the talk went fairly well, although I imagine it was quite boring for most involved — I’m not sure how to make new APIs particularly interesting to listen to!

The slides for my talk on download management on metered connections (the ‘Mogwai’ project) are here and the notes are here (source for them is here). I think this talk also went fairly well, and I’m pleased by how many people turned up and asked insightful questions. As I said in the talk, my time to spend on this project is currently limited, but I am interested in mentoring new contributors on it. Get in touch if you’re interested.

During the birds of a feather days, I spent most of my time on GLib, clearing out old bugs. We had the GLib BoF during the GTK+ one on Monday. The notes are here. Emmanuele has already done a good writeup of the results of the BoF here; and Matthias has written up the GTK+ BoF itself here.

There were some good discussions over dinner during the BoF days about people’s niggles with GLib, which has set a few ideas in motion in my head which I will try and explore over the coming few months, once the 2.58 release is out of the way.

It was good to catch up with everyone, great to see Almería and sample its food and drink, and nice to finally meet some of my colleagues from Endless for the first time!