2 * Copyright (C) 2011 Wim Taymans <wim.taymans@gmail.be>
4 * gstmemory.c: memory block handling
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., 59 Temple Place - Suite 330,
19 * Boston, MA 02111-1307, USA.
24 * @short_description: refcounted wrapper for memory blocks
25 * @see_also: #GstBuffer
27 * GstMemory is a lightweight refcounted object that wraps a region of memory.
28 * They are typically used to manage the data of a #GstBuffer.
30 * A GstMemory object has an allocated region of memory of maxsize. The maximum
31 * size does not change during the lifetime of the memory object. The memory
32 * also has an offset and size property that specifies the valid range of memory
33 * in the allocated region.
35 * Memory is usually created by allocators with a gst_allocator_alloc()
36 * method call. When NULL is used as the allocator, the default allocator will
39 * New allocators can be registered with gst_allocator_register().
40 * Allocators are identified by name and can be retrieved with
41 * gst_allocator_find(). gst_allocator_set_default() can be used to change the
44 * New memory can be created with gst_memory_new_wrapped() that wraps the memory
45 * allocated elsewhere.
47 * Refcounting of the memory block is performed with gst_memory_ref() and
50 * The size of the memory can be retrieved and changed with
51 * gst_memory_get_sizes() and gst_memory_resize() respectively.
53 * Getting access to the data of the memory is performed with gst_memory_map().
54 * The call will return a pointer to offset bytes into the region of memory.
55 * After the memory access is completed, gst_memory_unmap() should be called.
57 * Memory can be copied with gst_memory_copy(), which will return a writable
58 * copy. gst_memory_share() will create a new memory block that shares the
59 * memory with an existing memory block at a custom offset and with a custom
62 * Memory can be efficiently merged when gst_memory_is_span() returns TRUE.
64 * Last reviewed on 2012-03-28 (0.11.3)
71 #include "gst_private.h"
72 #include "gstmemory.h"
74 #ifndef GST_DISABLE_TRACE
76 static GstAllocTrace *_gst_memory_trace;
77 static GstAllocTrace *_gst_allocator_trace;
80 G_DEFINE_BOXED_TYPE (GstMemory, gst_memory, (GBoxedCopyFunc) gst_memory_ref,
81 (GBoxedFreeFunc) gst_memory_unref);
83 GST_DEFINE_MINI_OBJECT_TYPE (GstAllocator, gst_allocator);
85 G_DEFINE_BOXED_TYPE (GstAllocationParams, gst_allocation_params,
86 (GBoxedCopyFunc) gst_allocation_params_copy,
87 (GBoxedFreeFunc) gst_allocation_params_free);
89 #if defined(MEMORY_ALIGNMENT_MALLOC)
90 size_t gst_memory_alignment = 7;
91 #elif defined(MEMORY_ALIGNMENT_PAGESIZE)
92 /* we fill this in in the _init method */
93 size_t gst_memory_alignment = 0;
94 #elif defined(MEMORY_ALIGNMENT)
95 size_t gst_memory_alignment = MEMORY_ALIGNMENT - 1;
97 #error "No memory alignment configured"
98 size_t gst_memory_alignment = 0;
103 GstMiniObject mini_object;
108 GDestroyNotify notify;
111 /* default memory implementation */
118 GDestroyNotify notify;
121 /* the default allocator */
122 static GstAllocator *_default_allocator;
124 /* our predefined allocators */
125 static GstAllocator *_default_mem_impl;
127 /* initialize the fields */
129 _default_mem_init (GstMemoryDefault * mem, GstMemoryFlags flags,
130 GstMemory * parent, gsize slice_size, gpointer data,
131 gsize maxsize, gsize offset, gsize size, gsize align,
132 gpointer user_data, GDestroyNotify notify)
134 mem->mem.allocator = _default_mem_impl;
135 mem->mem.flags = flags;
136 mem->mem.refcount = 1;
137 mem->mem.parent = parent ? gst_memory_ref (parent) : NULL;
138 mem->mem.state = (flags & GST_MEMORY_FLAG_READONLY ? 0x1 : 0);
139 mem->mem.maxsize = maxsize;
140 mem->mem.align = align;
141 mem->mem.offset = offset;
142 mem->mem.size = size;
143 mem->slice_size = slice_size;
145 mem->user_data = user_data;
146 mem->notify = notify;
148 GST_CAT_DEBUG (GST_CAT_MEMORY, "new memory %p, maxsize:%" G_GSIZE_FORMAT
149 " offset:%" G_GSIZE_FORMAT " size:%" G_GSIZE_FORMAT, mem, maxsize,
153 /* create a new memory block that manages the given memory */
154 static GstMemoryDefault *
155 _default_mem_new (GstMemoryFlags flags, GstMemory * parent, gpointer data,
156 gsize maxsize, gsize offset, gsize size, gsize align, gpointer user_data,
157 GDestroyNotify notify)
159 GstMemoryDefault *mem;
162 slice_size = sizeof (GstMemoryDefault);
164 mem = g_slice_alloc (slice_size);
165 _default_mem_init (mem, flags, parent, slice_size,
166 data, maxsize, offset, size, align, user_data, notify);
171 /* allocate the memory and structure in one block */
172 static GstMemoryDefault *
173 _default_mem_new_block (GstMemoryFlags flags, gsize maxsize, gsize align,
174 gsize offset, gsize size)
176 GstMemoryDefault *mem;
177 gsize aoffset, slice_size, padding;
180 /* ensure configured alignment */
181 align |= gst_memory_alignment;
182 /* allocate more to compensate for alignment */
184 /* alloc header and data in one block */
185 slice_size = sizeof (GstMemoryDefault) + maxsize;
187 mem = g_slice_alloc (slice_size);
191 data = (guint8 *) mem + sizeof (GstMemoryDefault);
194 if ((aoffset = ((guintptr) data & align))) {
195 aoffset = (align + 1) - aoffset;
200 if (offset && (flags & GST_MEMORY_FLAG_ZERO_PREFIXED))
201 memset (data, 0, offset);
203 padding = maxsize - (offset + size);
204 if (padding && (flags & GST_MEMORY_FLAG_ZERO_PADDED))
205 memset (data + offset + size, 0, padding);
207 _default_mem_init (mem, flags, NULL, slice_size, data, maxsize,
208 offset, size, align, NULL, NULL);
214 _default_alloc_alloc (GstAllocator * allocator, gsize size,
215 GstAllocationParams * params, gpointer user_data)
217 gsize maxsize = size + params->prefix + params->padding;
219 return (GstMemory *) _default_mem_new_block (params->flags,
220 maxsize, params->align, params->prefix, size);
224 _default_mem_map (GstMemoryDefault * mem, gsize maxsize, GstMapFlags flags)
230 _default_mem_unmap (GstMemoryDefault * mem)
236 _default_mem_free (GstMemoryDefault * mem)
238 GST_CAT_DEBUG (GST_CAT_MEMORY, "free memory %p", mem);
241 gst_memory_unref (mem->mem.parent);
244 mem->notify (mem->user_data);
246 g_slice_free1 (mem->slice_size, mem);
249 static GstMemoryDefault *
250 _default_mem_copy (GstMemoryDefault * mem, gssize offset, gsize size)
252 GstMemoryDefault *copy;
255 size = mem->mem.size > offset ? mem->mem.size - offset : 0;
258 _default_mem_new_block (0, mem->mem.maxsize, 0, mem->mem.offset + offset,
260 GST_CAT_DEBUG (GST_CAT_PERFORMANCE,
261 "memcpy %" G_GSIZE_FORMAT " memory %p -> %p", mem->mem.maxsize, mem,
263 memcpy (copy->data, mem->data, mem->mem.maxsize);
268 static GstMemoryDefault *
269 _default_mem_share (GstMemoryDefault * mem, gssize offset, gsize size)
271 GstMemoryDefault *sub;
274 /* find the real parent */
275 if ((parent = mem->mem.parent) == NULL)
276 parent = (GstMemory *) mem;
279 size = mem->mem.size - offset;
282 _default_mem_new (parent->flags, parent, mem->data,
283 mem->mem.maxsize, mem->mem.offset + offset, size, mem->mem.align, NULL,
290 _default_mem_is_span (GstMemoryDefault * mem1, GstMemoryDefault * mem2,
295 GstMemoryDefault *parent;
297 parent = (GstMemoryDefault *) mem1->mem.parent;
299 *offset = mem1->mem.offset - parent->mem.offset;
302 /* and memory is contiguous */
303 return mem1->data + mem1->mem.offset + mem1->mem.size ==
304 mem2->data + mem2->mem.offset;
308 _fallback_mem_copy (GstMemory * mem, gssize offset, gssize size)
311 GstMapInfo sinfo, dinfo;
312 GstAllocationParams params = { 0, 0, 0, mem->align, };
314 if (!gst_memory_map (mem, &sinfo, GST_MAP_READ))
318 size = sinfo.size > offset ? sinfo.size - offset : 0;
320 /* use the same allocator as the memory we copy */
321 copy = gst_allocator_alloc (mem->allocator, size, ¶ms);
322 if (!gst_memory_map (copy, &dinfo, GST_MAP_WRITE)) {
323 GST_CAT_WARNING (GST_CAT_MEMORY, "could not write map memory %p", copy);
324 gst_memory_unmap (mem, &sinfo);
328 GST_CAT_DEBUG (GST_CAT_PERFORMANCE,
329 "memcpy %" G_GSSIZE_FORMAT " memory %p -> %p", size, mem, copy);
330 memcpy (dinfo.data, sinfo.data + offset, size);
331 gst_memory_unmap (copy, &dinfo);
332 gst_memory_unmap (mem, &sinfo);
338 _fallback_mem_is_span (GstMemory * mem1, GstMemory * mem2, gsize * offset)
344 static GHashTable *allocators;
347 _priv_sysmem_notify (gpointer user_data)
349 g_warning ("The default memory allocator was freed!");
353 _priv_gst_memory_initialize (void)
355 static const GstMemoryInfo _mem_info = {
356 GST_ALLOCATOR_SYSMEM,
357 (GstAllocatorAllocFunction) _default_alloc_alloc,
358 (GstMemoryMapFunction) _default_mem_map,
359 (GstMemoryUnmapFunction) _default_mem_unmap,
360 (GstMemoryFreeFunction) _default_mem_free,
361 (GstMemoryCopyFunction) _default_mem_copy,
362 (GstMemoryShareFunction) _default_mem_share,
363 (GstMemoryIsSpanFunction) _default_mem_is_span,
366 #ifndef GST_DISABLE_TRACE
367 _gst_memory_trace = _gst_alloc_trace_register ("GstMemory", -1);
368 _gst_allocator_trace = _gst_alloc_trace_register ("GstAllocator", -1);
371 g_rw_lock_init (&lock);
372 allocators = g_hash_table_new (g_str_hash, g_str_equal);
374 #ifdef HAVE_GETPAGESIZE
375 #ifdef MEMORY_ALIGNMENT_PAGESIZE
376 gst_memory_alignment = getpagesize () - 1;
380 GST_CAT_DEBUG (GST_CAT_MEMORY, "memory alignment: %" G_GSIZE_FORMAT,
381 gst_memory_alignment);
383 _default_mem_impl = gst_allocator_new (&_mem_info, NULL, _priv_sysmem_notify);
385 _default_allocator = gst_allocator_ref (_default_mem_impl);
386 gst_allocator_register (GST_ALLOCATOR_SYSMEM,
387 gst_allocator_ref (_default_mem_impl));
391 * gst_memory_new_wrapped:
392 * @flags: #GstMemoryFlags
393 * @data: data to wrap
394 * @maxsize: allocated size of @data
395 * @offset: offset in @data
396 * @size: size of valid data
397 * @user_data: user_data
398 * @notify: called with @user_data when the memory is freed
400 * Allocate a new memory block that wraps the given @data.
402 * The prefix/padding must be filled with 0 if @flags contains
403 * #GST_MEMORY_FLAG_ZERO_PREFIXED and #GST_MEMORY_FLAG_ZERO_PADDED respectively.
405 * Returns: a new #GstMemory.
408 gst_memory_new_wrapped (GstMemoryFlags flags, gpointer data,
409 gsize maxsize, gsize offset, gsize size, gpointer user_data,
410 GDestroyNotify notify)
412 GstMemoryDefault *mem;
414 g_return_val_if_fail (data != NULL, NULL);
415 g_return_val_if_fail (offset + size <= maxsize, NULL);
418 _default_mem_new (flags, NULL, data, maxsize, offset, size, 0, user_data,
421 #ifndef GST_DISABLE_TRACE
422 _gst_alloc_trace_new (_gst_memory_trace, mem);
425 return (GstMemory *) mem;
432 * Increases the refcount of @mem.
434 * Returns: @mem with increased refcount
437 gst_memory_ref (GstMemory * mem)
439 g_return_val_if_fail (mem != NULL, NULL);
441 GST_CAT_TRACE (GST_CAT_MEMORY, "memory %p, %d->%d", mem, mem->refcount,
444 g_atomic_int_inc (&mem->refcount);
453 * Decreases the refcount of @mem. When the refcount reaches 0, the free
454 * function of @mem will be called.
457 gst_memory_unref (GstMemory * mem)
459 g_return_if_fail (mem != NULL);
460 g_return_if_fail (mem->allocator != NULL);
462 GST_CAT_TRACE (GST_CAT_MEMORY, "memory %p, %d->%d", mem, mem->refcount,
465 if (g_atomic_int_dec_and_test (&mem->refcount)) {
466 /* there should be no outstanding mappings */
467 g_return_if_fail (g_atomic_int_get (&mem->state) < 4);
468 #ifndef GST_DISABLE_TRACE
469 _gst_alloc_trace_free (_gst_memory_trace, mem);
471 mem->allocator->info.mem_free (mem);
476 * gst_memory_is_exclusive:
479 * Check if the current ref to @mem is exclusive, this means that no other
480 * references exist other than @mem.
483 gst_memory_is_exclusive (GstMemory * mem)
485 g_return_val_if_fail (mem != NULL, FALSE);
487 return (g_atomic_int_get (&mem->refcount) == 1);
491 * gst_memory_get_sizes:
493 * @offset: pointer to offset
494 * @maxsize: pointer to maxsize
496 * Get the current @size, @offset and @maxsize of @mem.
498 * Returns: the current sizes of @mem
501 gst_memory_get_sizes (GstMemory * mem, gsize * offset, gsize * maxsize)
503 g_return_val_if_fail (mem != NULL, 0);
506 *offset = mem->offset;
508 *maxsize = mem->maxsize;
516 * @offset: a new offset
519 * Resize the memory region. @mem should be writable and offset + size should be
520 * less than the maxsize of @mem.
522 * #GST_MEMORY_FLAG_ZERO_PREFIXED and #GST_MEMORY_FLAG_ZERO_PADDED will be
523 * cleared when offset or padding is increased respectively.
526 gst_memory_resize (GstMemory * mem, gssize offset, gsize size)
528 g_return_if_fail (mem != NULL);
529 g_return_if_fail (offset >= 0 || mem->offset >= -offset);
530 g_return_if_fail (size + mem->offset + offset <= mem->maxsize);
532 /* if we increase the prefix, we can't guarantee it is still 0 filled */
533 if ((offset > 0) && GST_MEMORY_IS_ZERO_PREFIXED (mem))
534 GST_MEMORY_FLAG_UNSET (mem, GST_MEMORY_FLAG_ZERO_PREFIXED);
536 /* if we increase the padding, we can't guarantee it is still 0 filled */
537 if ((offset + size < mem->size) && GST_MEMORY_IS_ZERO_PADDED (mem))
538 GST_MEMORY_FLAG_UNSET (mem, GST_MEMORY_FLAG_ZERO_PADDED);
540 mem->offset += offset;
545 gst_memory_lock (GstMemory * mem, GstMapFlags flags)
547 gint access_mode, state, newstate;
549 access_mode = flags & 3;
552 state = g_atomic_int_get (&mem->state);
554 /* nothing mapped, set access_mode and refcount */
555 newstate = 4 | access_mode;
557 /* access_mode must match */
558 if ((state & access_mode) != access_mode)
560 /* increase refcount */
561 newstate = state + 4;
563 } while (!g_atomic_int_compare_and_exchange (&mem->state, state, newstate));
569 GST_CAT_DEBUG (GST_CAT_MEMORY, "lock failed %p: state %d, access_mode %d",
570 mem, state, access_mode);
576 gst_memory_unlock (GstMemory * mem)
578 gint state, newstate;
581 state = g_atomic_int_get (&mem->state);
582 /* decrease the refcount */
583 newstate = state - 4;
584 /* last refcount, unset access_mode */
587 } while (!g_atomic_int_compare_and_exchange (&mem->state, state, newstate));
592 * gst_memory_make_mapped:
593 * @mem: (transfer full): a #GstMemory
594 * @info: (out): pointer for info
595 * @flags: mapping flags
597 * Create a #GstMemory object that is mapped with @flags. If @mem is mappable
598 * with @flags, this function returns the mapped @mem directly. Otherwise a
599 * mapped copy of @mem is returned.
601 * This function takes ownership of old @mem and returns a reference to a new
604 * Returns: (transfer full): a #GstMemory object mapped with @flags or NULL when
605 * a mapping is not possible.
608 gst_memory_make_mapped (GstMemory * mem, GstMapInfo * info, GstMapFlags flags)
612 if (gst_memory_map (mem, info, flags)) {
615 result = gst_memory_copy (mem, 0, -1);
616 gst_memory_unref (mem);
621 if (!gst_memory_map (result, info, flags))
629 GST_CAT_DEBUG (GST_CAT_MEMORY, "cannot copy memory %p", mem);
634 GST_CAT_DEBUG (GST_CAT_MEMORY, "cannot map memory %p with flags %d", mem,
636 gst_memory_unref (result);
644 * @info: (out): pointer for info
645 * @flags: mapping flags
647 * Fill @info with the pointer and sizes of the memory in @mem that can be
648 * accessed according to @flags.
650 * This function can return %FALSE for various reasons:
651 * - the memory backed by @mem is not accessible with the given @flags.
652 * - the memory was already mapped with a different mapping.
654 * @info and its contents remain valid for as long as @mem is valid and
655 * until gst_memory_unmap() is called.
657 * For each gst_memory_map() call, a corresponding gst_memory_unmap() call
660 * Returns: %TRUE if the map operation was successful.
663 gst_memory_map (GstMemory * mem, GstMapInfo * info, GstMapFlags flags)
665 g_return_val_if_fail (mem != NULL, FALSE);
666 g_return_val_if_fail (info != NULL, FALSE);
668 if (!gst_memory_lock (mem, flags))
671 info->data = mem->allocator->info.mem_map (mem, mem->maxsize, flags);
673 if (G_UNLIKELY (info->data == NULL))
678 info->size = mem->size;
679 info->maxsize = mem->maxsize - mem->offset;
680 info->data = info->data + mem->offset;
687 GST_CAT_DEBUG (GST_CAT_MEMORY, "mem %p: lock %d failed", mem, flags);
692 /* something went wrong, restore the orginal state again */
693 GST_CAT_ERROR (GST_CAT_MEMORY, "mem %p: map failed", mem);
694 gst_memory_unlock (mem);
702 * @info: a #GstMapInfo
704 * Release the memory obtained with gst_memory_map()
707 gst_memory_unmap (GstMemory * mem, GstMapInfo * info)
709 g_return_if_fail (mem != NULL);
710 g_return_if_fail (info != NULL);
711 g_return_if_fail (info->memory == mem);
712 /* there must be a ref */
713 g_return_if_fail (g_atomic_int_get (&mem->state) >= 4);
715 mem->allocator->info.mem_unmap (mem);
716 gst_memory_unlock (mem);
722 * @offset: an offset to copy
723 * @size: size to copy or -1 to copy all bytes from offset
725 * Return a copy of @size bytes from @mem starting from @offset. This copy is
726 * guaranteed to be writable. @size can be set to -1 to return a copy all bytes
729 * Returns: a new #GstMemory.
732 gst_memory_copy (GstMemory * mem, gssize offset, gssize size)
736 g_return_val_if_fail (mem != NULL, NULL);
738 copy = mem->allocator->info.mem_copy (mem, offset, size);
740 #ifndef GST_DISABLE_TRACE
741 _gst_alloc_trace_new (_gst_memory_trace, copy);
750 * @offset: an offset to share
751 * @size: size to share or -1 to share bytes from offset
753 * Return a shared copy of @size bytes from @mem starting from @offset. No
754 * memory copy is performed and the memory region is simply shared. The result
755 * is guaranteed to be not-writable. @size can be set to -1 to return a share
756 * all bytes from @offset.
758 * Returns: a new #GstMemory.
761 gst_memory_share (GstMemory * mem, gssize offset, gssize size)
765 g_return_val_if_fail (mem != NULL, NULL);
766 g_return_val_if_fail (!GST_MEMORY_FLAG_IS_SET (mem, GST_MEMORY_FLAG_NO_SHARE),
769 shared = mem->allocator->info.mem_share (mem, offset, size);
771 #ifndef GST_DISABLE_TRACE
772 _gst_alloc_trace_new (_gst_memory_trace, shared);
779 * gst_memory_is_span:
780 * @mem1: a #GstMemory
781 * @mem2: a #GstMemory
782 * @offset: a pointer to a result offset
784 * Check if @mem1 and mem2 share the memory with a common parent memory object
785 * and that the memory is contiguous.
787 * If this is the case, the memory of @mem1 and @mem2 can be merged
788 * efficiently by performing gst_memory_share() on the parent object from
789 * the returned @offset.
791 * Returns: %TRUE if the memory is contiguous and of a common parent.
794 gst_memory_is_span (GstMemory * mem1, GstMemory * mem2, gsize * offset)
796 g_return_val_if_fail (mem1 != NULL, FALSE);
797 g_return_val_if_fail (mem2 != NULL, FALSE);
799 /* need to have the same allocators */
800 if (mem1->allocator != mem2->allocator)
803 /* need to have the same parent */
804 if (mem1->parent == NULL || mem1->parent != mem2->parent)
807 /* and memory is contiguous */
808 if (!mem1->allocator->info.mem_is_span (mem1, mem2, offset))
815 _gst_allocator_free (GstAllocator * allocator)
817 if (allocator->notify)
818 allocator->notify (allocator->user_data);
820 g_slice_free1 (GST_MINI_OBJECT_SIZE (allocator), allocator);
823 static void gst_allocator_init (GstAllocator * allocator,
824 const GstMemoryInfo * info, gsize size);
826 static GstAllocator *
827 _gst_allocator_copy (GstAllocator * allocator)
831 copy = g_slice_new (GstAllocator);
833 gst_allocator_init (copy, &allocator->info, sizeof (GstAllocator));
839 gst_allocator_init (GstAllocator * allocator, const GstMemoryInfo * info,
842 gst_mini_object_init (GST_MINI_OBJECT_CAST (allocator),
843 gst_allocator_get_type (), size);
845 allocator->mini_object.copy = (GstMiniObjectCopyFunction) _gst_allocator_copy;
846 allocator->mini_object.free = (GstMiniObjectFreeFunction) _gst_allocator_free;
848 allocator->info = *info;
849 #define INSTALL_FALLBACK(_t) \
850 if (allocator->info._t == NULL) allocator->info._t = _fallback_ ##_t;
851 INSTALL_FALLBACK (mem_copy);
852 INSTALL_FALLBACK (mem_is_span);
853 #undef INSTALL_FALLBACK
858 * @info: a #GstMemoryInfo
859 * @user_data: user data
860 * @notify: a #GDestroyNotify for @user_data
862 * Create a new memory allocator with @info and @user_data.
864 * All functions in @info are mandatory exept the copy and is_span
865 * functions, which will have a default implementation when left NULL.
867 * The @user_data will be passed to all calls of the alloc function. @notify
868 * will be called with @user_data when the allocator is freed.
870 * Returns: a new #GstAllocator.
873 gst_allocator_new (const GstMemoryInfo * info, gpointer user_data,
874 GDestroyNotify notify)
876 GstAllocator *allocator;
878 g_return_val_if_fail (info != NULL, NULL);
879 g_return_val_if_fail (info->alloc != NULL, NULL);
880 g_return_val_if_fail (info->mem_map != NULL, NULL);
881 g_return_val_if_fail (info->mem_unmap != NULL, NULL);
882 g_return_val_if_fail (info->mem_free != NULL, NULL);
883 g_return_val_if_fail (info->mem_share != NULL, NULL);
885 allocator = g_slice_new (GstAllocator);
887 gst_allocator_init (allocator, info, sizeof (GstAllocator));
889 allocator->user_data = user_data;
890 allocator->notify = notify;
892 GST_CAT_DEBUG (GST_CAT_MEMORY, "new allocator %p", allocator);
898 * gst_allocator_get_memory_type:
899 * @allocator: a #GstAllocator
901 * Get the memory type allocated by this allocator
903 * Returns: the memory type provided by @allocator
906 gst_allocator_get_memory_type (GstAllocator * allocator)
908 g_return_val_if_fail (allocator != NULL, NULL);
910 return allocator->info.mem_type;
914 * gst_allocator_register:
915 * @name: the name of the allocator
916 * @allocator: (transfer full): #GstAllocator
918 * Registers the memory @allocator with @name. This function takes ownership of
922 gst_allocator_register (const gchar * name, GstAllocator * allocator)
924 g_return_if_fail (name != NULL);
925 g_return_if_fail (allocator != NULL);
927 GST_CAT_DEBUG (GST_CAT_MEMORY, "registering allocator %p with name \"%s\"",
930 g_rw_lock_writer_lock (&lock);
931 g_hash_table_insert (allocators, (gpointer) name, (gpointer) allocator);
932 g_rw_lock_writer_unlock (&lock);
936 * gst_allocator_find:
937 * @name: the name of the allocator
939 * Find a previously registered allocator with @name. When @name is NULL, the
940 * default allocator will be returned.
942 * Returns: (transfer full): a #GstAllocator or NULL when the allocator with @name was not
943 * registered. Use gst_allocator_unref() to release the allocator after usage.
946 gst_allocator_find (const gchar * name)
948 GstAllocator *allocator;
950 g_rw_lock_reader_lock (&lock);
952 allocator = g_hash_table_lookup (allocators, (gconstpointer) name);
954 allocator = _default_allocator;
957 gst_allocator_ref (allocator);
958 g_rw_lock_reader_unlock (&lock);
964 * gst_allocator_set_default:
965 * @allocator: (transfer full): a #GstAllocator
967 * Set the default allocator. This function takes ownership of @allocator.
970 gst_allocator_set_default (GstAllocator * allocator)
973 g_return_if_fail (allocator != NULL);
975 g_rw_lock_writer_lock (&lock);
976 old = _default_allocator;
977 _default_allocator = allocator;
978 g_rw_lock_writer_unlock (&lock);
981 gst_allocator_unref (old);
985 * gst_allocation_params_init:
986 * @params: a #GstAllocationParams
988 * Initialize @params to its default values
991 gst_allocation_params_init (GstAllocationParams * params)
993 g_return_if_fail (params != NULL);
995 memset (params, 0, sizeof (GstAllocationParams));
999 * gst_allocation_params_copy:
1000 * @params: (transfer none): a #GstAllocationParams
1002 * Create a copy of @params.
1004 * Free-function: gst_allocation_params_free
1006 * Returns: (transfer full): a new ##GstAllocationParams, free with
1007 * gst_allocation_params_free().
1009 GstAllocationParams *
1010 gst_allocation_params_copy (const GstAllocationParams * params)
1012 GstAllocationParams *result = NULL;
1016 (GstAllocationParams *) g_slice_copy (sizeof (GstAllocationParams),
1023 * gst_allocation_params_free:
1024 * @params: (in) (transfer full): a #GstAllocationParams
1029 gst_allocation_params_free (GstAllocationParams * params)
1031 g_slice_free (GstAllocationParams, params);
1035 * gst_allocator_alloc:
1036 * @allocator: (transfer none) (allow-none): a #GstAllocator to use
1037 * @size: size of the visible memory area
1038 * @params: (transfer none) (allow-none): optional parameters
1040 * Use @allocator to allocate a new memory block with memory that is at least
1043 * The optional @params can specify the prefix and padding for the memory. If
1044 * NULL is passed, no flags, no extra prefix/padding and a default alignment is
1047 * The prefix/padding will be filled with 0 if flags contains
1048 * #GST_MEMORY_FLAG_ZERO_PREFIXED and #GST_MEMORY_FLAG_ZERO_PADDED respectively.
1050 * When @allocator is NULL, the default allocator will be used.
1052 * The alignment in @params is given as a bitmask so that @align + 1 equals
1053 * the amount of bytes to align to. For example, to align to 8 bytes,
1054 * use an alignment of 7.
1056 * Returns: (transfer full): a new #GstMemory.
1059 gst_allocator_alloc (GstAllocator * allocator, gsize size,
1060 GstAllocationParams * params)
1063 static GstAllocationParams defparams = { 0, 0, 0, 0, };
1066 g_return_val_if_fail (((params->align + 1) & params->align) == 0, NULL);
1068 params = &defparams;
1071 if (allocator == NULL)
1072 allocator = _default_allocator;
1074 mem = allocator->info.alloc (allocator, size, params, allocator->user_data);
1076 #ifndef GST_DISABLE_TRACE
1077 _gst_alloc_trace_new (_gst_memory_trace, mem);