[libdazzle] cancellable: provide cancellable back for convenience

[Christian Hergert <chergert src gnome org>]

commit 13b798762b13d1916a47c5563a2c32f2e8fc07a3
Author: Christian Hergert <chergert redhat com>
Date:   Wed Jan 3 19:22:37 2018 -0800

    cancellable: provide cancellable back for convenience
    
    This makes it simpler to use chained cancellables as you can now
    just do something like:
    
     cancellable = dzl_cancellable_chain (cancellable, other);
    
    If cancellable is NULL, you'll get other as a result.

 src/util/dzl-cancellable.c |   30 +++++++++++++++++++++++++-----
 src/util/dzl-cancellable.h |    4 ++--
 2 files changed, 27 insertions(+), 7 deletions(-)
---
diff --git a/src/util/dzl-cancellable.c b/src/util/dzl-cancellable.c
index 1b9460d..b32c3a4 100644
--- a/src/util/dzl-cancellable.c
+++ b/src/util/dzl-cancellable.c
@@ -81,19 +81,37 @@ dzl_cancellable_cancelled_cb (GCancellable *other,
  * If both @self and @other are not %NULL, then the cancellation of
  * @other will be propagated to @self if @other is cancelled.
  *
+ * If @self and @other are the same, @self is returned and no additional
+ * chaining will occur.
+ *
+ * If @self and @other are %NULL, then %NULL is returned.
+ * If @self is non-%NULL, it will be returned.
+ * If @self is %NULL and @other is non-%NULL, other will be
+ * returned. This is useful to succinctly chain cancellables like:
+ *
+ * |[
+ * cancellable = dzl_cancellable_chain (cancellable, self->cancellable);
+ * ]|
+ *
+ * Returns: (transfer none) (nullable): a #GCancellable or %NULL
+ *
  * Since: 3.28
  */
-void
+GCancellable *
 dzl_cancellable_chain (GCancellable *self,
                        GCancellable *other)
 {
   ChainedInfo *info;
 
-  g_return_if_fail (!self || G_IS_CANCELLABLE (self));
-  g_return_if_fail (!other || G_IS_CANCELLABLE (other));
+  g_return_val_if_fail (!self || G_IS_CANCELLABLE (self), NULL);
+  g_return_val_if_fail (!other || G_IS_CANCELLABLE (other), NULL);
 
-  if (self == NULL || other == NULL)
-    return;
+  if (self == other)
+    return self;
+  else if (self == NULL)
+    return other;
+  else if (other == NULL)
+    return self;
 
   /*
    * We very much want to avoid taking a reference in the process
@@ -108,4 +126,6 @@ dzl_cancellable_chain (GCancellable *self,
                                                G_CALLBACK (dzl_cancellable_cancelled_cb),
                                                info,
                                                chained_info_free);
+
+  return self;
 }
diff --git a/src/util/dzl-cancellable.h b/src/util/dzl-cancellable.h
index 7f2497b..be0c4d0 100644
--- a/src/util/dzl-cancellable.h
+++ b/src/util/dzl-cancellable.h
@@ -22,7 +22,7 @@
 
 G_BEGIN_DECLS
 
-void dzl_cancellable_chain (GCancellable *self,
-                            GCancellable *other);
+GCancellable *dzl_cancellable_chain (GCancellable *self,
+                                     GCancellable *other);
 
 G_END_DECLS