gst/gstbufferpool.c

   1 /* GStreamer
   2  * Copyright (C) 2010 Wim Taymans <wim.taymans@gmail.com>
   3  *
   4  * gstbufferpool.c: GstBufferPool baseclass
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Library General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Library General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Library General Public
  17  * License along with this library; if not, write to the
  18  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  19  * Boston, MA 02111-1307, USA.
  20  */
  21
  22 /**
  23  * SECTION:gstbufferpool
  24  * @short_description: Pool for buffers
  25  * @see_also: #GstBuffer
  26  *
  27  */
  28
  29 #include "gst_private.h"
  30 #include "glib-compat-private.h"
  31
  32 #include <errno.h>
  33 #ifdef HAVE_UNISTD_H
  34 #  include <unistd.h>
  35 #endif
  36 #include <sys/types.h>
  37
  38 #include "gstinfo.h"
  39 #include "gstquark.h"
  40 #include "gstvalue.h"
  41
  42 #include "gstbufferpool.h"
  43
  44 GST_DEBUG_CATEGORY_STATIC (gst_buffer_pool_debug);
  45 #define GST_CAT_DEFAULT gst_buffer_pool_debug
  46
  47 #define GST_BUFFER_POOL_GET_PRIVATE(obj)  \
  48    (G_TYPE_INSTANCE_GET_PRIVATE ((obj), GST_TYPE_BUFFER_POOL, GstBufferPoolPrivate))
  49
  50 #define GST_BUFFER_POOL_LOCK(pool)   (g_rec_mutex_lock(&pool->priv->rec_lock))
  51 #define GST_BUFFER_POOL_UNLOCK(pool) (g_rec_mutex_unlock(&pool->priv->rec_lock))
  52
  53 struct _GstBufferPoolPrivate
  54 {
  55   GRecMutex rec_lock;
  56   guint size;
  57   guint min_buffers;
  58   guint max_buffers;
  59   guint prefix;
  60   guint align;
  61 };
  62
  63 enum
  64 {
  65   /* add more above */
  66   LAST_SIGNAL
  67 };
  68
  69 static void gst_buffer_pool_finalize (GObject * object);
  70
  71 G_DEFINE_TYPE (GstBufferPool, gst_buffer_pool, GST_TYPE_OBJECT);
  72
  73 static gboolean default_start (GstBufferPool * pool);
  74 static gboolean default_stop (GstBufferPool * pool);
  75 static gboolean default_set_config (GstBufferPool * pool,
  76     GstStructure * config);
  77 static GstFlowReturn default_alloc_buffer (GstBufferPool * pool,
  78     GstBuffer ** buffer, GstBufferPoolParams * params);
  79 static GstFlowReturn default_acquire_buffer (GstBufferPool * pool,
  80     GstBuffer ** buffer, GstBufferPoolParams * params);
  81 static void default_reset_buffer (GstBufferPool * pool, GstBuffer * buffer,
  82     GstBufferPoolParams * params);
  83 static void default_free_buffer (GstBufferPool * pool, GstBuffer * buffer);
  84 static void default_release_buffer (GstBufferPool * pool, GstBuffer * buffer);
  85
  86 static void
  87 gst_buffer_pool_class_init (GstBufferPoolClass * klass)
  88 {
  89   GObjectClass *gobject_class = (GObjectClass *) klass;
  90
  91   g_type_class_add_private (klass, sizeof (GstBufferPoolPrivate));
  92
  93   gobject_class->finalize = gst_buffer_pool_finalize;
  94
  95   klass->start = default_start;
  96   klass->stop = default_stop;
  97   klass->set_config = default_set_config;
  98   klass->acquire_buffer = default_acquire_buffer;
  99   klass->reset_buffer = default_reset_buffer;
 100   klass->alloc_buffer = default_alloc_buffer;
 101   klass->release_buffer = default_release_buffer;
 102   klass->free_buffer = default_free_buffer;
 103
 104   GST_DEBUG_CATEGORY_INIT (gst_buffer_pool_debug, "bufferpool", 0,
 105       "bufferpool debug");
 106 }
 107
 108 static void
 109 gst_buffer_pool_init (GstBufferPool * pool)
 110 {
 111   pool->priv = GST_BUFFER_POOL_GET_PRIVATE (pool);
 112
 113   g_rec_mutex_init (&pool->priv->rec_lock);
 114
 115   pool->poll = gst_poll_new_timer ();
 116   pool->queue = gst_atomic_queue_new (10);
 117   pool->flushing = TRUE;
 118   pool->active = FALSE;
 119   pool->configured = FALSE;
 120   pool->started = FALSE;
 121   pool->config = gst_structure_new_id_empty (GST_QUARK (BUFFER_POOL_CONFIG));
 122   gst_buffer_pool_config_set (pool->config, NULL, 0, 0, 0, 0, 0);
 123   gst_poll_write_control (pool->poll);
 124
 125   GST_DEBUG_OBJECT (pool, "created");
 126 }
 127
 128 static void
 129 gst_buffer_pool_finalize (GObject * object)
 130 {
 131   GstBufferPool *pool;
 132
 133   pool = GST_BUFFER_POOL_CAST (object);
 134
 135   GST_DEBUG_OBJECT (pool, "finalize");
 136
 137   gst_buffer_pool_set_active (pool, FALSE);
 138   gst_atomic_queue_unref (pool->queue);
 139   gst_poll_free (pool->poll);
 140   gst_structure_free (pool->config);
 141   g_rec_mutex_clear (&pool->priv->rec_lock);
 142
 143   G_OBJECT_CLASS (gst_buffer_pool_parent_class)->finalize (object);
 144 }
 145
 146 /**
 147  * gst_buffer_pool_new:
 148  *
 149  * Creates a new #GstBufferPool instance.
 150  *
 151  * Returns: (transfer full): a new #GstBufferPool instance
 152  */
 153 GstBufferPool *
 154 gst_buffer_pool_new (void)
 155 {
 156   GstBufferPool *result;
 157
 158   result = g_object_newv (GST_TYPE_BUFFER_POOL, 0, NULL);
 159   GST_DEBUG_OBJECT (result, "created new buffer pool");
 160
 161   return result;
 162 }
 163
 164 static GstFlowReturn
 165 default_alloc_buffer (GstBufferPool * pool, GstBuffer ** buffer,
 166     GstBufferPoolParams * params)
 167 {
 168   GstBufferPoolPrivate *priv = pool->priv;
 169   GstMemory *mem;
 170
 171   *buffer = gst_buffer_new ();
 172
 173   mem = gst_allocator_alloc (NULL, priv->size + priv->prefix, priv->align);
 174   gst_memory_resize (mem, priv->prefix, priv->size);
 175   gst_buffer_take_memory (*buffer, -1, mem);
 176
 177   return GST_FLOW_OK;
 178 }
 179
 180 static gboolean
 181 mark_meta_pooled (GstBuffer * buffer, GstMeta ** meta, gpointer user_data)
 182 {
 183   GST_META_FLAG_SET (*meta, GST_META_FLAG_POOLED);
 184
 185   return TRUE;
 186 }
 187
 188 /* the default implementation for preallocating the buffers
 189  * in the pool */
 190 static gboolean
 191 default_start (GstBufferPool * pool)
 192 {
 193   guint i;
 194   GstBufferPoolPrivate *priv = pool->priv;
 195   GstBufferPoolClass *pclass;
 196
 197   pclass = GST_BUFFER_POOL_GET_CLASS (pool);
 198
 199   /* no alloc function, error */
 200   if (G_UNLIKELY (pclass->alloc_buffer == NULL))
 201     goto no_alloc;
 202
 203   /* we need to prealloc buffers */
 204   for (i = 0; i < priv->min_buffers; i++) {
 205     GstBuffer *buffer;
 206
 207     if (pclass->alloc_buffer (pool, &buffer, NULL) != GST_FLOW_OK)
 208       goto alloc_failed;
 209
 210     gst_buffer_foreach_meta (buffer, mark_meta_pooled, pool);
 211     GST_LOG_OBJECT (pool, "prealloced buffer %d: %p", i, buffer);
 212     /* release to the queue, we call the vmethod directly, we don't need to do
 213      * the other refcount handling right now. */
 214     if (G_LIKELY (pclass->release_buffer))
 215       pclass->release_buffer (pool, buffer);
 216   }
 217   return TRUE;
 218
 219   /* ERRORS */
 220 no_alloc:
 221   {
 222     GST_WARNING_OBJECT (pool, "no alloc function");
 223     return FALSE;
 224   }
 225 alloc_failed:
 226   {
 227     GST_WARNING_OBJECT (pool, "alloc function failed");
 228     return FALSE;
 229   }
 230 }
 231
 232 /* must be called with the lock */
 233 static gboolean
 234 do_start (GstBufferPool * pool)
 235 {
 236   if (!pool->started) {
 237     GstBufferPoolClass *pclass;
 238
 239     pclass = GST_BUFFER_POOL_GET_CLASS (pool);
 240
 241     GST_LOG_OBJECT (pool, "starting");
 242     /* start the pool, subclasses should allocate buffers and put them
 243      * in the queue */
 244     if (G_LIKELY (pclass->start)) {
 245       if (!pclass->start (pool))
 246         return FALSE;
 247     }
 248     pool->started = TRUE;
 249   }
 250   return TRUE;
 251 }
 252
 253
 254 static void
 255 default_free_buffer (GstBufferPool * pool, GstBuffer * buffer)
 256 {
 257   gst_buffer_unref (buffer);
 258 }
 259
 260 /* must be called with the lock */
 261 static gboolean
 262 default_stop (GstBufferPool * pool)
 263 {
 264   GstBuffer *buffer;
 265   GstBufferPoolClass *pclass;
 266
 267   pclass = GST_BUFFER_POOL_GET_CLASS (pool);
 268
 269   /* clear the pool */
 270   while ((buffer = gst_atomic_queue_pop (pool->queue))) {
 271     GST_LOG_OBJECT (pool, "freeing %p", buffer);
 272     gst_poll_read_control (pool->poll);
 273
 274     if (G_LIKELY (pclass->free_buffer))
 275       pclass->free_buffer (pool, buffer);
 276   }
 277   return TRUE;
 278 }
 279
 280 /* must be called with the lock */
 281 static gboolean
 282 do_stop (GstBufferPool * pool)
 283 {
 284   if (pool->started) {
 285     GstBufferPoolClass *pclass;
 286
 287     pclass = GST_BUFFER_POOL_GET_CLASS (pool);
 288
 289     GST_LOG_OBJECT (pool, "stopping");
 290     if (G_LIKELY (pclass->stop)) {
 291       if (!pclass->stop (pool))
 292         return FALSE;
 293     }
 294     pool->started = FALSE;
 295   }
 296   return TRUE;
 297 }
 298
 299 /**
 300  * gst_buffer_pool_set_active:
 301  * @pool: a #GstBufferPool
 302  * @active: the new active state
 303  *
 304  * Control the active state of @pool. When the pool is active, new calls to
 305  * gst_buffer_pool_acquire_buffer() will return with GST_FLOW_FLUSHING.
 306  *
 307  * Activating the bufferpool will preallocate all resources in the pool based on
 308  * the configuration of the pool.
 309  *
 310  * Deactivating will free the resources again when there are no outstanding
 311  * buffers. When there are outstanding buffers, they will be freed as soon as
 312  * they are all returned to the pool.
 313  *
 314  * Returns: %FALSE when the pool was not configured or when preallocation of the
 315  * buffers failed.
 316  */
 317 gboolean
 318 gst_buffer_pool_set_active (GstBufferPool * pool, gboolean active)
 319 {
 320   gboolean res = TRUE;
 321
 322   g_return_val_if_fail (GST_IS_BUFFER_POOL (pool), FALSE);
 323
 324   GST_LOG_OBJECT (pool, "active %d", active);
 325
 326   GST_BUFFER_POOL_LOCK (pool);
 327   /* just return if we are already in the right state */
 328   if (pool->active == active)
 329     goto was_ok;
 330
 331   /* we need to be configured */
 332   if (!pool->configured)
 333     goto not_configured;
 334
 335   if (active) {
 336     if (!do_start (pool))
 337       goto start_failed;
 338
 339     /* unset the flushing state now */
 340     gst_poll_read_control (pool->poll);
 341     g_atomic_int_set (&pool->flushing, FALSE);
 342   } else {
 343     gint outstanding;
 344
 345     /* set to flushing first */
 346     g_atomic_int_set (&pool->flushing, TRUE);
 347     gst_poll_write_control (pool->poll);
 348
 349     /* when all buffers are in the pool, free them. Else they will be
 350      * freed when they are released */
 351     outstanding = g_atomic_int_get (&pool->outstanding);
 352     GST_LOG_OBJECT (pool, "outstanding buffers %d", outstanding);
 353     if (outstanding == 0) {
 354       if (!do_stop (pool))
 355         goto stop_failed;
 356     }
 357   }
 358   pool->active = active;
 359   GST_BUFFER_POOL_UNLOCK (pool);
 360
 361   return res;
 362
 363 was_ok:
 364   {
 365     GST_DEBUG_OBJECT (pool, "pool was in the right state");
 366     GST_BUFFER_POOL_UNLOCK (pool);
 367     return TRUE;
 368   }
 369 not_configured:
 370   {
 371     GST_ERROR_OBJECT (pool, "pool was not configured");
 372     GST_BUFFER_POOL_UNLOCK (pool);
 373     return FALSE;
 374   }
 375 start_failed:
 376   {
 377     GST_ERROR_OBJECT (pool, "start failed");
 378     GST_BUFFER_POOL_UNLOCK (pool);
 379     return FALSE;
 380   }
 381 stop_failed:
 382   {
 383     GST_WARNING_OBJECT (pool, "stop failed");
 384     GST_BUFFER_POOL_UNLOCK (pool);
 385     return FALSE;
 386   }
 387 }
 388
 389 /**
 390  * gst_buffer_pool_is_active:
 391  * @pool: a #GstBufferPool
 392  *
 393  * Check if @pool is active. A pool can be activated with the
 394  * gst_buffer_pool_set_active() call.
 395  *
 396  * Returns: %TRUE when the pool is active.
 397  */
 398 gboolean
 399 gst_buffer_pool_is_active (GstBufferPool * pool)
 400 {
 401   gboolean res;
 402
 403   GST_BUFFER_POOL_LOCK (pool);
 404   res = pool->active;
 405   GST_BUFFER_POOL_UNLOCK (pool);
 406
 407   return res;
 408 }
 409
 410 static gboolean
 411 default_set_config (GstBufferPool * pool, GstStructure * config)
 412 {
 413   GstBufferPoolPrivate *priv = pool->priv;
 414   const GstCaps *caps;
 415   guint size, min_buffers, max_buffers;
 416   guint prefix, align;
 417
 418   /* parse the config and keep around */
 419   if (!gst_buffer_pool_config_get (config, &caps, &size, &min_buffers,
 420           &max_buffers, &prefix, &align))
 421     goto wrong_config;
 422
 423   GST_DEBUG_OBJECT (pool, "config %" GST_PTR_FORMAT, config);
 424
 425   priv->size = size;
 426   priv->min_buffers = min_buffers;
 427   priv->max_buffers = max_buffers;
 428   priv->prefix = prefix;
 429   priv->align = align;
 430
 431   return TRUE;
 432
 433 wrong_config:
 434   {
 435     GST_WARNING_OBJECT (pool, "invalid config %" GST_PTR_FORMAT, config);
 436     return FALSE;
 437   }
 438 }
 439
 440 /**
 441  * gst_buffer_pool_set_config:
 442  * @pool: a #GstBufferPool
 443  * @config: (transfer full): a #GstStructure
 444  *
 445  * Set the configuration of the pool. The pool must be inactive and all buffers
 446  * allocated form this pool must be returned or else this function will do
 447  * nothing and return FALSE.
 448  *
 449  * @config is a #GstStructure that contains the configuration parameters for
 450  * the pool. A default and mandatory set of parameters can be configured with
 451  * gst_buffer_pool_config_set(). This function takes ownership of @config.
 452  *
 453  * Returns: TRUE when the configuration could be set.
 454  */
 455 gboolean
 456 gst_buffer_pool_set_config (GstBufferPool * pool, GstStructure * config)
 457 {
 458   gboolean result;
 459   GstBufferPoolClass *pclass;
 460
 461   g_return_val_if_fail (GST_IS_BUFFER_POOL (pool), FALSE);
 462   g_return_val_if_fail (config != NULL, FALSE);
 463
 464   GST_BUFFER_POOL_LOCK (pool);
 465   /* can't change the settings when active */
 466   if (pool->active)
 467     goto was_active;
 468
 469   /* we can't change when outstanding buffers */
 470   if (g_atomic_int_get (&pool->outstanding) != 0)
 471     goto have_outstanding;
 472
 473   pclass = GST_BUFFER_POOL_GET_CLASS (pool);
 474
 475   /* set the new config */
 476   if (G_LIKELY (pclass->set_config))
 477     result = pclass->set_config (pool, config);
 478   else
 479     result = FALSE;
 480
 481   if (result) {
 482     if (pool->config)
 483       gst_structure_free (pool->config);
 484     pool->config = config;
 485
 486     /* now we are configured */
 487     pool->configured = TRUE;
 488   }
 489   GST_BUFFER_POOL_UNLOCK (pool);
 490
 491   return result;
 492
 493   /* ERRORS */
 494 was_active:
 495   {
 496     GST_WARNING_OBJECT (pool, "can't change config, we are active");
 497     GST_BUFFER_POOL_UNLOCK (pool);
 498     return FALSE;
 499   }
 500 have_outstanding:
 501   {
 502     GST_WARNING_OBJECT (pool, "can't change config, have outstanding buffers");
 503     GST_BUFFER_POOL_UNLOCK (pool);
 504     return FALSE;
 505   }
 506 }
 507
 508 /**
 509  * gst_buffer_pool_get_config:
 510  * @pool: a #GstBufferPool
 511  *
 512  * Get a copy of the current configuration of the pool. This configuration
 513  * can either be modified and used for the gst_buffer_pool_set_config() call
 514  * or it must be freed after usage.
 515  *
 516  * Returns: (transfer full): a copy of the current configuration of @pool. use
 517  * gst_structure_free() after usage or gst_buffer_pool_set_config().
 518  */
 519 GstStructure *
 520 gst_buffer_pool_get_config (GstBufferPool * pool)
 521 {
 522   GstStructure *result;
 523
 524   g_return_val_if_fail (GST_IS_BUFFER_POOL (pool), NULL);
 525
 526   GST_BUFFER_POOL_UNLOCK (pool);
 527   result = gst_structure_copy (pool->config);
 528   GST_BUFFER_POOL_UNLOCK (pool);
 529
 530   return result;
 531 }
 532
 533 static const gchar *empty_option[] = { NULL };
 534
 535 /**
 536  * gst_buffer_pool_get_options:
 537  * @pool: a #GstBufferPool
 538  *
 539  * Get a NULL terminated array of string with supported bufferpool options for
 540  * @pool. An option would typically be enabled with
 541  * gst_buffer_pool_config_add_option().
 542  *
 543  * Returns: (array zero-terminated=1) (transfer none): a NULL terminated array of strings.
 544  */
 545 const gchar **
 546 gst_buffer_pool_get_options (GstBufferPool * pool)
 547 {
 548   GstBufferPoolClass *pclass;
 549   const gchar **result;
 550
 551   g_return_val_if_fail (GST_IS_BUFFER_POOL (pool), NULL);
 552
 553   pclass = GST_BUFFER_POOL_GET_CLASS (pool);
 554
 555   if (G_LIKELY (pclass->get_options)) {
 556     if ((result = pclass->get_options (pool)) == NULL)
 557       goto invalid_result;
 558   } else
 559     result = empty_option;
 560
 561   return result;
 562
 563   /* ERROR */
 564 invalid_result:
 565   {
 566     g_warning ("bufferpool subclass returned NULL options");
 567     return empty_option;
 568   }
 569 }
 570
 571 /**
 572  * gst_buffer_pool_has_option:
 573  * @pool: a #GstBufferPool
 574  * @option: an option
 575  *
 576  * Check if the bufferpool supports @option.
 577  *
 578  * Returns: a NULL terminated array of strings.
 579  */
 580 gboolean
 581 gst_buffer_pool_has_option (GstBufferPool * pool, const gchar * option)
 582 {
 583   guint i;
 584   const gchar **options;
 585
 586   g_return_val_if_fail (GST_IS_BUFFER_POOL (pool), FALSE);
 587   g_return_val_if_fail (option != NULL, FALSE);
 588
 589   options = gst_buffer_pool_get_options (pool);
 590
 591   for (i = 0; options[i]; i++) {
 592     if (g_str_equal (options[i], option))
 593       return TRUE;
 594   }
 595   return FALSE;
 596 }
 597
 598 /**
 599  * gst_buffer_pool_config_set:
 600  * @config: a #GstBufferPool configuration
 601  * @caps: caps for the buffers
 602  * @size: the size of each buffer, not including prefix
 603  * @min_buffers: the minimum amount of buffers to allocate.
 604  * @max_buffers: the maximum amount of buffers to allocate or 0 for unlimited.
 605  * @prefix: prefix each buffer with this many bytes
 606  * @align: alignment of the buffer data.
 607  *
 608  * Configure @config with the given parameters.
 609  */
 610 void
 611 gst_buffer_pool_config_set (GstStructure * config, const GstCaps * caps,
 612     guint size, guint min_buffers, guint max_buffers, guint prefix, guint align)
 613 {
 614   g_return_if_fail (config != NULL);
 615
 616   gst_structure_id_set (config,
 617       GST_QUARK (CAPS), GST_TYPE_CAPS, caps,
 618       GST_QUARK (SIZE), G_TYPE_UINT, size,
 619       GST_QUARK (MIN_BUFFERS), G_TYPE_UINT, min_buffers,
 620       GST_QUARK (MAX_BUFFERS), G_TYPE_UINT, max_buffers,
 621       GST_QUARK (PREFIX), G_TYPE_UINT, prefix,
 622       GST_QUARK (ALIGN), G_TYPE_UINT, align, NULL);
 623 }
 624
 625 /**
 626  * gst_buffer_pool_config_add_option:
 627  * @config: a #GstBufferPool configuration
 628  * @option: an option to add
 629  *
 630  * Enabled the option in @config. This will instruct the @bufferpool to enable
 631  * the specified option on the buffers that it allocates.
 632  *
 633  * The supported options by @pool can be retrieved with gst_buffer_pool_get_options().
 634  */
 635 void
 636 gst_buffer_pool_config_add_option (GstStructure * config, const gchar * option)
 637 {
 638   const GValue *value;
 639   GValue option_value = { 0, };
 640   guint i, len;
 641
 642   g_return_if_fail (config != NULL);
 643
 644   value = gst_structure_id_get_value (config, GST_QUARK (OPTIONS));
 645   if (value) {
 646     len = gst_value_array_get_size (value);
 647     for (i = 0; i < len; ++i) {
 648       const GValue *nth_val = gst_value_array_get_value (value, i);
 649
 650       if (g_str_equal (option, g_value_get_string (nth_val)))
 651         return;
 652     }
 653   } else {
 654     GValue new_array_val = { 0, };
 655
 656     g_value_init (&new_array_val, GST_TYPE_ARRAY);
 657     gst_structure_id_take_value (config, GST_QUARK (OPTIONS), &new_array_val);
 658     value = gst_structure_id_get_value (config, GST_QUARK (OPTIONS));
 659   }
 660   g_value_init (&option_value, G_TYPE_STRING);
 661   g_value_set_string (&option_value, option);
 662   gst_value_array_append_value ((GValue *) value, &option_value);
 663   g_value_unset (&option_value);
 664 }
 665
 666 /**
 667  * gst_buffer_pool_config_n_options:
 668  * @config: a #GstBufferPool configuration
 669  *
 670  * Retrieve the number of values currently stored in the
 671  * options array of the @config structure.
 672  *
 673  * Returns: the options array size as a #guint.
 674  */
 675 guint
 676 gst_buffer_pool_config_n_options (GstStructure * config)
 677 {
 678   const GValue *value;
 679   guint size = 0;
 680
 681   g_return_val_if_fail (config != NULL, 0);
 682
 683   value = gst_structure_id_get_value (config, GST_QUARK (OPTIONS));
 684   if (value) {
 685     size = gst_value_array_get_size (value);
 686   }
 687   return size;
 688 }
 689
 690 /**
 691  * gst_buffer_pool_config_get_option:
 692  * @config: a #GstBufferPool configuration
 693  * @index: position in the option array to read
 694  *
 695  * Parse an available @config and get the option
 696  * at @index of the options API array.
 697  *
 698  * Returns: a #gchar of the option at @index.
 699  */
 700 const gchar *
 701 gst_buffer_pool_config_get_option (GstStructure * config, guint index)
 702 {
 703   const GValue *value;
 704   const gchar *ret = NULL;
 705
 706   g_return_val_if_fail (config != NULL, 0);
 707
 708   value = gst_structure_id_get_value (config, GST_QUARK (OPTIONS));
 709   if (value) {
 710     const GValue *option_value;
 711
 712     option_value = gst_value_array_get_value (value, index);
 713     if (option_value)
 714       ret = g_value_get_string (option_value);
 715   }
 716   return ret;
 717 }
 718
 719 /**
 720  * gst_buffer_pool_config_has_option:
 721  * @config: a #GstBufferPool configuration
 722  * @option: an option
 723  *
 724  * Check if @config contains @option
 725  *
 726  * Returns: TRUE if the options array contains @option.
 727  */
 728 gboolean
 729 gst_buffer_pool_config_has_option (GstStructure * config, const gchar * option)
 730 {
 731   const GValue *value;
 732   guint i, len;
 733
 734   g_return_val_if_fail (config != NULL, 0);
 735
 736   value = gst_structure_id_get_value (config, GST_QUARK (OPTIONS));
 737   if (value) {
 738     len = gst_value_array_get_size (value);
 739     for (i = 0; i < len; ++i) {
 740       const GValue *nth_val = gst_value_array_get_value (value, i);
 741
 742       if (g_str_equal (option, g_value_get_string (nth_val)))
 743         return TRUE;
 744     }
 745   }
 746   return FALSE;
 747 }
 748
 749 /**
 750  * gst_buffer_pool_config_get:
 751  * @config: (transfer none): a #GstBufferPool configuration
 752  * @caps: (out): the caps of buffers
 753  * @size: (out): the size of each buffer, not including prefix
 754  * @min_buffers: (out): the minimum amount of buffers to allocate.
 755  * @max_buffers: (out): the maximum amount of buffers to allocate or 0 for unlimited.
 756  * @prefix: (out): prefix each buffer with this many bytes
 757  * @align: (out): alignment of the buffer data.
 758  *
 759  * Get the configuration values from @config.
 760  */
 761 gboolean
 762 gst_buffer_pool_config_get (GstStructure * config, const GstCaps ** caps,
 763     guint * size, guint * min_buffers, guint * max_buffers, guint * prefix,
 764     guint * align)
 765 {
 766   g_return_val_if_fail (config != NULL, FALSE);
 767
 768   return gst_structure_id_get (config,
 769       GST_QUARK (CAPS), GST_TYPE_CAPS, caps,
 770       GST_QUARK (SIZE), G_TYPE_UINT, size,
 771       GST_QUARK (MIN_BUFFERS), G_TYPE_UINT, min_buffers,
 772       GST_QUARK (MAX_BUFFERS), G_TYPE_UINT, max_buffers,
 773       GST_QUARK (PREFIX), G_TYPE_UINT, prefix,
 774       GST_QUARK (ALIGN), G_TYPE_UINT, align, NULL);
 775 }
 776
 777 static GstFlowReturn
 778 default_acquire_buffer (GstBufferPool * pool, GstBuffer ** buffer,
 779     GstBufferPoolParams * params)
 780 {
 781   GstFlowReturn result;
 782   GstBufferPoolClass *pclass;
 783   GstBufferPoolPrivate *priv = pool->priv;
 784
 785   pclass = GST_BUFFER_POOL_GET_CLASS (pool);
 786
 787   while (TRUE) {
 788     if (G_UNLIKELY (g_atomic_int_get (&pool->flushing)))
 789       goto flushing;
 790
 791     /* try to get a buffer from the queue */
 792     *buffer = gst_atomic_queue_pop (pool->queue);
 793     if (G_LIKELY (*buffer)) {
 794       gst_poll_read_control (pool->poll);
 795       result = GST_FLOW_OK;
 796       GST_LOG_OBJECT (pool, "acquired buffer %p", *buffer);
 797       break;
 798     }
 799
 800     /* no buffer */
 801     if (priv->max_buffers == 0) {
 802       /* no max_buffers, we allocate some more */
 803       if (G_LIKELY (pclass->alloc_buffer)) {
 804         result = pclass->alloc_buffer (pool, buffer, params);
 805         if (result == GST_FLOW_OK && *buffer)
 806           gst_buffer_foreach_meta (*buffer, mark_meta_pooled, pool);
 807         else
 808           result = GST_FLOW_ERROR;
 809       } else
 810         result = GST_FLOW_NOT_SUPPORTED;
 811       GST_LOG_OBJECT (pool, "alloc buffer %p", *buffer);
 812       break;
 813     }
 814
 815     /* check if we need to wait */
 816     if (params && (params->flags & GST_BUFFER_POOL_FLAG_DONTWAIT)) {
 817       GST_LOG_OBJECT (pool, "no more buffers");
 818       result = GST_FLOW_EOS;
 819       break;
 820     }
 821
 822     /* now wait */
 823     GST_LOG_OBJECT (pool, "waiting for free buffers");
 824     gst_poll_wait (pool->poll, GST_CLOCK_TIME_NONE);
 825   }
 826
 827   return result;
 828
 829   /* ERRORS */
 830 flushing:
 831   {
 832     GST_DEBUG_OBJECT (pool, "we are flushing");
 833     return GST_FLOW_FLUSHING;
 834   }
 835 }
 836
 837 static inline void
 838 dec_outstanding (GstBufferPool * pool)
 839 {
 840   if (g_atomic_int_dec_and_test (&pool->outstanding)) {
 841     /* all buffers are returned to the pool, see if we need to free them */
 842     if (g_atomic_int_get (&pool->flushing)) {
 843       /* take the lock so that set_active is not run concurrently */
 844       GST_BUFFER_POOL_LOCK (pool);
 845       /* recheck the flushing state in the lock, the pool could have been
 846        * set to active again */
 847       if (g_atomic_int_get (&pool->flushing))
 848         do_stop (pool);
 849
 850       GST_BUFFER_POOL_UNLOCK (pool);
 851     }
 852   }
 853 }
 854
 855 static gboolean
 856 remove_meta_unpooled (GstBuffer * buffer, GstMeta ** meta, gpointer user_data)
 857 {
 858   if (!GST_META_FLAG_IS_SET (*meta, GST_META_FLAG_POOLED))
 859     *meta = NULL;
 860   return TRUE;
 861 }
 862
 863 static void
 864 default_reset_buffer (GstBufferPool * pool, GstBuffer * buffer,
 865     GstBufferPoolParams * params)
 866 {
 867   GST_BUFFER_FLAGS (buffer) = 0;
 868
 869   GST_BUFFER_PTS (buffer) = GST_CLOCK_TIME_NONE;
 870   GST_BUFFER_DTS (buffer) = GST_CLOCK_TIME_NONE;
 871   GST_BUFFER_DURATION (buffer) = GST_CLOCK_TIME_NONE;
 872   GST_BUFFER_OFFSET (buffer) = GST_BUFFER_OFFSET_NONE;
 873   GST_BUFFER_OFFSET_END (buffer) = GST_BUFFER_OFFSET_NONE;
 874
 875   /* remove all metadata without the POOLED flag */
 876   gst_buffer_foreach_meta (buffer, remove_meta_unpooled, pool);
 877 }
 878
 879 /**
 880  * gst_buffer_pool_acquire_buffer:
 881  * @pool: a #GstBufferPool
 882  * @buffer: (out): a location for a #GstBuffer
 883  * @params: (transfer none) (allow-none) parameters.
 884  *
 885  * Acquire a buffer from @pool. @buffer should point to a memory location that
 886  * can hold a pointer to the new buffer.
 887  *
 888  * @params can be NULL or contain optional parameters to influence the allocation.
 889  *
 890  * Returns: a #GstFlowReturn such as GST_FLOW_FLUSHING when the pool is
 891  * inactive.
 892  */
 893 GstFlowReturn
 894 gst_buffer_pool_acquire_buffer (GstBufferPool * pool, GstBuffer ** buffer,
 895     GstBufferPoolParams * params)
 896 {
 897   GstBufferPoolClass *pclass;
 898   GstFlowReturn result;
 899
 900   g_return_val_if_fail (GST_IS_BUFFER_POOL (pool), GST_FLOW_ERROR);
 901   g_return_val_if_fail (buffer != NULL, GST_FLOW_ERROR);
 902
 903   pclass = GST_BUFFER_POOL_GET_CLASS (pool);
 904
 905   /* assume we'll have one more outstanding buffer we need to do that so
 906    * that concurrent set_active doesn't clear the buffers */
 907   g_atomic_int_inc (&pool->outstanding);
 908
 909   if (G_LIKELY (pclass->acquire_buffer))
 910     result = pclass->acquire_buffer (pool, buffer, params);
 911   else
 912     result = GST_FLOW_NOT_SUPPORTED;
 913
 914   if (G_LIKELY (result == GST_FLOW_OK)) {
 915     /* all buffers from the pool point to the pool and have the refcount of the
 916      * pool incremented */
 917     (*buffer)->pool = gst_object_ref (pool);
 918     /* now reset the buffer when needed */
 919     if (G_LIKELY (pclass->reset_buffer))
 920       pclass->reset_buffer (pool, *buffer, params);
 921   } else {
 922     dec_outstanding (pool);
 923   }
 924
 925   return result;
 926 }
 927
 928 static void
 929 default_release_buffer (GstBufferPool * pool, GstBuffer * buffer)
 930 {
 931   /* keep it around in our queue */
 932   GST_LOG_OBJECT (pool, "released buffer %p", buffer);
 933   gst_atomic_queue_push (pool->queue, buffer);
 934   gst_poll_write_control (pool->poll);
 935 }
 936
 937 /**
 938  * gst_buffer_pool_release_buffer:
 939  * @pool: a #GstBufferPool
 940  * @buffer: (transfer none): a #GstBuffer
 941  *
 942  * Release @buffer to @pool. @buffer should have previously been allocated from
 943  * @pool with gst_buffer_pool_acquire_buffer().
 944  *
 945  * This function is usually called automatically when the last ref on @buffer
 946  * disappears.
 947  */
 948 void
 949 gst_buffer_pool_release_buffer (GstBufferPool * pool, GstBuffer * buffer)
 950 {
 951   GstBufferPoolClass *pclass;
 952
 953   g_return_if_fail (GST_IS_BUFFER_POOL (pool));
 954   g_return_if_fail (buffer != NULL);
 955
 956   /* check that the buffer is ours, all buffers returned to the pool have the
 957    * pool member set to NULL and the pool refcount decreased */
 958   if (!g_atomic_pointer_compare_and_exchange (&buffer->pool, pool, NULL))
 959     return;
 960
 961   pclass = GST_BUFFER_POOL_GET_CLASS (pool);
 962
 963   if (G_LIKELY (pclass->release_buffer))
 964     pclass->release_buffer (pool, buffer);
 965
 966   dec_outstanding (pool);
 967
 968   /* decrease the refcount that the buffer had to us */
 969   gst_object_unref (pool);
 970 }