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 GST_DEBUG_CATEGORY_STATIC (flowcombiner_dbg);
  76 #define GST_CAT_DEFAULT flowcombiner_dbg
  77
  78 G_DEFINE_BOXED_TYPE_WITH_CODE (GstFlowCombiner, gst_flow_combiner,
  79     (GBoxedCopyFunc) gst_flow_combiner_ref,
  80     (GBoxedFreeFunc) gst_flow_combiner_unref,
  81     GST_DEBUG_CATEGORY_INIT (flowcombiner_dbg, "flowcombiner", 0,
  82         "Flow Combiner"));
  83
  84 /**
  85  * gst_flow_combiner_new:
  86  *
  87  * Creates a new #GstFlowCombiner, use gst_flow_combiner_free() to free it.
  88  *
  89  * Returns: A new #GstFlowCombiner
  90  * Since: 1.4
  91  */
  92 GstFlowCombiner *
  93 gst_flow_combiner_new (void)
  94 {
  95   GstFlowCombiner *combiner = g_slice_new (GstFlowCombiner);
  96
  97   g_queue_init (&combiner->pads);
  98   combiner->last_ret = GST_FLOW_OK;
  99   combiner->ref_count = 1;
 100
 101   /* Make sure debug category is initialised */
 102   gst_flow_combiner_get_type ();
 103
 104   return combiner;
 105 }
 106
 107 /**
 108  * gst_flow_combiner_free:
 109  * @combiner: the #GstFlowCombiner to free
 110  *
 111  * Frees a #GstFlowCombiner struct and all its internal data.
 112  *
 113  * Since: 1.4
 114  */
 115 void
 116 gst_flow_combiner_free (GstFlowCombiner * combiner)
 117 {
 118   gst_flow_combiner_unref (combiner);
 119 }
 120
 121 GstFlowCombiner *
 122 gst_flow_combiner_ref (GstFlowCombiner * combiner)
 123 {
 124   g_return_val_if_fail (combiner != NULL, NULL);
 125
 126   g_atomic_int_inc (&combiner->ref_count);
 127
 128   return combiner;
 129 }
 130
 131 void
 132 gst_flow_combiner_unref (GstFlowCombiner * combiner)
 133 {
 134   g_return_if_fail (combiner != NULL);
 135   g_return_if_fail (combiner->ref_count > 0);
 136
 137   if (g_atomic_int_dec_and_test (&combiner->ref_count)) {
 138     GstPad *pad;
 139
 140     while ((pad = g_queue_pop_head (&combiner->pads)))
 141       gst_object_unref (pad);
 142
 143     g_slice_free (GstFlowCombiner, combiner);
 144   }
 145 }
 146
 147 /**
 148  * gst_flow_combiner_clear:
 149  * @combiner: the #GstFlowCombiner to clear
 150  *
 151  * Removes all pads from a #GstFlowCombiner and resets it to its initial state.
 152  *
 153  * Since: 1.6
 154  */
 155 void
 156 gst_flow_combiner_clear (GstFlowCombiner * combiner)
 157 {
 158   GstPad *pad;
 159
 160   g_return_if_fail (combiner != NULL);
 161
 162   while ((pad = g_queue_pop_head (&combiner->pads)))
 163     gst_object_unref (pad);
 164   combiner->last_ret = GST_FLOW_OK;
 165 }
 166
 167 /**
 168  * gst_flow_combiner_reset:
 169  * @combiner: the #GstFlowCombiner to clear
 170  *
 171  * Reset flow combiner and all pads to their initial state without removing pads.
 172  *
 173  * Since: 1.6
 174  */
 175 void
 176 gst_flow_combiner_reset (GstFlowCombiner * combiner)
 177 {
 178   GList *iter;
 179
 180   g_return_if_fail (combiner != NULL);
 181
 182   GST_DEBUG ("Reset flow returns");
 183
 184   for (iter = combiner->pads.head; iter; iter = iter->next) {
 185     GST_PAD_LAST_FLOW_RETURN (iter->data) = GST_FLOW_OK;
 186   }
 187
 188   combiner->last_ret = GST_FLOW_OK;
 189 }
 190
 191 static GstFlowReturn
 192 gst_flow_combiner_get_flow (GstFlowCombiner * combiner)
 193 {
 194   GstFlowReturn cret = GST_FLOW_OK;
 195   gboolean all_eos = TRUE;
 196   gboolean all_notlinked = TRUE;
 197   GList *iter;
 198
 199   GST_DEBUG ("Combining flow returns");
 200
 201   for (iter = combiner->pads.head; iter; iter = iter->next) {
 202     GstFlowReturn fret = GST_PAD_LAST_FLOW_RETURN (iter->data);
 203
 204     if (fret <= GST_FLOW_NOT_NEGOTIATED || fret == GST_FLOW_FLUSHING) {
 205       GST_DEBUG ("Error flow return found, returning");
 206       cret = fret;
 207       goto done;
 208     }
 209
 210     if (fret != GST_FLOW_NOT_LINKED) {
 211       all_notlinked = FALSE;
 212       if (fret != GST_FLOW_EOS)
 213         all_eos = FALSE;
 214     }
 215   }
 216   if (all_notlinked)
 217     cret = GST_FLOW_NOT_LINKED;
 218   else if (all_eos)
 219     cret = GST_FLOW_EOS;
 220
 221 done:
 222   GST_DEBUG ("Combined flow return: %s (%d)", gst_flow_get_name (cret), cret);
 223   return cret;
 224 }
 225
 226 /**
 227  * gst_flow_combiner_update_flow:
 228  * @combiner: the #GstFlowCombiner
 229  * @fret: the latest #GstFlowReturn received for a pad in this #GstFlowCombiner
 230  *
 231  * Computes the combined flow return for the pads in it.
 232  *
 233  * The #GstFlowReturn parameter should be the last flow return update for a pad
 234  * in this #GstFlowCombiner. It will use this value to be able to shortcut some
 235  * combinations and avoid looking over all pads again. e.g. The last combined
 236  * return is the same as the latest obtained #GstFlowReturn.
 237  *
 238  * Returns: The combined #GstFlowReturn
 239  * Since: 1.4
 240  */
 241 GstFlowReturn
 242 gst_flow_combiner_update_flow (GstFlowCombiner * combiner, GstFlowReturn fret)
 243 {
 244   GstFlowReturn ret;
 245
 246   g_return_val_if_fail (combiner != NULL, GST_FLOW_ERROR);
 247
 248   if (combiner->last_ret == fret) {
 249     return fret;
 250   }
 251
 252   if (fret <= GST_FLOW_NOT_NEGOTIATED || fret == GST_FLOW_FLUSHING) {
 253     ret = fret;
 254   } else {
 255     ret = gst_flow_combiner_get_flow (combiner);
 256   }
 257   combiner->last_ret = ret;
 258   return ret;
 259 }
 260
 261 /**
 262  * gst_flow_combiner_update_pad_flow:
 263  * @combiner: the #GstFlowCombiner
 264  * @pad: the #GstPad whose #GstFlowReturn to update
 265  * @fret: the latest #GstFlowReturn received for a pad in this #GstFlowCombiner
 266  *
 267  * Sets the provided pad's last flow return to provided value and computes
 268  * the combined flow return for the pads in it.
 269  *
 270  * The #GstFlowReturn parameter should be the last flow return update for a pad
 271  * in this #GstFlowCombiner. It will use this value to be able to shortcut some
 272  * combinations and avoid looking over all pads again. e.g. The last combined
 273  * return is the same as the latest obtained #GstFlowReturn.
 274  *
 275  * Returns: The combined #GstFlowReturn
 276  * Since: 1.6
 277  */
 278 GstFlowReturn
 279 gst_flow_combiner_update_pad_flow (GstFlowCombiner * combiner, GstPad * pad,
 280     GstFlowReturn fret)
 281 {
 282   g_return_val_if_fail (pad != NULL, GST_FLOW_ERROR);
 283
 284   GST_PAD_LAST_FLOW_RETURN (pad) = fret;
 285
 286   return gst_flow_combiner_update_flow (combiner, fret);
 287 }
 288
 289 /**
 290  * gst_flow_combiner_add_pad:
 291  * @combiner: the #GstFlowCombiner
 292  * @pad: (transfer none): the #GstPad that is being added
 293  *
 294  * Adds a new #GstPad to the #GstFlowCombiner.
 295  *
 296  * Since: 1.4
 297  */
 298 void
 299 gst_flow_combiner_add_pad (GstFlowCombiner * combiner, GstPad * pad)
 300 {
 301   g_return_if_fail (combiner != NULL);
 302   g_return_if_fail (pad != NULL);
 303
 304   g_queue_push_head (&combiner->pads, gst_object_ref (pad));
 305 }
 306
 307 /**
 308  * gst_flow_combiner_remove_pad:
 309  * @combiner: the #GstFlowCombiner
 310  * @pad: (transfer none): the #GstPad to remove
 311  *
 312  * Removes a #GstPad from the #GstFlowCombiner.
 313  *
 314  * Since: 1.4
 315  */
 316 void
 317 gst_flow_combiner_remove_pad (GstFlowCombiner * combiner, GstPad * pad)
 318 {
 319   g_return_if_fail (combiner != NULL);
 320   g_return_if_fail (pad != NULL);
 321
 322   if (g_queue_remove (&combiner->pads, pad))
 323     gst_object_unref (pad);
 324 }