Merge branch 'type-deprecation' into 'main'

Add G_TYPE_FLAG_DEPRECATED

See merge request GNOME/glib!2993

docs/reference/gobject/gobject-sections.txt

@@ -18,6 +18,7 @@ G_TYPE_IS_DERIVABLE
 G_TYPE_IS_DEEP_DERIVABLE
 G_TYPE_IS_INTERFACE
 G_TYPE_IS_FINAL
+G_TYPE_IS_DEPRECATED
 GTypeInterface
 GTypeInstance
 GTypeClass

gobject/gtype.c

@@ -145,7 +145,7 @@
 				    G_TYPE_FLAG_INSTANTIATABLE | \
 				    G_TYPE_FLAG_DERIVABLE | \
 				    G_TYPE_FLAG_DEEP_DERIVABLE)
-#define	TYPE_FLAG_MASK		   (G_TYPE_FLAG_ABSTRACT | G_TYPE_FLAG_VALUE_ABSTRACT | G_TYPE_FLAG_FINAL)
+#define	TYPE_FLAG_MASK		   (G_TYPE_FLAG_ABSTRACT | G_TYPE_FLAG_VALUE_ABSTRACT | G_TYPE_FLAG_FINAL | G_TYPE_FLAG_DEPRECATED)
 #define	SIZEOF_FUNDAMENTAL_INFO	   ((gssize) MAX (MAX (sizeof (GTypeFundamentalInfo), \
 						       sizeof (gpointer)), \
                                                   sizeof (glong)))
@@ -1824,6 +1824,47 @@ type_iface_blow_holder_info_Wm (TypeNode *iface,
     }
 }
 
+static void
+maybe_issue_deprecation_warning (GType type)
+{
+  static GHashTable *already_warned_table;
+  static const gchar *enable_diagnostic;
+  static GMutex already_warned_lock;
+  gboolean already;
+  const char *name;
+
+  if (g_once_init_enter (&enable_diagnostic))
+    {
+      const gchar *value = g_getenv ("G_ENABLE_DIAGNOSTIC");
+
+      if (!value)
+        value = "0";
+
+      g_once_init_leave (&enable_diagnostic, value);
+    }
+
+  if (enable_diagnostic[0] == '0')
+    return;
+
+  g_mutex_lock (&already_warned_lock);
+
+  if (already_warned_table == NULL)
+    already_warned_table = g_hash_table_new (NULL, NULL);
+
+  name = g_type_name (type);
+
+  already = g_hash_table_contains (already_warned_table, (gpointer) name);
+  if (!already)
+    g_hash_table_add (already_warned_table, (gpointer) name);
+
+  g_mutex_unlock (&already_warned_lock);
+
+  if (!already)
+    g_warning ("The type %s is deprecated and shouldn’t be used "
+               "any more. It may be removed in a future version.",
+               name);
+}
+
 /* We use the system allocator on UNIX-y systems, where we know we have
  * access to a decent allocator. On other systems, we fall back to the
  * slice allocator, as we know its performance profile
@@ -1883,6 +1924,10 @@ g_type_create_instance (GType type)
       g_error ("cannot create instance of abstract (non-instantiatable) type '%s'",
 		 type_descriptive_name_I (type));
     }
+  if (G_UNLIKELY (G_TYPE_IS_DEPRECATED (type)))
+    {
+      maybe_issue_deprecation_warning (type);
+    }
 
   class = g_type_class_ref (type);
 

gobject/gtype.h

@@ -390,6 +390,19 @@ G_BEGIN_DECLS
  */
 #define G_TYPE_IS_FINAL(type)                   (g_type_test_flags ((type), G_TYPE_FLAG_FINAL)) GOBJECT_AVAILABLE_MACRO_IN_2_70
 
+/**
+ * G_TYPE_IS_DEPRECATED:
+ * @type: a #GType value
+ *
+ * Checks if @type is deprecated. Instantiating a deprecated type will
+ * trigger a warning if running with `G_ENABLE_DIAGNOSTIC=1`.
+ *
+ * Returns: %TRUE if the type is deprecated
+ *
+ * Since: 2.76
+ */
+#define G_TYPE_IS_DEPRECATED(type)                   (g_type_test_flags ((type), G_TYPE_FLAG_DEPRECATED)) GOBJECT_AVAILABLE_MACRO_IN_2_76
+
 
 /* Typedefs
  */
@@ -1050,6 +1063,9 @@ typedef enum    /*< skip >*/
  *  g_value_init()
  * @G_TYPE_FLAG_FINAL: Indicates a final type. A final type is a non-derivable
  *  leaf node in a deep derivable type hierarchy tree. Since: 2.70
+ * @G_TYPE_FLAG_DEPRECATED: The type is deprecated and may be removed in a
+ *  future version. A warning will be emitted if it is instantiated while
+ *  running with `G_ENABLE_DIAGNOSTIC=1`. Since 2.76
  * 
  * Bit masks used to check or determine characteristics of a type.
  */
@@ -1058,7 +1074,8 @@ typedef enum    /*< skip >*/
   G_TYPE_FLAG_NONE GOBJECT_AVAILABLE_ENUMERATOR_IN_2_74 = 0,
   G_TYPE_FLAG_ABSTRACT = (1 << 4),
   G_TYPE_FLAG_VALUE_ABSTRACT = (1 << 5),
-  G_TYPE_FLAG_FINAL GOBJECT_AVAILABLE_ENUMERATOR_IN_2_70 = (1 << 6)
+  G_TYPE_FLAG_FINAL GOBJECT_AVAILABLE_ENUMERATOR_IN_2_70 = (1 << 6),
+  G_TYPE_FLAG_DEPRECATED GOBJECT_AVAILABLE_ENUMERATOR_IN_2_76 = (1 << 7)
 } GTypeFlags;
 /**
  * GTypeInfo:

gobject/tests/type-flags.c

@@ -77,12 +77,72 @@ test_type_flags_final (void)
   g_test_assert_expected_messages ();
 }
 
+#define TEST_TYPE_DEPRECATED (test_deprecated_get_type())
+G_DECLARE_FINAL_TYPE (TestDeprecated, test_deprecated, TEST, DEPRECATED, GObject)
+
+struct _TestDeprecated
+{
+  GObject parent_instance;
+};
+
+struct _TestDeprecatedClass
+{
+  GObjectClass parent_class;
+};
+
+G_DEFINE_TYPE_EXTENDED (TestDeprecated, test_deprecated, G_TYPE_OBJECT, G_TYPE_FLAG_FINAL | G_TYPE_FLAG_DEPRECATED, {})
+
+static void
+test_deprecated_class_init (TestDeprecatedClass *klass)
+{
+}
+
+static void
+test_deprecated_init (TestDeprecated *self)
+{
+}
+
+static void
+test_type_flags_deprecated (void)
+{
+  GType deprecated_type;
+  GObject *deprecated_object = NULL;
+
+  g_test_summary ("Test that trying to instantiate a deprecated type results in a warning.");
+
+  /* This is the message we print out when registering the type */
+  g_test_expect_message ("GLib-GObject", G_LOG_LEVEL_WARNING,
+                         "*The type TestDeprecated is deprecated and shouldn’t be used any more*");
+
+  /* The type itself should not be considered invalid. */
+  deprecated_type = TEST_TYPE_DEPRECATED;
+  g_assert_false (deprecated_type == G_TYPE_INVALID);
+  g_assert_true (G_TYPE_IS_DEPRECATED (deprecated_type));
+
+  /* Instantiating it should work, but emit a warning. */
+  deprecated_object = g_object_new (deprecated_type, NULL);
+  g_assert_nonnull (deprecated_object);
+
+  g_test_assert_expected_messages ();
+
+  g_object_unref (deprecated_object);
+
+  /* Instantiating it again should not emit a second warning. */
+  deprecated_object = g_object_new (deprecated_type, NULL);
+  g_assert_nonnull (deprecated_object);
+
+  g_test_assert_expected_messages ();
+
+  g_object_unref (deprecated_object);
+}
+
 int
 main (int argc, char *argv[])
 {
   g_test_init (&argc, &argv, NULL);
 
   g_test_add_func ("/type/flags/final", test_type_flags_final);
+  g_test_add_func ("/type/flags/deprecated", test_type_flags_deprecated);
 
   return g_test_run ();
 }