[mutter/wip/nielsdg/cogl-clear-object] cogl/object: add cogl_clear_object utility function

[Niels De Graef <nielsdg src gnome org>]

commit 862b82bdebbf321f4503af27da068f38298f8d7a
Author: Niels De Graef <Niels DeGraef barco com>
Date:   Thu Nov 15 13:01:59 2018 +0100

    cogl/object: add cogl_clear_object utility function
    
    This is based on `g_clear_object`, so it will be a bit more consistent
    to write (and prevents the headaches from accidentally forgetting a NULL
    check).

 cogl/cogl/cogl-object.h | 14 ++++++++++++++
 1 file changed, 14 insertions(+)
---
diff --git a/cogl/cogl/cogl-object.h b/cogl/cogl/cogl-object.h
index 338ef79d8..e12028467 100644
--- a/cogl/cogl/cogl-object.h
+++ b/cogl/cogl/cogl-object.h
@@ -75,6 +75,20 @@ cogl_object_ref (void *object);
 void
 cogl_object_unref (void *object);
 
+/**
+ * cogl_clear_object: (skip)
+ * @object_ptr: a pointer to a #CoglObject reference
+ *
+ * Clears a reference to a #CoglObject.
+ *
+ * @object_ptr must not be %NULL.
+ *
+ * If the reference is %NULL then this function does nothing.
+ * Otherwise, the reference count of the object is decreased using
+ * cogl_object_unref() and the pointer is set to %NULL.
+ **/
+#define cogl_clear_object(object_ptr) g_clear_pointer ((object_ptr), cogl_object_unref)
+
 /**
  * CoglUserDataKey:
  * @unused: ignored.