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 immediately from the gst_flow_combiner_update_flow() function.
  60  *
  61  * Since: 1.4
  62  */
  63 #ifdef HAVE_CONFIG_H
  64 #include "config.h"
  65 #endif
  66
  67 #include <gst/gst.h>
  68 #include "gstflowcombiner.h"
  69
  70 struct _GstFlowCombiner
  71 {
  72   GQueue pads;
  73
  74   GstFlowReturn last_ret;
  75   volatile gint ref_count;
  76 };
  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 /**
 125  * gst_flow_combiner_ref:
 126  * @combiner: the #GstFlowCombiner to add a reference to.
 127  *
 128  * Increments the reference count on the #GstFlowCombiner.
 129  *
 130  * Returns: the #GstFlowCombiner.
 131  *
 132  * Since: 1.12.1
 133  */
 134 GstFlowCombiner *
 135 gst_flow_combiner_ref (GstFlowCombiner * combiner)
 136 {
 137   g_return_val_if_fail (combiner != NULL, NULL);
 138
 139   g_atomic_int_inc (&combiner->ref_count);
 140
 141   return combiner;
 142 }
 143
 144 /**
 145  * gst_flow_combiner_unref:
 146  * @combiner: the #GstFlowCombiner to unreference.
 147  *
 148  * Decrements the reference count on the #GstFlowCombiner.
 149  *
 150  * Since: 1.12.1
 151  */
 152 void
 153 gst_flow_combiner_unref (GstFlowCombiner * combiner)
 154 {
 155   g_return_if_fail (combiner != NULL);
 156   g_return_if_fail (combiner->ref_count > 0);
 157
 158   if (g_atomic_int_dec_and_test (&combiner->ref_count)) {
 159     GstPad *pad;
 160
 161     while ((pad = g_queue_pop_head (&combiner->pads)))
 162       gst_object_unref (pad);
 163
 164     g_slice_free (GstFlowCombiner, combiner);
 165   }
 166 }
 167
 168 /**
 169  * gst_flow_combiner_clear:
 170  * @combiner: the #GstFlowCombiner to clear
 171  *
 172  * Removes all pads from a #GstFlowCombiner and resets it to its initial state.
 173  *
 174  * Since: 1.6
 175  */
 176 void
 177 gst_flow_combiner_clear (GstFlowCombiner * combiner)
 178 {
 179   GstPad *pad;
 180
 181   g_return_if_fail (combiner != NULL);
 182
 183   while ((pad = g_queue_pop_head (&combiner->pads)))
 184     gst_object_unref (pad);
 185   combiner->last_ret = GST_FLOW_OK;
 186 }
 187
 188 /**
 189  * gst_flow_combiner_reset:
 190  * @combiner: the #GstFlowCombiner to clear
 191  *
 192  * Reset flow combiner and all pads to their initial state without removing pads.
 193  *
 194  * Since: 1.6
 195  */
 196 void
 197 gst_flow_combiner_reset (GstFlowCombiner * combiner)
 198 {
 199   GList *iter;
 200
 201   g_return_if_fail (combiner != NULL);
 202
 203   GST_DEBUG ("Reset flow returns");
 204
 205   for (iter = combiner->pads.head; iter; iter = iter->next) {
 206     GST_PAD_LAST_FLOW_RETURN (iter->data) = GST_FLOW_OK;
 207   }
 208
 209   combiner->last_ret = GST_FLOW_OK;
 210 }
 211
 212 static GstFlowReturn
 213 gst_flow_combiner_get_flow (GstFlowCombiner * combiner)
 214 {
 215   GstFlowReturn cret = GST_FLOW_OK;
 216   gboolean all_eos = TRUE;
 217   gboolean all_notlinked = TRUE;
 218   GList *iter;
 219
 220   GST_DEBUG ("Combining flow returns");
 221
 222   for (iter = combiner->pads.head; iter; iter = iter->next) {
 223     GstFlowReturn fret = GST_PAD_LAST_FLOW_RETURN (iter->data);
 224
 225     if (fret <= GST_FLOW_NOT_NEGOTIATED || fret == GST_FLOW_FLUSHING) {
 226       GST_DEBUG ("Error flow return found, returning");
 227       cret = fret;
 228       goto done;
 229     }
 230
 231     if (fret != GST_FLOW_NOT_LINKED) {
 232       all_notlinked = FALSE;
 233       if (fret != GST_FLOW_EOS)
 234         all_eos = FALSE;
 235     }
 236   }
 237   if (all_notlinked)
 238     cret = GST_FLOW_NOT_LINKED;
 239   else if (all_eos)
 240     cret = GST_FLOW_EOS;
 241
 242 done:
 243   GST_DEBUG ("Combined flow return: %s (%d)", gst_flow_get_name (cret), cret);
 244   return cret;
 245 }
 246
 247 /**
 248  * gst_flow_combiner_update_flow:
 249  * @combiner: the #GstFlowCombiner
 250  * @fret: the latest #GstFlowReturn received for a pad in this #GstFlowCombiner
 251  *
 252  * Computes the combined flow return for the pads in it.
 253  *
 254  * The #GstFlowReturn parameter should be the last flow return update for a pad
 255  * in this #GstFlowCombiner. It will use this value to be able to shortcut some
 256  * combinations and avoid looking over all pads again. e.g. The last combined
 257  * return is the same as the latest obtained #GstFlowReturn.
 258  *
 259  * Returns: The combined #GstFlowReturn
 260  * Since: 1.4
 261  */
 262 GstFlowReturn
 263 gst_flow_combiner_update_flow (GstFlowCombiner * combiner, GstFlowReturn fret)
 264 {
 265   GstFlowReturn ret;
 266
 267   g_return_val_if_fail (combiner != NULL, GST_FLOW_ERROR);
 268
 269   if (combiner->last_ret == fret) {
 270     return fret;
 271   }
 272
 273   if (fret <= GST_FLOW_NOT_NEGOTIATED || fret == GST_FLOW_FLUSHING) {
 274     ret = fret;
 275   } else {
 276     ret = gst_flow_combiner_get_flow (combiner);
 277   }
 278   combiner->last_ret = ret;
 279   return ret;
 280 }
 281
 282 /**
 283  * gst_flow_combiner_update_pad_flow:
 284  * @combiner: the #GstFlowCombiner
 285  * @pad: the #GstPad whose #GstFlowReturn to update
 286  * @fret: the latest #GstFlowReturn received for a pad in this #GstFlowCombiner
 287  *
 288  * Sets the provided pad's last flow return to provided value and computes
 289  * the combined flow return for the pads in it.
 290  *
 291  * The #GstFlowReturn parameter should be the last flow return update for a pad
 292  * in this #GstFlowCombiner. It will use this value to be able to shortcut some
 293  * combinations and avoid looking over all pads again. e.g. The last combined
 294  * return is the same as the latest obtained #GstFlowReturn.
 295  *
 296  * Returns: The combined #GstFlowReturn
 297  * Since: 1.6
 298  */
 299 GstFlowReturn
 300 gst_flow_combiner_update_pad_flow (GstFlowCombiner * combiner, GstPad * pad,
 301     GstFlowReturn fret)
 302 {
 303   g_return_val_if_fail (pad != NULL, GST_FLOW_ERROR);
 304
 305   GST_PAD_LAST_FLOW_RETURN (pad) = fret;
 306
 307   return gst_flow_combiner_update_flow (combiner, fret);
 308 }
 309
 310 /**
 311  * gst_flow_combiner_add_pad:
 312  * @combiner: the #GstFlowCombiner
 313  * @pad: (transfer none): the #GstPad that is being added
 314  *
 315  * Adds a new #GstPad to the #GstFlowCombiner.
 316  *
 317  * Since: 1.4
 318  */
 319 void
 320 gst_flow_combiner_add_pad (GstFlowCombiner * combiner, GstPad * pad)
 321 {
 322   g_return_if_fail (combiner != NULL);
 323   g_return_if_fail (pad != NULL);
 324
 325   g_queue_push_head (&combiner->pads, gst_object_ref (pad));
 326 }
 327
 328 /**
 329  * gst_flow_combiner_remove_pad:
 330  * @combiner: the #GstFlowCombiner
 331  * @pad: (transfer none): the #GstPad to remove
 332  *
 333  * Removes a #GstPad from the #GstFlowCombiner.
 334  *
 335  * Since: 1.4
 336  */
 337 void
 338 gst_flow_combiner_remove_pad (GstFlowCombiner * combiner, GstPad * pad)
 339 {
 340   g_return_if_fail (combiner != NULL);
 341   g_return_if_fail (pad != NULL);
 342
 343   if (g_queue_remove (&combiner->pads, pad))
 344     gst_object_unref (pad);
 345 }