2 * Copyright (C) 2010 Wim Taymans <wim.taymans@gmail.com>
4 * gstbufferpool.c: GstBufferPool baseclass
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.
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.
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., 51 Franklin St, Fifth Floor,
19 * Boston, MA 02110-1301, USA.
23 * SECTION:gstbufferpool
24 * @title: GstBufferPool
25 * @short_description: Pool for buffers
26 * @see_also: #GstBuffer
28 * A #GstBufferPool is an object that can be used to pre-allocate and recycle
29 * buffers of the same size and with the same properties.
31 * A #GstBufferPool is created with gst_buffer_pool_new().
33 * Once a pool is created, it needs to be configured. A call to
34 * gst_buffer_pool_get_config() returns the current configuration structure from
35 * the pool. With gst_buffer_pool_config_set_params() and
36 * gst_buffer_pool_config_set_allocator() the bufferpool parameters and
37 * allocator can be configured. Other properties can be configured in the pool
38 * depending on the pool implementation.
40 * A bufferpool can have extra options that can be enabled with
41 * gst_buffer_pool_config_add_option(). The available options can be retrieved
42 * with gst_buffer_pool_get_options(). Some options allow for additional
43 * configuration properties to be set.
45 * After the configuration structure has been configured,
46 * gst_buffer_pool_set_config() updates the configuration in the pool. This can
47 * fail when the configuration structure is not accepted.
49 * After the a pool has been configured, it can be activated with
50 * gst_buffer_pool_set_active(). This will preallocate the configured resources
53 * When the pool is active, gst_buffer_pool_acquire_buffer() can be used to
54 * retrieve a buffer from the pool.
56 * Buffers allocated from a bufferpool will automatically be returned to the
57 * pool with gst_buffer_pool_release_buffer() when their refcount drops to 0.
59 * The bufferpool can be deactivated again with gst_buffer_pool_set_active().
60 * All further gst_buffer_pool_acquire_buffer() calls will return an error. When
61 * all buffers are returned to the pool they will be freed.
63 * Use gst_object_unref() to release the reference to a bufferpool. If the
64 * refcount of the pool reaches 0, the pool will be freed.
67 #include "gst_private.h"
68 #include "glib-compat-private.h"
74 #include <sys/types.h>
76 #include "gstatomicqueue.h"
82 #include "gstbufferpool.h"
86 # define EWOULDBLOCK EAGAIN /* This is just to placate gcc */
88 #endif /* G_OS_WIN32 */
90 GST_DEBUG_CATEGORY_STATIC (gst_buffer_pool_debug);
91 #define GST_CAT_DEFAULT gst_buffer_pool_debug
93 #define GST_BUFFER_POOL_GET_PRIVATE(obj) \
94 (G_TYPE_INSTANCE_GET_PRIVATE ((obj), GST_TYPE_BUFFER_POOL, GstBufferPoolPrivate))
96 #define GST_BUFFER_POOL_LOCK(pool) (g_rec_mutex_lock(&pool->priv->rec_lock))
97 #define GST_BUFFER_POOL_UNLOCK(pool) (g_rec_mutex_unlock(&pool->priv->rec_lock))
99 struct _GstBufferPoolPrivate
101 GstAtomicQueue *queue;
108 gint outstanding; /* number of buffers that are in use */
111 GstStructure *config;
117 GstAllocator *allocator;
118 GstAllocationParams params;
121 static void gst_buffer_pool_finalize (GObject * object);
123 G_DEFINE_TYPE (GstBufferPool, gst_buffer_pool, GST_TYPE_OBJECT);
125 static gboolean default_start (GstBufferPool * pool);
126 static gboolean default_stop (GstBufferPool * pool);
127 static gboolean default_set_config (GstBufferPool * pool,
128 GstStructure * config);
129 static GstFlowReturn default_alloc_buffer (GstBufferPool * pool,
130 GstBuffer ** buffer, GstBufferPoolAcquireParams * params);
131 static GstFlowReturn default_acquire_buffer (GstBufferPool * pool,
132 GstBuffer ** buffer, GstBufferPoolAcquireParams * params);
133 static void default_reset_buffer (GstBufferPool * pool, GstBuffer * buffer);
134 static void default_free_buffer (GstBufferPool * pool, GstBuffer * buffer);
135 static void default_release_buffer (GstBufferPool * pool, GstBuffer * buffer);
138 gst_buffer_pool_class_init (GstBufferPoolClass * klass)
140 GObjectClass *gobject_class = (GObjectClass *) klass;
142 g_type_class_add_private (klass, sizeof (GstBufferPoolPrivate));
144 gobject_class->finalize = gst_buffer_pool_finalize;
146 klass->start = default_start;
147 klass->stop = default_stop;
148 klass->set_config = default_set_config;
149 klass->acquire_buffer = default_acquire_buffer;
150 klass->reset_buffer = default_reset_buffer;
151 klass->alloc_buffer = default_alloc_buffer;
152 klass->release_buffer = default_release_buffer;
153 klass->free_buffer = default_free_buffer;
155 GST_DEBUG_CATEGORY_INIT (gst_buffer_pool_debug, "bufferpool", 0,
160 gst_buffer_pool_init (GstBufferPool * pool)
162 GstBufferPoolPrivate *priv;
164 priv = pool->priv = GST_BUFFER_POOL_GET_PRIVATE (pool);
166 g_rec_mutex_init (&priv->rec_lock);
168 priv->poll = gst_poll_new_timer ();
169 priv->queue = gst_atomic_queue_new (16);
171 priv->active = FALSE;
172 priv->configured = FALSE;
173 priv->started = FALSE;
174 priv->config = gst_structure_new_id_empty (GST_QUARK (BUFFER_POOL_CONFIG));
175 gst_buffer_pool_config_set_params (priv->config, NULL, 0, 0, 0);
176 priv->allocator = NULL;
177 gst_allocation_params_init (&priv->params);
178 gst_buffer_pool_config_set_allocator (priv->config, priv->allocator,
180 /* 1 control write for flushing - the flush token */
181 gst_poll_write_control (priv->poll);
182 /* 1 control write for marking that we are not waiting for poll - the wait token */
183 gst_poll_write_control (priv->poll);
185 GST_DEBUG_OBJECT (pool, "created");
189 gst_buffer_pool_finalize (GObject * object)
192 GstBufferPoolPrivate *priv;
194 pool = GST_BUFFER_POOL_CAST (object);
197 GST_DEBUG_OBJECT (pool, "%p finalize", pool);
199 gst_buffer_pool_set_active (pool, FALSE);
200 gst_atomic_queue_unref (priv->queue);
201 gst_poll_free (priv->poll);
202 gst_structure_free (priv->config);
203 g_rec_mutex_clear (&priv->rec_lock);
205 gst_object_unref (priv->allocator);
207 G_OBJECT_CLASS (gst_buffer_pool_parent_class)->finalize (object);
211 * gst_buffer_pool_new:
213 * Creates a new #GstBufferPool instance.
215 * Returns: (transfer floating): a new #GstBufferPool instance
218 gst_buffer_pool_new (void)
220 GstBufferPool *result;
222 result = g_object_newv (GST_TYPE_BUFFER_POOL, 0, NULL);
223 GST_DEBUG_OBJECT (result, "created new buffer pool");
229 default_alloc_buffer (GstBufferPool * pool, GstBuffer ** buffer,
230 GstBufferPoolAcquireParams * params)
232 GstBufferPoolPrivate *priv = pool->priv;
235 gst_buffer_new_allocate (priv->allocator, priv->size, &priv->params);
238 return GST_FLOW_ERROR;
244 mark_meta_pooled (GstBuffer * buffer, GstMeta ** meta, gpointer user_data)
246 GST_DEBUG_OBJECT (GST_BUFFER_POOL (user_data),
247 "marking meta %p as POOLED in buffer %p", *meta, buffer);
248 GST_META_FLAG_SET (*meta, GST_META_FLAG_POOLED);
249 GST_META_FLAG_SET (*meta, GST_META_FLAG_LOCKED);
255 do_alloc_buffer (GstBufferPool * pool, GstBuffer ** buffer,
256 GstBufferPoolAcquireParams * params)
258 GstBufferPoolPrivate *priv = pool->priv;
259 GstFlowReturn result;
260 gint cur_buffers, max_buffers;
261 GstBufferPoolClass *pclass;
263 pclass = GST_BUFFER_POOL_GET_CLASS (pool);
265 if (G_UNLIKELY (!pclass->alloc_buffer))
268 max_buffers = priv->max_buffers;
270 /* increment the allocation counter */
271 cur_buffers = g_atomic_int_add (&priv->cur_buffers, 1);
272 if (max_buffers && cur_buffers >= max_buffers)
275 result = pclass->alloc_buffer (pool, buffer, params);
276 if (G_UNLIKELY (result != GST_FLOW_OK))
279 /* lock all metadata and mark as pooled, we want this to remain on
280 * the buffer and we want to remove any other metadata that gets added
282 gst_buffer_foreach_meta (*buffer, mark_meta_pooled, pool);
284 /* un-tag memory, this is how we expect the buffer when it is
286 GST_BUFFER_FLAG_UNSET (*buffer, GST_BUFFER_FLAG_TAG_MEMORY);
288 GST_LOG_OBJECT (pool, "allocated buffer %d/%d, %p", cur_buffers,
289 max_buffers, *buffer);
296 GST_ERROR_OBJECT (pool, "no alloc function");
297 return GST_FLOW_NOT_SUPPORTED;
301 GST_DEBUG_OBJECT (pool, "max buffers reached");
302 g_atomic_int_add (&priv->cur_buffers, -1);
307 GST_WARNING_OBJECT (pool, "alloc function failed");
308 g_atomic_int_add (&priv->cur_buffers, -1);
313 /* the default implementation for preallocating the buffers in the pool */
315 default_start (GstBufferPool * pool)
318 GstBufferPoolPrivate *priv = pool->priv;
319 GstBufferPoolClass *pclass;
321 pclass = GST_BUFFER_POOL_GET_CLASS (pool);
323 /* we need to prealloc buffers */
324 for (i = 0; i < priv->min_buffers; i++) {
327 if (do_alloc_buffer (pool, &buffer, NULL) != GST_FLOW_OK)
330 /* release to the queue, we call the vmethod directly, we don't need to do
331 * the other refcount handling right now. */
332 if (G_LIKELY (pclass->release_buffer))
333 pclass->release_buffer (pool, buffer);
340 GST_WARNING_OBJECT (pool, "failed to allocate buffer");
345 /* must be called with the lock */
347 do_start (GstBufferPool * pool)
349 GstBufferPoolPrivate *priv = pool->priv;
351 if (!priv->started) {
352 GstBufferPoolClass *pclass;
354 pclass = GST_BUFFER_POOL_GET_CLASS (pool);
356 GST_LOG_OBJECT (pool, "starting");
357 /* start the pool, subclasses should allocate buffers and put them
359 if (G_LIKELY (pclass->start)) {
360 if (!pclass->start (pool))
363 priv->started = TRUE;
369 default_free_buffer (GstBufferPool * pool, GstBuffer * buffer)
371 gst_buffer_unref (buffer);
375 do_free_buffer (GstBufferPool * pool, GstBuffer * buffer)
377 GstBufferPoolPrivate *priv;
378 GstBufferPoolClass *pclass;
381 pclass = GST_BUFFER_POOL_GET_CLASS (pool);
383 g_atomic_int_add (&priv->cur_buffers, -1);
384 GST_LOG_OBJECT (pool, "freeing buffer %p (%u left)", buffer,
387 if (G_LIKELY (pclass->free_buffer))
388 pclass->free_buffer (pool, buffer);
391 /* must be called with the lock */
393 default_stop (GstBufferPool * pool)
395 GstBufferPoolPrivate *priv = pool->priv;
399 while ((buffer = gst_atomic_queue_pop (priv->queue))) {
400 while (!gst_poll_read_control (priv->poll)) {
401 if (errno == EWOULDBLOCK) {
402 /* We put the buffer into the queue but did not finish writing control
403 * yet, let's wait a bit and retry */
407 /* Critical error but GstPoll already complained */
411 do_free_buffer (pool, buffer);
413 return priv->cur_buffers == 0;
416 /* must be called with the lock */
418 do_stop (GstBufferPool * pool)
420 GstBufferPoolPrivate *priv = pool->priv;
423 GstBufferPoolClass *pclass;
425 pclass = GST_BUFFER_POOL_GET_CLASS (pool);
427 GST_LOG_OBJECT (pool, "stopping");
428 if (G_LIKELY (pclass->stop)) {
429 if (!pclass->stop (pool))
432 priv->started = FALSE;
437 /* must be called with the lock */
439 do_set_flushing (GstBufferPool * pool, gboolean flushing)
441 GstBufferPoolPrivate *priv = pool->priv;
442 GstBufferPoolClass *pclass;
444 pclass = GST_BUFFER_POOL_GET_CLASS (pool);
446 if (GST_BUFFER_POOL_IS_FLUSHING (pool) == flushing)
450 g_atomic_int_set (&pool->flushing, 1);
451 /* Write the flush token to wake up any waiters */
452 gst_poll_write_control (priv->poll);
454 if (pclass->flush_start)
455 pclass->flush_start (pool);
457 if (pclass->flush_stop)
458 pclass->flush_stop (pool);
460 while (!gst_poll_read_control (priv->poll)) {
461 if (errno == EWOULDBLOCK) {
462 /* This should not really happen unless flushing and unflushing
463 * happens on different threads. Let's wait a bit to get back flush
464 * token from the thread that was setting it to flushing */
468 /* Critical error but GstPoll already complained */
473 g_atomic_int_set (&pool->flushing, 0);
478 * gst_buffer_pool_set_active:
479 * @pool: a #GstBufferPool
480 * @active: the new active state
482 * Control the active state of @pool. When the pool is inactive, new calls to
483 * gst_buffer_pool_acquire_buffer() will return with %GST_FLOW_FLUSHING.
485 * Activating the bufferpool will preallocate all resources in the pool based on
486 * the configuration of the pool.
488 * Deactivating will free the resources again when there are no outstanding
489 * buffers. When there are outstanding buffers, they will be freed as soon as
490 * they are all returned to the pool.
492 * Returns: %FALSE when the pool was not configured or when preallocation of the
496 gst_buffer_pool_set_active (GstBufferPool * pool, gboolean active)
499 GstBufferPoolPrivate *priv;
501 g_return_val_if_fail (GST_IS_BUFFER_POOL (pool), FALSE);
503 GST_LOG_OBJECT (pool, "active %d", active);
507 GST_BUFFER_POOL_LOCK (pool);
508 /* just return if we are already in the right state */
509 if (priv->active == active)
512 /* we need to be configured */
513 if (!priv->configured)
517 if (!do_start (pool))
520 /* flush_stop my release buffers, setting to active to avoid running
521 * do_stop while activating the pool */
524 /* unset the flushing state now */
525 do_set_flushing (pool, FALSE);
529 /* set to flushing first */
530 do_set_flushing (pool, TRUE);
532 /* when all buffers are in the pool, free them. Else they will be
533 * freed when they are released */
534 outstanding = g_atomic_int_get (&priv->outstanding);
535 GST_LOG_OBJECT (pool, "outstanding buffers %d", outstanding);
536 if (outstanding == 0) {
541 priv->active = FALSE;
543 GST_BUFFER_POOL_UNLOCK (pool);
549 GST_DEBUG_OBJECT (pool, "pool was in the right state");
550 GST_BUFFER_POOL_UNLOCK (pool);
555 GST_ERROR_OBJECT (pool, "pool was not configured");
556 GST_BUFFER_POOL_UNLOCK (pool);
561 GST_ERROR_OBJECT (pool, "start failed");
562 GST_BUFFER_POOL_UNLOCK (pool);
567 GST_WARNING_OBJECT (pool, "stop failed");
568 GST_BUFFER_POOL_UNLOCK (pool);
574 * gst_buffer_pool_is_active:
575 * @pool: a #GstBufferPool
577 * Check if @pool is active. A pool can be activated with the
578 * gst_buffer_pool_set_active() call.
580 * Returns: %TRUE when the pool is active.
583 gst_buffer_pool_is_active (GstBufferPool * pool)
587 GST_BUFFER_POOL_LOCK (pool);
588 res = pool->priv->active;
589 GST_BUFFER_POOL_UNLOCK (pool);
595 default_set_config (GstBufferPool * pool, GstStructure * config)
597 GstBufferPoolPrivate *priv = pool->priv;
599 guint size, min_buffers, max_buffers;
600 GstAllocator *allocator;
601 GstAllocationParams params;
603 /* parse the config and keep around */
604 if (!gst_buffer_pool_config_get_params (config, &caps, &size, &min_buffers,
608 if (!gst_buffer_pool_config_get_allocator (config, &allocator, ¶ms))
611 GST_DEBUG_OBJECT (pool, "config %" GST_PTR_FORMAT, config);
614 priv->min_buffers = min_buffers;
615 priv->max_buffers = max_buffers;
616 priv->cur_buffers = 0;
619 gst_object_unref (priv->allocator);
620 if ((priv->allocator = allocator))
621 gst_object_ref (allocator);
622 priv->params = params;
628 GST_WARNING_OBJECT (pool, "invalid config %" GST_PTR_FORMAT, config);
634 * gst_buffer_pool_set_config:
635 * @pool: a #GstBufferPool
636 * @config: (transfer full): a #GstStructure
638 * Set the configuration of the pool. If the pool is already configured, and
639 * the configuration haven't change, this function will return %TRUE. If the
640 * pool is active, this method will return %FALSE and active configuration
641 * will remain. Buffers allocated form this pool must be returned or else this
642 * function will do nothing and return %FALSE.
644 * @config is a #GstStructure that contains the configuration parameters for
645 * the pool. A default and mandatory set of parameters can be configured with
646 * gst_buffer_pool_config_set_params(), gst_buffer_pool_config_set_allocator()
647 * and gst_buffer_pool_config_add_option().
649 * If the parameters in @config can not be set exactly, this function returns
650 * %FALSE and will try to update as much state as possible. The new state can
651 * then be retrieved and refined with gst_buffer_pool_get_config().
653 * This function takes ownership of @config.
655 * Returns: %TRUE when the configuration could be set.
658 gst_buffer_pool_set_config (GstBufferPool * pool, GstStructure * config)
661 GstBufferPoolClass *pclass;
662 GstBufferPoolPrivate *priv;
664 g_return_val_if_fail (GST_IS_BUFFER_POOL (pool), FALSE);
665 g_return_val_if_fail (config != NULL, FALSE);
669 GST_BUFFER_POOL_LOCK (pool);
671 /* nothing to do if config is unchanged */
672 if (priv->configured && gst_structure_is_equal (config, priv->config))
673 goto config_unchanged;
675 /* can't change the settings when active */
679 /* we can't change when outstanding buffers */
680 if (g_atomic_int_get (&priv->outstanding) != 0)
681 goto have_outstanding;
683 pclass = GST_BUFFER_POOL_GET_CLASS (pool);
685 /* set the new config */
686 if (G_LIKELY (pclass->set_config))
687 result = pclass->set_config (pool, config);
691 /* save the config regardless of the result so user can read back the
692 * modified config and evaluate if the changes are acceptable */
694 gst_structure_free (priv->config);
695 priv->config = config;
698 /* now we are configured */
699 priv->configured = TRUE;
701 GST_BUFFER_POOL_UNLOCK (pool);
707 gst_structure_free (config);
708 GST_BUFFER_POOL_UNLOCK (pool);
714 gst_structure_free (config);
715 GST_INFO_OBJECT (pool, "can't change config, we are active");
716 GST_BUFFER_POOL_UNLOCK (pool);
721 gst_structure_free (config);
722 GST_WARNING_OBJECT (pool, "can't change config, have outstanding buffers");
723 GST_BUFFER_POOL_UNLOCK (pool);
729 * gst_buffer_pool_get_config:
730 * @pool: a #GstBufferPool
732 * Get a copy of the current configuration of the pool. This configuration
733 * can either be modified and used for the gst_buffer_pool_set_config() call
734 * or it must be freed after usage.
736 * Returns: (transfer full): a copy of the current configuration of @pool. use
737 * gst_structure_free() after usage or gst_buffer_pool_set_config().
740 gst_buffer_pool_get_config (GstBufferPool * pool)
742 GstStructure *result;
744 g_return_val_if_fail (GST_IS_BUFFER_POOL (pool), NULL);
746 GST_BUFFER_POOL_LOCK (pool);
747 result = gst_structure_copy (pool->priv->config);
748 GST_BUFFER_POOL_UNLOCK (pool);
753 static const gchar *empty_option[] = { NULL };
756 * gst_buffer_pool_get_options:
757 * @pool: a #GstBufferPool
759 * Get a %NULL terminated array of string with supported bufferpool options for
760 * @pool. An option would typically be enabled with
761 * gst_buffer_pool_config_add_option().
763 * Returns: (array zero-terminated=1) (transfer none): a %NULL terminated array
767 gst_buffer_pool_get_options (GstBufferPool * pool)
769 GstBufferPoolClass *pclass;
770 const gchar **result;
772 g_return_val_if_fail (GST_IS_BUFFER_POOL (pool), NULL);
774 pclass = GST_BUFFER_POOL_GET_CLASS (pool);
776 if (G_LIKELY (pclass->get_options)) {
777 if ((result = pclass->get_options (pool)) == NULL)
780 result = empty_option;
787 g_warning ("bufferpool subclass returned NULL options");
793 * gst_buffer_pool_has_option:
794 * @pool: a #GstBufferPool
797 * Check if the bufferpool supports @option.
799 * Returns: %TRUE if the buffer pool contains @option.
802 gst_buffer_pool_has_option (GstBufferPool * pool, const gchar * option)
805 const gchar **options;
807 g_return_val_if_fail (GST_IS_BUFFER_POOL (pool), FALSE);
808 g_return_val_if_fail (option != NULL, FALSE);
810 options = gst_buffer_pool_get_options (pool);
812 for (i = 0; options[i]; i++) {
813 if (g_str_equal (options[i], option))
820 * gst_buffer_pool_config_set_params:
821 * @config: a #GstBufferPool configuration
822 * @caps: caps for the buffers
823 * @size: the size of each buffer, not including prefix and padding
824 * @min_buffers: the minimum amount of buffers to allocate.
825 * @max_buffers: the maximum amount of buffers to allocate or 0 for unlimited.
827 * Configure @config with the given parameters.
830 gst_buffer_pool_config_set_params (GstStructure * config, GstCaps * caps,
831 guint size, guint min_buffers, guint max_buffers)
833 g_return_if_fail (config != NULL);
834 g_return_if_fail (max_buffers == 0 || min_buffers <= max_buffers);
835 g_return_if_fail (caps == NULL || gst_caps_is_fixed (caps));
837 gst_structure_id_set (config,
838 GST_QUARK (CAPS), GST_TYPE_CAPS, caps,
839 GST_QUARK (SIZE), G_TYPE_UINT, size,
840 GST_QUARK (MIN_BUFFERS), G_TYPE_UINT, min_buffers,
841 GST_QUARK (MAX_BUFFERS), G_TYPE_UINT, max_buffers, NULL);
845 * gst_buffer_pool_config_set_allocator:
846 * @config: a #GstBufferPool configuration
847 * @allocator: (allow-none): a #GstAllocator
848 * @params: (allow-none): #GstAllocationParams
850 * Set the @allocator and @params on @config.
852 * One of @allocator and @params can be %NULL, but not both. When @allocator
853 * is %NULL, the default allocator of the pool will use the values in @param
854 * to perform its allocation. When @param is %NULL, the pool will use the
855 * provided @allocator with its default #GstAllocationParams.
857 * A call to gst_buffer_pool_set_config() can update the allocator and params
858 * with the values that it is able to do. Some pools are, for example, not able
859 * to operate with different allocators or cannot allocate with the values
860 * specified in @params. Use gst_buffer_pool_get_config() to get the currently
864 gst_buffer_pool_config_set_allocator (GstStructure * config,
865 GstAllocator * allocator, const GstAllocationParams * params)
867 g_return_if_fail (config != NULL);
868 g_return_if_fail (allocator != NULL || params != NULL);
870 gst_structure_id_set (config,
871 GST_QUARK (ALLOCATOR), GST_TYPE_ALLOCATOR, allocator,
872 GST_QUARK (PARAMS), GST_TYPE_ALLOCATION_PARAMS, params, NULL);
876 * gst_buffer_pool_config_add_option:
877 * @config: a #GstBufferPool configuration
878 * @option: an option to add
880 * Enabled the option in @config. This will instruct the @bufferpool to enable
881 * the specified option on the buffers that it allocates.
883 * The supported options by @pool can be retrieved with gst_buffer_pool_get_options().
886 gst_buffer_pool_config_add_option (GstStructure * config, const gchar * option)
889 GValue option_value = { 0, };
892 g_return_if_fail (config != NULL);
894 value = gst_structure_id_get_value (config, GST_QUARK (OPTIONS));
896 len = gst_value_array_get_size (value);
897 for (i = 0; i < len; ++i) {
898 const GValue *nth_val = gst_value_array_get_value (value, i);
900 if (g_str_equal (option, g_value_get_string (nth_val)))
904 GValue new_array_val = { 0, };
906 g_value_init (&new_array_val, GST_TYPE_ARRAY);
907 gst_structure_id_take_value (config, GST_QUARK (OPTIONS), &new_array_val);
908 value = gst_structure_id_get_value (config, GST_QUARK (OPTIONS));
910 g_value_init (&option_value, G_TYPE_STRING);
911 g_value_set_string (&option_value, option);
912 gst_value_array_append_and_take_value ((GValue *) value, &option_value);
916 * gst_buffer_pool_config_n_options:
917 * @config: a #GstBufferPool configuration
919 * Retrieve the number of values currently stored in the options array of the
922 * Returns: the options array size as a #guint.
925 gst_buffer_pool_config_n_options (GstStructure * config)
930 g_return_val_if_fail (config != NULL, 0);
932 value = gst_structure_id_get_value (config, GST_QUARK (OPTIONS));
934 size = gst_value_array_get_size (value);
940 * gst_buffer_pool_config_get_option:
941 * @config: a #GstBufferPool configuration
942 * @index: position in the option array to read
944 * Parse an available @config and get the option at @index of the options API
947 * Returns: a #gchar of the option at @index.
950 gst_buffer_pool_config_get_option (GstStructure * config, guint index)
953 const gchar *ret = NULL;
955 g_return_val_if_fail (config != NULL, 0);
957 value = gst_structure_id_get_value (config, GST_QUARK (OPTIONS));
959 const GValue *option_value;
961 option_value = gst_value_array_get_value (value, index);
963 ret = g_value_get_string (option_value);
969 * gst_buffer_pool_config_has_option:
970 * @config: a #GstBufferPool configuration
973 * Check if @config contains @option.
975 * Returns: %TRUE if the options array contains @option.
978 gst_buffer_pool_config_has_option (GstStructure * config, const gchar * option)
983 g_return_val_if_fail (config != NULL, 0);
985 value = gst_structure_id_get_value (config, GST_QUARK (OPTIONS));
987 len = gst_value_array_get_size (value);
988 for (i = 0; i < len; ++i) {
989 const GValue *nth_val = gst_value_array_get_value (value, i);
991 if (g_str_equal (option, g_value_get_string (nth_val)))
999 * gst_buffer_pool_config_get_params:
1000 * @config: (transfer none): a #GstBufferPool configuration
1001 * @caps: (out) (transfer none) (allow-none): the caps of buffers
1002 * @size: (out) (allow-none): the size of each buffer, not including prefix and padding
1003 * @min_buffers: (out) (allow-none): the minimum amount of buffers to allocate.
1004 * @max_buffers: (out) (allow-none): the maximum amount of buffers to allocate or 0 for unlimited.
1006 * Get the configuration values from @config.
1008 * Returns: %TRUE if all parameters could be fetched.
1011 gst_buffer_pool_config_get_params (GstStructure * config, GstCaps ** caps,
1012 guint * size, guint * min_buffers, guint * max_buffers)
1014 g_return_val_if_fail (config != NULL, FALSE);
1017 *caps = g_value_get_boxed (gst_structure_id_get_value (config,
1020 return gst_structure_id_get (config,
1021 GST_QUARK (SIZE), G_TYPE_UINT, size,
1022 GST_QUARK (MIN_BUFFERS), G_TYPE_UINT, min_buffers,
1023 GST_QUARK (MAX_BUFFERS), G_TYPE_UINT, max_buffers, NULL);
1027 * gst_buffer_pool_config_get_allocator:
1028 * @config: (transfer none): a #GstBufferPool configuration
1029 * @allocator: (out) (allow-none) (transfer none): a #GstAllocator, or %NULL
1030 * @params: (out) (allow-none): #GstAllocationParams, or %NULL
1032 * Get the @allocator and @params from @config.
1034 * Returns: %TRUE, if the values are set.
1037 gst_buffer_pool_config_get_allocator (GstStructure * config,
1038 GstAllocator ** allocator, GstAllocationParams * params)
1040 g_return_val_if_fail (config != NULL, FALSE);
1043 *allocator = g_value_get_object (gst_structure_id_get_value (config,
1044 GST_QUARK (ALLOCATOR)));
1046 GstAllocationParams *p;
1048 p = g_value_get_boxed (gst_structure_id_get_value (config,
1049 GST_QUARK (PARAMS)));
1053 gst_allocation_params_init (params);
1060 * gst_buffer_pool_config_validate_params:
1061 * @config: (transfer none): a #GstBufferPool configuration
1062 * @caps: (transfer none): the excepted caps of buffers
1063 * @size: the expected size of each buffer, not including prefix and padding
1064 * @min_buffers: the expected minimum amount of buffers to allocate.
1065 * @max_buffers: the expect maximum amount of buffers to allocate or 0 for unlimited.
1067 * Validate that changes made to @config are still valid in the context of the
1068 * expected parameters. This function is a helper that can be used to validate
1069 * changes made by a pool to a config when gst_buffer_pool_set_config()
1070 * returns %FALSE. This expects that @caps haven't changed and that
1071 * @min_buffers aren't lower then what we initially expected.
1072 * This does not check if options or allocator parameters are still valid,
1073 * won't check if size have changed, since changing the size is valid to adapt
1078 * Returns: %TRUE, if the parameters are valid in this context.
1081 gst_buffer_pool_config_validate_params (GstStructure * config, GstCaps * caps,
1082 guint size, guint min_buffers, G_GNUC_UNUSED guint max_buffers)
1085 guint newsize, newmin;
1086 gboolean ret = FALSE;
1088 g_return_val_if_fail (config != NULL, FALSE);
1090 gst_buffer_pool_config_get_params (config, &newcaps, &newsize, &newmin, NULL);
1092 if (gst_caps_is_equal (caps, newcaps) && (newsize >= size)
1093 && (newmin >= min_buffers))
1099 static GstFlowReturn
1100 default_acquire_buffer (GstBufferPool * pool, GstBuffer ** buffer,
1101 GstBufferPoolAcquireParams * params)
1103 GstFlowReturn result;
1104 GstBufferPoolPrivate *priv = pool->priv;
1107 if (G_UNLIKELY (GST_BUFFER_POOL_IS_FLUSHING (pool)))
1110 /* try to get a buffer from the queue */
1111 *buffer = gst_atomic_queue_pop (priv->queue);
1112 if (G_LIKELY (*buffer)) {
1113 while (!gst_poll_read_control (priv->poll)) {
1114 if (errno == EWOULDBLOCK) {
1115 /* We put the buffer into the queue but did not finish writing control
1116 * yet, let's wait a bit and retry */
1120 /* Critical error but GstPoll already complained */
1124 result = GST_FLOW_OK;
1125 GST_LOG_OBJECT (pool, "acquired buffer %p", *buffer);
1129 /* no buffer, try to allocate some more */
1130 GST_LOG_OBJECT (pool, "no buffer, trying to allocate");
1131 result = do_alloc_buffer (pool, buffer, params);
1132 if (G_LIKELY (result == GST_FLOW_OK))
1133 /* we have a buffer, return it */
1136 if (G_UNLIKELY (result != GST_FLOW_EOS))
1137 /* something went wrong, return error */
1140 /* check if we need to wait */
1141 if (params && (params->flags & GST_BUFFER_POOL_ACQUIRE_FLAG_DONTWAIT)) {
1142 GST_LOG_OBJECT (pool, "no more buffers");
1146 /* now we release the control socket, we wait for a buffer release or
1148 if (!gst_poll_read_control (pool->priv->poll)) {
1149 if (errno == EWOULDBLOCK) {
1150 /* This means that we have two threads trying to allocate buffers
1151 * already, and the other one already got the wait token. This
1152 * means that we only have to wait for the poll now and not write the
1153 * token afterwards: we will be woken up once the other thread is
1154 * woken up and that one will write the wait token it removed */
1155 GST_LOG_OBJECT (pool, "waiting for free buffers or flushing");
1156 gst_poll_wait (priv->poll, GST_CLOCK_TIME_NONE);
1158 /* This is a critical error, GstPoll already gave a warning */
1159 result = GST_FLOW_ERROR;
1163 /* We're the first thread waiting, we got the wait token and have to
1164 * write it again later
1166 * We're a second thread and just consumed the flush token and block all
1167 * other threads, in which case we must not wait and give it back
1169 if (!GST_BUFFER_POOL_IS_FLUSHING (pool)) {
1170 GST_LOG_OBJECT (pool, "waiting for free buffers or flushing");
1171 gst_poll_wait (priv->poll, GST_CLOCK_TIME_NONE);
1173 gst_poll_write_control (pool->priv->poll);
1182 GST_DEBUG_OBJECT (pool, "we are flushing");
1183 return GST_FLOW_FLUSHING;
1188 dec_outstanding (GstBufferPool * pool)
1190 if (g_atomic_int_dec_and_test (&pool->priv->outstanding)) {
1191 /* all buffers are returned to the pool, see if we need to free them */
1192 if (GST_BUFFER_POOL_IS_FLUSHING (pool)) {
1193 /* take the lock so that set_active is not run concurrently */
1194 GST_BUFFER_POOL_LOCK (pool);
1195 /* now that we have the lock, check if we have been de-activated with
1196 * outstanding buffers */
1197 if (!pool->priv->active)
1200 GST_BUFFER_POOL_UNLOCK (pool);
1206 remove_meta_unpooled (GstBuffer * buffer, GstMeta ** meta, gpointer user_data)
1208 if (!GST_META_FLAG_IS_SET (*meta, GST_META_FLAG_POOLED)) {
1209 GST_META_FLAG_UNSET (*meta, GST_META_FLAG_LOCKED);
1216 default_reset_buffer (GstBufferPool * pool, GstBuffer * buffer)
1218 GST_BUFFER_FLAGS (buffer) &= GST_BUFFER_FLAG_TAG_MEMORY;
1220 GST_BUFFER_PTS (buffer) = GST_CLOCK_TIME_NONE;
1221 GST_BUFFER_DTS (buffer) = GST_CLOCK_TIME_NONE;
1222 GST_BUFFER_DURATION (buffer) = GST_CLOCK_TIME_NONE;
1223 GST_BUFFER_OFFSET (buffer) = GST_BUFFER_OFFSET_NONE;
1224 GST_BUFFER_OFFSET_END (buffer) = GST_BUFFER_OFFSET_NONE;
1226 /* remove all metadata without the POOLED flag */
1227 gst_buffer_foreach_meta (buffer, remove_meta_unpooled, pool);
1231 * gst_buffer_pool_acquire_buffer:
1232 * @pool: a #GstBufferPool
1233 * @buffer: (out): a location for a #GstBuffer
1234 * @params: (transfer none) (allow-none): parameters.
1236 * Acquire a buffer from @pool. @buffer should point to a memory location that
1237 * can hold a pointer to the new buffer.
1239 * @params can be %NULL or contain optional parameters to influence the
1242 * Returns: a #GstFlowReturn such as %GST_FLOW_FLUSHING when the pool is
1246 gst_buffer_pool_acquire_buffer (GstBufferPool * pool, GstBuffer ** buffer,
1247 GstBufferPoolAcquireParams * params)
1249 GstBufferPoolClass *pclass;
1250 GstFlowReturn result;
1252 g_return_val_if_fail (GST_IS_BUFFER_POOL (pool), GST_FLOW_ERROR);
1253 g_return_val_if_fail (buffer != NULL, GST_FLOW_ERROR);
1255 pclass = GST_BUFFER_POOL_GET_CLASS (pool);
1257 /* assume we'll have one more outstanding buffer we need to do that so
1258 * that concurrent set_active doesn't clear the buffers */
1259 g_atomic_int_inc (&pool->priv->outstanding);
1261 if (G_LIKELY (pclass->acquire_buffer))
1262 result = pclass->acquire_buffer (pool, buffer, params);
1264 result = GST_FLOW_NOT_SUPPORTED;
1266 if (G_LIKELY (result == GST_FLOW_OK)) {
1267 /* all buffers from the pool point to the pool and have the refcount of the
1268 * pool incremented */
1269 (*buffer)->pool = gst_object_ref (pool);
1271 dec_outstanding (pool);
1278 default_release_buffer (GstBufferPool * pool, GstBuffer * buffer)
1280 GST_LOG_OBJECT (pool, "released buffer %p %d", buffer,
1281 GST_MINI_OBJECT_FLAGS (buffer));
1283 /* memory should be untouched */
1284 if (G_UNLIKELY (GST_BUFFER_FLAG_IS_SET (buffer, GST_BUFFER_FLAG_TAG_MEMORY)))
1287 /* size should have been reset. This is not a catch all, pool with
1288 * size requirement per memory should do their own check. */
1289 if (G_UNLIKELY (gst_buffer_get_size (buffer) != pool->priv->size))
1292 /* all memory should be exclusive to this buffer (and thus be writable) */
1293 if (G_UNLIKELY (!gst_buffer_is_all_memory_writable (buffer)))
1296 /* keep it around in our queue */
1297 gst_atomic_queue_push (pool->priv->queue, buffer);
1298 gst_poll_write_control (pool->priv->poll);
1304 GST_CAT_DEBUG_OBJECT (GST_CAT_PERFORMANCE, pool,
1305 "discarding buffer %p: memory tag set", buffer);
1310 GST_CAT_DEBUG_OBJECT (GST_CAT_PERFORMANCE, pool,
1311 "discarding buffer %p: size %" G_GSIZE_FORMAT " != %u",
1312 buffer, gst_buffer_get_size (buffer), pool->priv->size);
1317 GST_CAT_DEBUG_OBJECT (GST_CAT_PERFORMANCE, pool,
1318 "discarding buffer %p: memory not writable", buffer);
1323 do_free_buffer (pool, buffer);
1329 * gst_buffer_pool_release_buffer:
1330 * @pool: a #GstBufferPool
1331 * @buffer: (transfer full): a #GstBuffer
1333 * Release @buffer to @pool. @buffer should have previously been allocated from
1334 * @pool with gst_buffer_pool_acquire_buffer().
1336 * This function is usually called automatically when the last ref on @buffer
1340 gst_buffer_pool_release_buffer (GstBufferPool * pool, GstBuffer * buffer)
1342 GstBufferPoolClass *pclass;
1344 g_return_if_fail (GST_IS_BUFFER_POOL (pool));
1345 g_return_if_fail (buffer != NULL);
1347 /* check that the buffer is ours, all buffers returned to the pool have the
1348 * pool member set to NULL and the pool refcount decreased */
1349 if (!g_atomic_pointer_compare_and_exchange (&buffer->pool, pool, NULL))
1352 pclass = GST_BUFFER_POOL_GET_CLASS (pool);
1354 /* reset the buffer when needed */
1355 if (G_LIKELY (pclass->reset_buffer))
1356 pclass->reset_buffer (pool, buffer);
1358 if (G_LIKELY (pclass->release_buffer))
1359 pclass->release_buffer (pool, buffer);
1361 dec_outstanding (pool);
1363 /* decrease the refcount that the buffer had to us */
1364 gst_object_unref (pool);
1368 * gst_buffer_pool_set_flushing:
1369 * @pool: a #GstBufferPool
1370 * @flushing: whether to start or stop flushing
1372 * Enable or disable the flushing state of a @pool without freeing or
1373 * allocating buffers.
1378 gst_buffer_pool_set_flushing (GstBufferPool * pool, gboolean flushing)
1380 GstBufferPoolPrivate *priv;
1382 g_return_if_fail (GST_IS_BUFFER_POOL (pool));
1384 GST_LOG_OBJECT (pool, "flushing %d", flushing);
1388 GST_BUFFER_POOL_LOCK (pool);
1390 if (!priv->active) {
1391 GST_WARNING_OBJECT (pool, "can't change flushing state of inactive pool");
1395 do_set_flushing (pool, flushing);
1398 GST_BUFFER_POOL_UNLOCK (pool);