Using glibmm / c++, do I really need to worry about refcounting?

Question

I am new to glibmm and am looking at the documentation for Glib::TimeZone c++ class. There are a few places, eg,. Glib::TimeZone::create_utc() where it states:

"You should release the return value by calling g_time_zone_unref() when you are done with it."

This seems odd for a C++ class.

Looking in the source code for the destructor of Glib::TimeZone, g_time_zone_unref() is called there, so am I right in thinking that I should ignore the statement in the documentation?

It seems a lot of the documentation refers to glib rather than glibmm, as if it's been generated from the underlying glib docs. Is this so? Should I be taking all the docs with a pinch of salt?

I'm using glibmm-2.68

Answer 1

It is sort of explained in the source code: https://gitlab.gnome.org/GNOME/glibmm/-/blob/master/glib/src/timezone.hg#L54-61

  // GTimeZone is refcounted, but Glib::TimeZone is not.
  // GTimeZone is immutable. Therefore, there is no problem having several
  // Glib::TimeZone instances wrap the same GTimeZone, and it's easier to use
  // Glib::TimeZone without Glib::RefPtr.
  _CLASS_BOXEDTYPE(TimeZone, GTimeZone, NONE, g_time_zone_ref, g_time_zone_unref, GLIBMM_API)
  _IGNORE(g_time_zone_ref, g_time_zone_unref)

So g_time_zone_ref() and g_time_zone_unref() are called automatically by the C++ Glib::TimeZone class. You should not call them explicitly.

The source code also says create() is deprecated and you should use create_identifier() instead. The difference is that create() returns the UTC zone if parsing failed, which makes it impossible to know if parsing failed, while create_identifier() returns null on error.

Why does the online documentation mention g_time_zone_unref()? Because it is auto-generated from the C documentation and the generator is not smart enough. An object lesson about the perils of generated documentation.