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