Merge branch 'master' into 0.11
[platform/upstream/gstreamer.git] / gst / gstmemory.c
1 /* GStreamer
2  * Copyright (C) 2011 Wim Taymans <wim.taymans@gmail.be>
3  *
4  * gstmemory.c: memory block handling
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:gstmemory
24  * @short_description: refcounted wrapper for memory blocks
25  * @see_also: #GstBuffer
26  *
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.
29  *
30  * Memory is usually created by allocators with a gst_allocator_alloc()
31  * method call. When NULL is used as the allocator, the default allocator will
32  * be used.
33  *
34  * New allocators can be registered with gst_allocator_register().
35  * Allocators are identified by name and can be retrieved with
36  * gst_allocator_find().
37  *
38  * New memory can be created with gst_memory_new_wrapped() that wraps the memory
39  * allocated elsewhere.
40  *
41  * Refcounting of the memory block is performed with gst_memory_ref() and
42  * gst_memory_unref().
43  *
44  * The size of the memory can be retrieved and changed with
45  * gst_memory_get_sizes() and gst_memory_resize() respectively.
46  *
47  * Getting access to the data of the memory is performed with gst_memory_map().
48  * After the memory access is completed, gst_memory_unmap() should be called.
49  *
50  * Memory can be copied with gst_memory_copy(), which will returnn a writable
51  * copy. gst_memory_share() will create a new memory block that shares the
52  * memory with an existing memory block at a custom offset and with a custom
53  * size.
54  *
55  * Memory can be efficiently merged when gst_memory_is_span() returns TRUE and
56  * with the function gst_memory_span().
57  *
58  * Last reviewed on 2011-06-08 (0.11.0)
59  */
60
61 #include "config.h"
62 #include "gst_private.h"
63 #include "gstmemory.h"
64
65
66 /* buffer alignment in bytes - 1
67  * an alignment of 7 would be the same as malloc() guarantees
68  */
69 #ifdef HAVE_POSIX_MEMALIGN
70 #if defined(MEMORY_ALIGNMENT_MALLOC)
71 size_t gst_memory_alignment = 7;
72 #elif defined(MEMORY_ALIGNMENT_PAGESIZE)
73 size_t gst_memory_alignment = 0;
74 #elif defined(MEMORY_ALIGNMENT)
75 size_t gst_memory_alignment = MEMORY_ALIGNMENT - 1;
76 #else
77 #error "No memory alignment configured"
78 size_t gst_memory_alignment = 0;
79 #endif
80 #endif /* HAVE_POSIX_MEMALIGN */
81
82 struct _GstAllocator
83 {
84   GQuark name;
85
86   GstMemoryInfo info;
87 };
88
89 /* default memory implementation */
90 typedef struct
91 {
92   GstMemory mem;
93   gsize slice_size;
94   guint8 *data;
95   GFreeFunc free_func;
96   gsize maxsize;
97   gsize offset;
98   gsize size;
99 } GstMemoryDefault;
100
101 /* the default allocator */
102 static const GstAllocator *_default_allocator;
103
104 /* our predefined allocators */
105 static const GstAllocator *_default_mem_impl;
106
107 /* initialize the fields */
108 static void
109 _default_mem_init (GstMemoryDefault * mem, GstMemoryFlags flags,
110     GstMemory * parent, gsize slice_size, gpointer data,
111     GFreeFunc free_func, gsize maxsize, gsize offset, gsize size)
112 {
113   mem->mem.allocator = _default_mem_impl;
114   mem->mem.flags = flags;
115   mem->mem.refcount = 1;
116   mem->mem.parent = parent ? gst_memory_ref (parent) : NULL;
117   mem->slice_size = slice_size;
118   mem->data = data;
119   mem->free_func = free_func;
120   mem->maxsize = maxsize;
121   mem->offset = offset;
122   mem->size = size;
123 }
124
125 /* create a new memory block that manages the given memory */
126 static GstMemoryDefault *
127 _default_mem_new (GstMemoryFlags flags, GstMemory * parent, gpointer data,
128     GFreeFunc free_func, gsize maxsize, gsize offset, gsize size)
129 {
130   GstMemoryDefault *mem;
131   gsize slice_size;
132
133   slice_size = sizeof (GstMemoryDefault);
134
135   mem = g_slice_alloc (slice_size);
136   _default_mem_init (mem, flags, parent, slice_size,
137       data, free_func, maxsize, offset, size);
138
139   return mem;
140 }
141
142 /* allocate the memory and structure in one block */
143 static GstMemoryDefault *
144 _default_mem_new_block (gsize maxsize, gsize align, gsize offset, gsize size)
145 {
146   GstMemoryDefault *mem;
147   gsize aoffset, slice_size;
148   guint8 *data;
149
150   /* ensure configured alignment */
151   align |= gst_memory_alignment;
152   /* allocate more to compensate for alignment */
153   maxsize += align;
154   /* alloc header and data in one block */
155   slice_size = sizeof (GstMemoryDefault) + maxsize;
156
157   mem = g_slice_alloc (slice_size);
158   if (mem == NULL)
159     return NULL;
160
161   data = (guint8 *) mem + sizeof (GstMemoryDefault);
162
163   if ((aoffset = ((guintptr) data & align)))
164     aoffset = (align + 1) - aoffset;
165
166   _default_mem_init (mem, 0, NULL, slice_size, data, NULL, maxsize,
167       aoffset + offset, size);
168
169   return mem;
170 }
171
172 static GstMemory *
173 _default_mem_alloc (const GstAllocator * allocator, gsize maxsize, gsize align)
174 {
175   return (GstMemory *) _default_mem_new_block (maxsize, align, 0, maxsize);
176 }
177
178 static gsize
179 _default_mem_get_sizes (GstMemoryDefault * mem, gsize * offset, gsize * maxsize)
180 {
181   if (offset)
182     *offset = mem->offset;
183   if (maxsize)
184     *maxsize = mem->maxsize;
185
186   return mem->size;
187 }
188
189 static void
190 _default_mem_resize (GstMemoryDefault * mem, gssize offset, gsize size)
191 {
192   g_return_if_fail (size + mem->offset + offset <= mem->maxsize);
193
194   mem->offset += offset;
195   mem->size = size;
196 }
197
198 static gpointer
199 _default_mem_map (GstMemoryDefault * mem, gsize * size, gsize * maxsize,
200     GstMapFlags flags)
201 {
202   if (size)
203     *size = mem->size;
204   if (maxsize)
205     *maxsize = mem->maxsize;
206
207   return mem->data + mem->offset;
208 }
209
210 static gboolean
211 _default_mem_unmap (GstMemoryDefault * mem, gpointer data, gsize size)
212 {
213   if (size != -1)
214     mem->size = size;
215   return TRUE;
216 }
217
218 static void
219 _default_mem_free (GstMemoryDefault * mem)
220 {
221   if (mem->mem.parent)
222     gst_memory_unref (mem->mem.parent);
223
224   if (mem->free_func)
225     mem->free_func (mem->data);
226
227   g_slice_free1 (mem->slice_size, mem);
228 }
229
230 static GstMemoryDefault *
231 _default_mem_copy (GstMemoryDefault * mem, gssize offset, gsize size)
232 {
233   GstMemoryDefault *copy;
234
235   if (size == -1)
236     size = mem->size > offset ? mem->size - offset : 0;
237
238   copy = _default_mem_new_block (mem->maxsize, 0, mem->offset + offset, size);
239   memcpy (copy->data, mem->data, mem->maxsize);
240
241   return copy;
242 }
243
244 static GstMemoryDefault *
245 _default_mem_share (GstMemoryDefault * mem, gssize offset, gsize size)
246 {
247   GstMemoryDefault *sub;
248   GstMemory *parent;
249
250   /* find the real parent */
251   if ((parent = mem->mem.parent) == NULL)
252     parent = (GstMemory *) mem;
253
254   if (size == -1)
255     size = mem->size - offset;
256
257   sub = _default_mem_new (parent->flags, parent, mem->data, NULL, mem->maxsize,
258       mem->offset + offset, size);
259
260   return sub;
261 }
262
263 static gboolean
264 _default_mem_is_span (GstMemoryDefault * mem1, GstMemoryDefault * mem2,
265     gsize * offset)
266 {
267
268   if (offset) {
269     GstMemoryDefault *parent;
270
271     parent = (GstMemoryDefault *) mem1->mem.parent;
272
273     *offset = mem1->offset - parent->offset;
274   }
275
276   /* and memory is contiguous */
277   return mem1->data + mem1->offset + mem1->size == mem2->data + mem2->offset;
278 }
279
280 static GstMemory *
281 _fallback_copy (GstMemory * mem, gssize offset, gsize size)
282 {
283   GstMemory *copy;
284   guint8 *data, *dest;
285   gsize msize;
286
287   data = gst_memory_map (mem, &msize, NULL, GST_MAP_READ);
288   if (size == -1)
289     size = msize > offset ? msize - offset : 0;
290   /* use the same allocator as the memory we copy, FIXME, alignment?  */
291   copy = gst_allocator_alloc (mem->allocator, size, 0);
292   dest = gst_memory_map (copy, NULL, NULL, GST_MAP_WRITE);
293   memcpy (dest, data + offset, size);
294   gst_memory_unmap (copy, dest, size);
295
296   gst_memory_unmap (mem, data, msize);
297
298   return (GstMemory *) copy;
299 }
300
301 static gboolean
302 _fallback_is_span (GstMemory * mem1, GstMemory * mem2, gsize * offset)
303 {
304   return FALSE;
305 }
306
307 static GStaticRWLock lock = G_STATIC_RW_LOCK_INIT;
308 static GHashTable *allocators;
309
310 void
311 _priv_gst_memory_initialize (void)
312 {
313   static const GstMemoryInfo _mem_info = {
314     (GstMemoryAllocFunction) _default_mem_alloc,
315     (GstMemoryGetSizesFunction) _default_mem_get_sizes,
316     (GstMemoryResizeFunction) _default_mem_resize,
317     (GstMemoryMapFunction) _default_mem_map,
318     (GstMemoryUnmapFunction) _default_mem_unmap,
319     (GstMemoryFreeFunction) _default_mem_free,
320     (GstMemoryCopyFunction) _default_mem_copy,
321     (GstMemoryShareFunction) _default_mem_share,
322     (GstMemoryIsSpanFunction) _default_mem_is_span,
323     NULL
324   };
325
326   allocators = g_hash_table_new (g_str_hash, g_str_equal);
327
328 #ifdef HAVE_GETPAGESIZE
329 #ifdef MEMORY_ALIGNMENT_PAGESIZE
330   gst_memory_alignment = getpagesize () - 1;
331 #endif
332 #endif
333
334   _default_mem_impl = gst_allocator_register (GST_ALLOCATOR_SYSMEM, &_mem_info);
335
336   _default_allocator = _default_mem_impl;
337 }
338
339 /**
340  * gst_memory_new_wrapped:
341  * @flags: #GstMemoryFlags
342  * @data: data to wrap
343  * @free_func: function to free @data
344  * @maxsize: allocated size of @data
345  * @offset: offset in @data
346  * @size: size of valid data
347  *
348  * Allocate a new memory block that wraps the given @data.
349  *
350  * Returns: a new #GstMemory.
351  */
352 GstMemory *
353 gst_memory_new_wrapped (GstMemoryFlags flags, gpointer data,
354     GFreeFunc free_func, gsize maxsize, gsize offset, gsize size)
355 {
356   GstMemoryDefault *mem;
357
358   g_return_val_if_fail (data != NULL, NULL);
359   g_return_val_if_fail (offset + size <= maxsize, NULL);
360
361   mem = _default_mem_new (flags, NULL, data, free_func, maxsize, offset, size);
362
363   return (GstMemory *) mem;
364 }
365
366 /**
367  * gst_memory_ref:
368  * @mem: a #GstMemory
369  *
370  * Increases the refcount of @mem.
371  *
372  * Returns: @mem with increased refcount
373  */
374 GstMemory *
375 gst_memory_ref (GstMemory * mem)
376 {
377   g_return_val_if_fail (mem != NULL, NULL);
378
379   g_atomic_int_inc (&mem->refcount);
380
381   return mem;
382 }
383
384 /**
385  * gst_memory_unref:
386  * @mem: a #GstMemory
387  *
388  * Decreases the refcount of @mem. When the refcount reaches 0, the free
389  * function of @mem will be called.
390  */
391 void
392 gst_memory_unref (GstMemory * mem)
393 {
394   g_return_if_fail (mem != NULL);
395   g_return_if_fail (mem->allocator != NULL);
396
397   if (g_atomic_int_dec_and_test (&mem->refcount))
398     mem->allocator->info.free (mem);
399 }
400
401 /**
402  * gst_memory_get_sizes:
403  * @mem: a #GstMemory
404  * @offset: pointer to offset
405  * @maxsize: pointer to maxsize
406  *
407  * Get the current @size, @offset and @maxsize of @mem.
408  *
409  * Returns: the current sizes of @mem
410  */
411 gsize
412 gst_memory_get_sizes (GstMemory * mem, gsize * offset, gsize * maxsize)
413 {
414   g_return_val_if_fail (mem != NULL, 0);
415
416   return mem->allocator->info.get_sizes (mem, offset, maxsize);
417 }
418
419 /**
420  * gst_memory_resize:
421  * @mem: a #GstMemory
422  * @offset: a new offset
423  * @size: a new size
424  *
425  * Resize the memory region. @mem should be writable and offset + size should be
426  * less than the maxsize of @mem.
427  */
428 void
429 gst_memory_resize (GstMemory * mem, gssize offset, gsize size)
430 {
431   g_return_if_fail (mem != NULL);
432   g_return_if_fail (GST_MEMORY_IS_WRITABLE (mem));
433
434   mem->allocator->info.resize (mem, offset, size);
435 }
436
437 /**
438  * gst_memory_map:
439  * @mem: a #GstMemory
440  * @size: pointer for size
441  * @maxsize: pointer for maxsize
442  * @flags: mapping flags
443  *
444  * Get a pointer to the memory of @mem that can be accessed according to @flags.
445  *
446  * @size and @maxsize will contain the size of the memory and the maximum
447  * allocated memory of @mem respectively. They can be set to NULL.
448  *
449  * Returns: a pointer to the memory of @mem.
450  */
451 gpointer
452 gst_memory_map (GstMemory * mem, gsize * size, gsize * maxsize,
453     GstMapFlags flags)
454 {
455   g_return_val_if_fail (mem != NULL, NULL);
456   g_return_val_if_fail (!(flags & GST_MAP_WRITE) ||
457       GST_MEMORY_IS_WRITABLE (mem), NULL);
458
459   return mem->allocator->info.map (mem, size, maxsize, flags);
460 }
461
462 /**
463  * gst_memory_unmap:
464  * @mem: a #GstMemory
465  * @data: data to unmap
466  * @size: new size of @mem
467  *
468  * Release the memory pointer obtained with gst_memory_map() and set the size of
469  * the memory to @size. @size can be set to -1 when the size should not be
470  * updated.
471  *
472  * Returns: TRUE when the memory was release successfully.
473  */
474 gboolean
475 gst_memory_unmap (GstMemory * mem, gpointer data, gsize size)
476 {
477   g_return_val_if_fail (mem != NULL, FALSE);
478
479   return mem->allocator->info.unmap (mem, data, size);
480 }
481
482 /**
483  * gst_memory_copy:
484  * @mem: a #GstMemory
485  * @offset: an offset to copy
486  * @size: size to copy
487  *
488  * Return a copy of @size bytes from @mem starting from @offset. This copy is
489  * guaranteed to be writable. @size can be set to -1 to return a copy all bytes
490  * from @offset.
491  *
492  * Returns: a new #GstMemory.
493  */
494 GstMemory *
495 gst_memory_copy (GstMemory * mem, gssize offset, gsize size)
496 {
497   g_return_val_if_fail (mem != NULL, NULL);
498
499   return mem->allocator->info.copy (mem, offset, size);
500 }
501
502 /**
503  * gst_memory_share:
504  * @mem: a #GstMemory
505  * @offset: an offset to share
506  * @size: size to share
507  *
508  * Return a shared copy of @size bytes from @mem starting from @offset. No memory
509  * copy is performed and the memory region is simply shared. The result is
510  * guaranteed to be not-writable. @size can be set to -1 to return a share all bytes
511  * from @offset.
512  *
513  * Returns: a new #GstMemory.
514  */
515 GstMemory *
516 gst_memory_share (GstMemory * mem, gssize offset, gsize size)
517 {
518   g_return_val_if_fail (mem != NULL, NULL);
519
520   return mem->allocator->info.share (mem, offset, size);
521 }
522
523 /**
524  * gst_memory_is_span:
525  * @mem1: a #GstMemory
526  * @mem2: a #GstMemory
527  * @offset: a pointer to a result offset
528  *
529  * Check if @mem1 and mem2 share the memory with a common parent memory object
530  * and that the memory is contiguous.
531  *
532  * If this is the case, the memory of @mem1 and @mem2 can be merged
533  * efficiently by performing gst_memory_share() on the parent object from
534  * the returned @offset.
535  *
536  * Returns: %TRUE if the memory is contiguous and of a common parent.
537  */
538 gboolean
539 gst_memory_is_span (GstMemory * mem1, GstMemory * mem2, gsize * offset)
540 {
541   g_return_val_if_fail (mem1 != NULL, FALSE);
542   g_return_val_if_fail (mem2 != NULL, FALSE);
543
544   /* need to have the same allocators */
545   if (mem1->allocator != mem2->allocator)
546     return FALSE;
547
548   /* need to have the same parent */
549   if (mem1->parent == NULL || mem1->parent != mem2->parent)
550     return FALSE;
551
552   /* and memory is contiguous */
553   if (!mem1->allocator->info.is_span (mem1, mem2, offset))
554     return FALSE;
555
556   return TRUE;
557 }
558
559 /**
560  * gst_allocator_register:
561  * @name: the name of the allocator
562  * @info: #GstMemoryInfo
563  *
564  * Registers the memory allocator with @name and implementation functions
565  * @info.
566  *
567  * All functions in @info are mandatory exept the copy and is_span
568  * functions, which will have a default implementation when left NULL.
569  *
570  * The user_data field in @info will be passed to all calls of the alloc
571  * function.
572  *
573  * Returns: a new #GstAllocator.
574  */
575 const GstAllocator *
576 gst_allocator_register (const gchar * name, const GstMemoryInfo * info)
577 {
578   GstAllocator *allocator;
579
580 #define INSTALL_FALLBACK(_t) \
581   if (allocator->info._t == NULL) allocator->info._t = _fallback_ ##_t;
582
583   g_return_val_if_fail (name != NULL, NULL);
584   g_return_val_if_fail (info != NULL, NULL);
585   g_return_val_if_fail (info->alloc != NULL, NULL);
586   g_return_val_if_fail (info->get_sizes != NULL, NULL);
587   g_return_val_if_fail (info->resize != NULL, NULL);
588   g_return_val_if_fail (info->map != NULL, NULL);
589   g_return_val_if_fail (info->unmap != NULL, NULL);
590   g_return_val_if_fail (info->free != NULL, NULL);
591   g_return_val_if_fail (info->share != NULL, NULL);
592
593   allocator = g_slice_new (GstAllocator);
594   allocator->name = g_quark_from_string (name);
595   allocator->info = *info;
596   INSTALL_FALLBACK (copy);
597   INSTALL_FALLBACK (is_span);
598 #undef INSTALL_FALLBACK
599
600   GST_DEBUG ("registering allocator \"%s\"", name);
601
602   g_static_rw_lock_writer_lock (&lock);
603   g_hash_table_insert (allocators, (gpointer) name, (gpointer) allocator);
604   g_static_rw_lock_writer_unlock (&lock);
605
606   return allocator;
607 }
608
609 /**
610  * gst_allocator_find:
611  * @name: the name of the allocator
612  *
613  * Find a previously registered allocator with @name. When @name is NULL, the
614  * default allocator will be returned.
615  *
616  * Returns: a #GstAllocator or NULL when the allocator with @name was not
617  * registered.
618  */
619 const GstAllocator *
620 gst_allocator_find (const gchar * name)
621 {
622   const GstAllocator *allocator;
623
624   g_static_rw_lock_reader_lock (&lock);
625   if (name) {
626     allocator = g_hash_table_lookup (allocators, (gconstpointer) name);
627   } else {
628     allocator = _default_allocator;
629   }
630   g_static_rw_lock_reader_unlock (&lock);
631
632   return allocator;
633 }
634
635 /**
636  * gst_allocator_set_default:
637  * @allocator: a #GstAllocator
638  *
639  * Set the default allocator.
640  */
641 void
642 gst_allocator_set_default (const GstAllocator * allocator)
643 {
644   g_return_if_fail (allocator != NULL);
645
646   g_static_rw_lock_writer_lock (&lock);
647   _default_allocator = allocator;
648   g_static_rw_lock_writer_unlock (&lock);
649 }
650
651 /**
652  * gst_allocator_alloc:
653  * @allocator: a #GstAllocator to use
654  * @maxsize: allocated size of @data
655  * @align: alignment for the data
656  *
657  * Use @allocator to allocate a new memory block with memory that is at least
658  * @maxsize big and has the given alignment.
659  *
660  * When @allocator is NULL, the default allocator will be used.
661  *
662  * @align is given as a bitmask so that @align + 1 equals the amount of bytes to
663  * align to. For example, to align to 8 bytes, use an alignment of 7.
664  *
665  * Returns: a new #GstMemory.
666  */
667 GstMemory *
668 gst_allocator_alloc (const GstAllocator * allocator, gsize maxsize, gsize align)
669 {
670   g_return_val_if_fail (((align + 1) & align) == 0, NULL);
671
672   if (allocator == NULL)
673     allocator = _default_allocator;
674
675   return allocator->info.alloc (allocator, maxsize, align,
676       allocator->info.user_data);
677 }