libs/gst/base/gstflowcombiner.c

   1 /* GStreamer
   2  *
   3  * Copyright (C) 2014 Samsung Electronics. All rights reserved.
   4  *   Author: Thiago Santos <ts.santos@sisa.samsung.com>
   5  *
   6  * gstflowcombiner.c: utility to combine multiple flow returns into a single one
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Library General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Library General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Library General Public
  19  * License along with this library; if not, write to the
  20  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  21  * Boston, MA 02110-1301, USA.
  22  */
  23
  24 /**
  25  * SECTION:gstflowcombiner
  26  * @title: GstFlowCombiner
  27  * @short_description: Utility to combine multiple flow returns into one
  28  *
  29  * Utility struct to help handling #GstFlowReturn combination. Useful for
  30  * #GstElement<!-- -->s that have multiple source pads and need to combine
  31  * the different #GstFlowReturn for those pads.
  32  *
  33  * #GstFlowCombiner works by using the last #GstFlowReturn for all #GstPad
  34  * it has in its list and computes the combined return value and provides
  35  * it to the caller.
  36  *
  37  * To add a new pad to the #GstFlowCombiner use gst_flow_combiner_add_pad().
  38  * The new #GstPad is stored with a default value of %GST_FLOW_OK.
  39  *
  40  * In case you want a #GstPad to be removed, use gst_flow_combiner_remove_pad().
  41  *
  42  * Please be aware that this struct isn't thread safe as its designed to be
  43  *  used by demuxers, those usually will have a single thread operating it.
  44  *
  45  * These functions will take refs on the passed #GstPad<!-- -->s.
  46  *
  47  * Aside from reducing the user's code size, the main advantage of using this
  48  * helper struct is to follow the standard rules for #GstFlowReturn combination.
  49  * These rules are:
  50  *
  51  * * %GST_FLOW_EOS: only if all returns are EOS too
  52  * * %GST_FLOW_NOT_LINKED: only if all returns are NOT_LINKED too
  53  * * %GST_FLOW_ERROR or below: if at least one returns an error return
  54  * * %GST_FLOW_NOT_NEGOTIATED: if at least one returns a not-negotiated return
  55  * * %GST_FLOW_FLUSHING: if at least one returns flushing
  56  * * %GST_FLOW_OK: otherwise
  57  *
  58  * %GST_FLOW_ERROR or below, GST_FLOW_NOT_NEGOTIATED and GST_FLOW_FLUSHING are
  59  * returned immediatelly from the gst_flow_combiner_update_flow() function.
  60  *
  61  * Since: 1.4
  62  */
  63
  64 #include <gst/gst.h>
  65 #include "gstflowcombiner.h"
  66
  67 struct _GstFlowCombiner
  68 {
  69   GQueue pads;
  70
  71   GstFlowReturn last_ret;
  72   volatile gint ref_count;
  73 };
  74
  75 static GstFlowCombiner *gst_flow_combiner_ref (GstFlowCombiner * combiner);
  76 static void gst_flow_combiner_unref (GstFlowCombiner * combiner);
  77
  78 GST_DEBUG_CATEGORY_STATIC (flowcombiner_dbg);
  79 #define GST_CAT_DEFAULT flowcombiner_dbg
  80
  81 G_DEFINE_BOXED_TYPE_WITH_CODE (GstFlowCombiner, gst_flow_combiner,
  82     (GBoxedCopyFunc) gst_flow_combiner_ref,
  83     (GBoxedFreeFunc) gst_flow_combiner_unref,
  84     GST_DEBUG_CATEGORY_INIT (flowcombiner_dbg, "flowcombiner", 0,
  85         "Flow Combiner"));
  86
  87 /**
  88  * gst_flow_combiner_new:
  89  *
  90  * Creates a new #GstFlowCombiner, use gst_flow_combiner_free() to free it.
  91  *
  92  * Returns: A new #GstFlowCombiner
  93  * Since: 1.4
  94  */
  95 GstFlowCombiner *
  96 gst_flow_combiner_new (void)
  97 {
  98   GstFlowCombiner *combiner = g_slice_new (GstFlowCombiner);
  99
 100   g_queue_init (&combiner->pads);
 101   combiner->last_ret = GST_FLOW_OK;
 102   combiner->ref_count = 1;
 103
 104   /* Make sure debug category is initialised */
 105   gst_flow_combiner_get_type ();
 106
 107   return combiner;
 108 }
 109
 110 /**
 111  * gst_flow_combiner_free:
 112  * @combiner: the #GstFlowCombiner to free
 113  *
 114  * Frees a #GstFlowCombiner struct and all its internal data.
 115  *
 116  * Since: 1.4
 117  */
 118 void
 119 gst_flow_combiner_free (GstFlowCombiner * combiner)
 120 {
 121   gst_flow_combiner_unref (combiner);
 122 }
 123
 124 static GstFlowCombiner *
 125 gst_flow_combiner_ref (GstFlowCombiner * combiner)
 126 {
 127   g_return_val_if_fail (combiner != NULL, NULL);
 128
 129   g_atomic_int_inc (&combiner->ref_count);
 130
 131   return combiner;
 132 }
 133
 134 static void
 135 gst_flow_combiner_unref (GstFlowCombiner * combiner)
 136 {
 137   g_return_if_fail (combiner != NULL);
 138   g_return_if_fail (combiner->ref_count > 0);
 139
 140   if (g_atomic_int_dec_and_test (&combiner->ref_count)) {
 141     GstPad *pad;
 142
 143     while ((pad = g_queue_pop_head (&combiner->pads)))
 144       gst_object_unref (pad);
 145
 146     g_slice_free (GstFlowCombiner, combiner);
 147   }
 148 }
 149
 150 /**
 151  * gst_flow_combiner_clear:
 152  * @combiner: the #GstFlowCombiner to clear
 153  *
 154  * Removes all pads from a #GstFlowCombiner and resets it to its initial state.
 155  *
 156  * Since: 1.6
 157  */
 158 void
 159 gst_flow_combiner_clear (GstFlowCombiner * combiner)
 160 {
 161   GstPad *pad;
 162
 163   g_return_if_fail (combiner != NULL);
 164
 165   while ((pad = g_queue_pop_head (&combiner->pads)))
 166     gst_object_unref (pad);
 167   combiner->last_ret = GST_FLOW_OK;
 168 }
 169
 170 /**
 171  * gst_flow_combiner_reset:
 172  * @combiner: the #GstFlowCombiner to clear
 173  *
 174  * Reset flow combiner and all pads to their initial state without removing pads.
 175  *
 176  * Since: 1.6
 177  */
 178 void
 179 gst_flow_combiner_reset (GstFlowCombiner * combiner)
 180 {
 181   GList *iter;
 182
 183   g_return_if_fail (combiner != NULL);
 184
 185   GST_DEBUG ("Reset flow returns");
 186
 187   for (iter = combiner->pads.head; iter; iter = iter->next) {
 188     GST_PAD_LAST_FLOW_RETURN (iter->data) = GST_FLOW_OK;
 189   }
 190
 191   combiner->last_ret = GST_FLOW_OK;
 192 }
 193
 194 static GstFlowReturn
 195 gst_flow_combiner_get_flow (GstFlowCombiner * combiner)
 196 {
 197   GstFlowReturn cret = GST_FLOW_OK;
 198   gboolean all_eos = TRUE;
 199   gboolean all_notlinked = TRUE;
 200   GList *iter;
 201
 202   GST_DEBUG ("Combining flow returns");
 203
 204   for (iter = combiner->pads.head; iter; iter = iter->next) {
 205     GstFlowReturn fret = GST_PAD_LAST_FLOW_RETURN (iter->data);
 206
 207     if (fret <= GST_FLOW_NOT_NEGOTIATED || fret == GST_FLOW_FLUSHING) {
 208       GST_DEBUG ("Error flow return found, returning");
 209       cret = fret;
 210       goto done;
 211     }
 212
 213     if (fret != GST_FLOW_NOT_LINKED) {
 214       all_notlinked = FALSE;
 215       if (fret != GST_FLOW_EOS)
 216         all_eos = FALSE;
 217     }
 218   }
 219   if (all_notlinked)
 220     cret = GST_FLOW_NOT_LINKED;
 221   else if (all_eos)
 222     cret = GST_FLOW_EOS;
 223
 224 done:
 225   GST_DEBUG ("Combined flow return: %s (%d)", gst_flow_get_name (cret), cret);
 226   return cret;
 227 }
 228
 229 /**
 230  * gst_flow_combiner_update_flow:
 231  * @combiner: the #GstFlowCombiner
 232  * @fret: the latest #GstFlowReturn received for a pad in this #GstFlowCombiner
 233  *
 234  * Computes the combined flow return for the pads in it.
 235  *
 236  * The #GstFlowReturn parameter should be the last flow return update for a pad
 237  * in this #GstFlowCombiner. It will use this value to be able to shortcut some
 238  * combinations and avoid looking over all pads again. e.g. The last combined
 239  * return is the same as the latest obtained #GstFlowReturn.
 240  *
 241  * Returns: The combined #GstFlowReturn
 242  * Since: 1.4
 243  */
 244 GstFlowReturn
 245 gst_flow_combiner_update_flow (GstFlowCombiner * combiner, GstFlowReturn fret)
 246 {
 247   GstFlowReturn ret;
 248
 249   g_return_val_if_fail (combiner != NULL, GST_FLOW_ERROR);
 250
 251   if (combiner->last_ret == fret) {
 252     return fret;
 253   }
 254
 255   if (fret <= GST_FLOW_NOT_NEGOTIATED || fret == GST_FLOW_FLUSHING) {
 256     ret = fret;
 257   } else {
 258     ret = gst_flow_combiner_get_flow (combiner);
 259   }
 260   combiner->last_ret = ret;
 261   return ret;
 262 }
 263
 264 /**
 265  * gst_flow_combiner_update_pad_flow:
 266  * @combiner: the #GstFlowCombiner
 267  * @pad: the #GstPad whose #GstFlowReturn to update
 268  * @fret: the latest #GstFlowReturn received for a pad in this #GstFlowCombiner
 269  *
 270  * Sets the provided pad's last flow return to provided value and computes
 271  * the combined flow return for the pads in it.
 272  *
 273  * The #GstFlowReturn parameter should be the last flow return update for a pad
 274  * in this #GstFlowCombiner. It will use this value to be able to shortcut some
 275  * combinations and avoid looking over all pads again. e.g. The last combined
 276  * return is the same as the latest obtained #GstFlowReturn.
 277  *
 278  * Returns: The combined #GstFlowReturn
 279  * Since: 1.6
 280  */
 281 GstFlowReturn
 282 gst_flow_combiner_update_pad_flow (GstFlowCombiner * combiner, GstPad * pad,
 283     GstFlowReturn fret)
 284 {
 285   g_return_val_if_fail (pad != NULL, GST_FLOW_ERROR);
 286
 287   GST_PAD_LAST_FLOW_RETURN (pad) = fret;
 288
 289   return gst_flow_combiner_update_flow (combiner, fret);
 290 }
 291
 292 /**
 293  * gst_flow_combiner_add_pad:
 294  * @combiner: the #GstFlowCombiner
 295  * @pad: (transfer none): the #GstPad that is being added
 296  *
 297  * Adds a new #GstPad to the #GstFlowCombiner.
 298  *
 299  * Since: 1.4
 300  */
 301 void
 302 gst_flow_combiner_add_pad (GstFlowCombiner * combiner, GstPad * pad)
 303 {
 304   g_return_if_fail (combiner != NULL);
 305   g_return_if_fail (pad != NULL);
 306
 307   g_queue_push_head (&combiner->pads, gst_object_ref (pad));
 308 }
 309
 310 /**
 311  * gst_flow_combiner_remove_pad:
 312  * @combiner: the #GstFlowCombiner
 313  * @pad: (transfer none): the #GstPad to remove
 314  *
 315  * Removes a #GstPad from the #GstFlowCombiner.
 316  *
 317  * Since: 1.4
 318  */
 319 void
 320 gst_flow_combiner_remove_pad (GstFlowCombiner * combiner, GstPad * pad)
 321 {
 322   g_return_if_fail (combiner != NULL);
 323   g_return_if_fail (pad != NULL);
 324
 325   if (g_queue_remove (&combiner->pads, pad))
 326     gst_object_unref (pad);
 327 }