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  * @short_description: Utility to combine multiple flow returns into one
  27  *
  28  * Utility struct to help handling #GstFlowReturn combination. Useful for
  29  * #GstElement<!-- -->s that have multiple source pads and need to combine
  30  * the different #GstFlowReturn for those pads.
  31  *
  32  * #GstFlowCombiner works by using the last #GstFlowReturn for all #GstPad
  33  * it has in its list and computes the combined return value and provides
  34  * it to the caller.
  35  *
  36  * To add a new pad to the #GstFlowCombiner use gst_flow_combiner_add_pad().
  37  * The new #GstPad is stored with a default value of %GST_FLOW_OK.
  38  *
  39  * In case you want a #GstPad to be removed, use gst_flow_combiner_remove_pad().
  40  *
  41  * Please be aware that this struct isn't thread safe as its designed to be
  42  *  used by demuxers, those usually will have a single thread operating it.
  43  *
  44  * None of these functions will take refs on the passed #GstPad<!-- -->s, it
  45  * is the caller's responsibility to make sure that the #GstPad exists as long
  46  * as this struct exists.
  47  *
  48  * Aside from reducing the user's code size, the main advantage of using this
  49  * helper struct is to follow the standard rules for #GstFlowReturn combination.
  50  * These rules are:
  51  *
  52  * * %GST_FLOW_EOS: only if all returns are EOS too
  53  * * %GST_FLOW_NOT_LINKED: only if all returns are NOT_LINKED too
  54  * * %GST_FLOW_ERROR or below: if at least one returns an error return
  55  * * %GST_FLOW_NOT_NEGOTIATED: if at least one returns a not-negotiated return
  56  * * %GST_FLOW_FLUSHING: if at least one returns flushing
  57  * * %GST_FLOW_OK: otherwise
  58  *
  59  * %GST_FLOW_ERROR or below, GST_FLOW_NOT_NEGOTIATED and GST_FLOW_FLUSHING are
  60  * returned immediatelly from the gst_flow_combiner_update_flow() function.
  61  *
  62  * Since: 1.4
  63  */
  64
  65 #include <gst/gst.h>
  66 #include "gstflowcombiner.h"
  67
  68 struct _GstFlowCombiner
  69 {
  70   GQueue pads;
  71
  72   GstFlowReturn last_ret;
  73   volatile gint ref_count;
  74 };
  75
  76 static GstFlowCombiner *gst_flow_combiner_ref (GstFlowCombiner * combiner);
  77 static void gst_flow_combiner_unref (GstFlowCombiner * combiner);
  78
  79 G_DEFINE_BOXED_TYPE (GstFlowCombiner, gst_flow_combiner,
  80     (GBoxedCopyFunc) gst_flow_combiner_ref,
  81     (GBoxedFreeFunc) gst_flow_combiner_unref);
  82
  83 /**
  84  * gst_flow_combiner_new:
  85  *
  86  * Creates a new #GstFlowCombiner, use gst_flow_combiner_free() to free it.
  87  *
  88  * Returns: A new #GstFlowCombiner
  89  * Since: 1.4
  90  */
  91 GstFlowCombiner *
  92 gst_flow_combiner_new (void)
  93 {
  94   GstFlowCombiner *combiner = g_slice_new (GstFlowCombiner);
  95
  96   g_queue_init (&combiner->pads);
  97   combiner->last_ret = GST_FLOW_OK;
  98   combiner->ref_count = 1;
  99
 100   return combiner;
 101 }
 102
 103 /**
 104  * gst_flow_combiner_free:
 105  * @combiner: the #GstFlowCombiner to free
 106  *
 107  * Frees a #GstFlowCombiner struct and all its internal data.
 108  *
 109  * Since: 1.4
 110  */
 111 void
 112 gst_flow_combiner_free (GstFlowCombiner * combiner)
 113 {
 114   gst_flow_combiner_unref (combiner);
 115 }
 116
 117 static GstFlowCombiner *
 118 gst_flow_combiner_ref (GstFlowCombiner * combiner)
 119 {
 120   g_return_if_fail (combiner != NULL);
 121
 122   g_atomic_int_inc (&combiner->ref_count);
 123 }
 124
 125 static void
 126 gst_flow_combiner_unref (GstFlowCombiner * combiner)
 127 {
 128   g_return_if_fail (combiner != NULL);
 129   g_return_if_fail (combiner->ref_count > 0);
 130
 131   if (g_atomic_int_dec_and_test (&combiner->ref_count)) {
 132     GstPad *pad;
 133
 134     while ((pad = g_queue_pop_head (&combiner->pads)))
 135       gst_object_unref (pad);
 136
 137     g_slice_free (GstFlowCombiner, combiner);
 138   }
 139 }
 140
 141 static GstFlowReturn
 142 gst_flow_combiner_get_flow (GstFlowCombiner * combiner)
 143 {
 144   GstFlowReturn cret = GST_FLOW_OK;
 145   gboolean all_eos = TRUE;
 146   gboolean all_notlinked = TRUE;
 147   GList *iter;
 148
 149   GST_DEBUG ("Combining flow returns");
 150
 151   for (iter = combiner->pads.head; iter; iter = iter->next) {
 152     GstFlowReturn fret = GST_PAD_LAST_FLOW_RETURN (iter->data);
 153
 154     if (fret <= GST_FLOW_NOT_NEGOTIATED || fret == GST_FLOW_FLUSHING) {
 155       GST_DEBUG ("Error flow return found, returning");
 156       cret = fret;
 157       goto done;
 158     }
 159
 160     if (fret != GST_FLOW_NOT_LINKED) {
 161       all_notlinked = FALSE;
 162       if (fret != GST_FLOW_EOS)
 163         all_eos = FALSE;
 164     }
 165   }
 166   if (all_notlinked)
 167     cret = GST_FLOW_NOT_LINKED;
 168   else if (all_eos)
 169     cret = GST_FLOW_EOS;
 170
 171 done:
 172   GST_DEBUG ("Combined flow return: %s (%d)", gst_flow_get_name (cret), cret);
 173   return cret;
 174 }
 175
 176 /**
 177  * gst_flow_combiner_update_flow:
 178  * @combiner: the #GstFlowCombiner
 179  * @fret: the latest #GstFlowReturn received for a pad in this #GstFlowCombiner
 180  *
 181  * Computes the combined flow return for the pads in it.
 182  *
 183  * The #GstFlowReturn paramter should be the last flow return update for a pad
 184  * in this #GstFlowCombiner. It will use this value to be able to shortcut some
 185  * combinations and avoid looking over all pads again. e.g. The last combined
 186  * return is the same as the latest obtained #GstFlowReturn.
 187  *
 188  * Returns: The combined #GstFlowReturn
 189  * Since: 1.4
 190  */
 191 GstFlowReturn
 192 gst_flow_combiner_update_flow (GstFlowCombiner * combiner, GstFlowReturn fret)
 193 {
 194   GstFlowReturn ret;
 195
 196   g_return_val_if_fail (combiner != NULL, GST_FLOW_ERROR);
 197
 198   if (combiner->last_ret == fret) {
 199     return fret;
 200   }
 201
 202   if (fret <= GST_FLOW_NOT_NEGOTIATED || fret == GST_FLOW_FLUSHING) {
 203     ret = fret;
 204   } else {
 205     ret = gst_flow_combiner_get_flow (combiner);
 206   }
 207   combiner->last_ret = ret;
 208   return ret;
 209 }
 210
 211 /**
 212  * gst_flow_combiner_add_pad:
 213  * @combiner: the #GstFlowCombiner
 214  * @pad: (transfer-none): the #GstPad that is being added
 215  *
 216  * Adds a new #GstPad to the #GstFlowCombiner.
 217  *
 218  * Since: 1.4
 219  */
 220 void
 221 gst_flow_combiner_add_pad (GstFlowCombiner * combiner, GstPad * pad)
 222 {
 223   g_return_if_fail (combiner != NULL);
 224   g_return_if_fail (pad != NULL);
 225
 226   g_queue_push_head (&combiner->pads, gst_object_ref (pad));
 227 }
 228
 229 /**
 230  * gst_flow_combiner_remove_pad:
 231  * @combiner: the #GstFlowCombiner
 232  * @pad: (transfer-none): the #GstPad to remove
 233  *
 234  * Removes a #GstPad from the #GstFlowCombiner.
 235  *
 236  * Since: 1.4
 237  */
 238 void
 239 gst_flow_combiner_remove_pad (GstFlowCombiner * combiner, GstPad * pad)
 240 {
 241   g_return_if_fail (combiner != NULL);
 242   g_return_if_fail (pad != NULL);
 243
 244   if (g_queue_remove (&combiner->pads, pad))
 245     gst_object_unref (pad);
 246 }