gst/gstallocator.c

   1 /* GStreamer
   2  * Copyright (C) 2011 Wim Taymans <wim.taymans@gmail.be>
   3  *
   4  * gstallocator.c: memory block allocator
   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:gstallocator
  24  * @short_description: allocate memory blocks
  25  * @see_also: #GstMemory
  26  *
  27  * Memory is usually created by allocators with a gst_allocator_alloc()
  28  * method call. When NULL is used as the allocator, the default allocator will
  29  * be used.
  30  *
  31  * New allocators can be registered with gst_allocator_register().
  32  * Allocators are identified by name and can be retrieved with
  33  * gst_allocator_find(). gst_allocator_set_default() can be used to change the
  34  * default allocator.
  35  *
  36  * New memory can be created with gst_memory_new_wrapped() that wraps the memory
  37  * allocated elsewhere.
  38  *
  39  * Last reviewed on 2012-07-09 (0.11.3)
  40  */
  41
  42 #ifdef HAVE_CONFIG_H
  43 #include "config.h"
  44 #endif
  45
  46 #include "gst_private.h"
  47 #include "gstmemory.h"
  48
  49 GST_DEBUG_CATEGORY_STATIC (gst_allocator_debug);
  50 #define GST_CAT_DEFAULT gst_allocator_debug
  51
  52 #define GST_ALLOCATOR_GET_PRIVATE(obj)  \
  53      (G_TYPE_INSTANCE_GET_PRIVATE ((obj), GST_TYPE_ALLOCATOR, GstAllocatorPrivate))
  54
  55 struct _GstAllocatorPrivate
  56 {
  57   gpointer dummy;
  58 };
  59
  60 #if defined(MEMORY_ALIGNMENT_MALLOC)
  61 size_t gst_memory_alignment = 7;
  62 #elif defined(MEMORY_ALIGNMENT_PAGESIZE)
  63 /* we fill this in in the _init method */
  64 size_t gst_memory_alignment = 0;
  65 #elif defined(MEMORY_ALIGNMENT)
  66 size_t gst_memory_alignment = MEMORY_ALIGNMENT - 1;
  67 #else
  68 #error "No memory alignment configured"
  69 size_t gst_memory_alignment = 0;
  70 #endif
  71
  72 /* the default allocator */
  73 static GstAllocator *_default_allocator;
  74
  75 static GstAllocator *_sysmem_allocator;
  76
  77 /* registered allocators */
  78 static GRWLock lock;
  79 static GHashTable *allocators;
  80
  81 G_DEFINE_ABSTRACT_TYPE (GstAllocator, gst_allocator, GST_TYPE_OBJECT);
  82
  83 static void
  84 gst_allocator_class_init (GstAllocatorClass * klass)
  85 {
  86   g_type_class_add_private (klass, sizeof (GstAllocatorPrivate));
  87
  88   GST_DEBUG_CATEGORY_INIT (gst_allocator_debug, "allocator", 0,
  89       "allocator debug");
  90 }
  91
  92 static GstMemory *
  93 _fallback_mem_copy (GstMemory * mem, gssize offset, gssize size)
  94 {
  95   GstMemory *copy;
  96   GstMapInfo sinfo, dinfo;
  97   GstAllocationParams params = { 0, mem->align, 0, 0, };
  98
  99   if (!gst_memory_map (mem, &sinfo, GST_MAP_READ))
 100     return NULL;
 101
 102   if (size == -1)
 103     size = sinfo.size > offset ? sinfo.size - offset : 0;
 104
 105   /* use the same allocator as the memory we copy  */
 106   copy = gst_allocator_alloc (mem->allocator, size, &params);
 107   if (!gst_memory_map (copy, &dinfo, GST_MAP_WRITE)) {
 108     GST_CAT_WARNING (GST_CAT_MEMORY, "could not write map memory %p", copy);
 109     gst_memory_unmap (mem, &sinfo);
 110     return NULL;
 111   }
 112
 113   GST_CAT_DEBUG (GST_CAT_PERFORMANCE,
 114       "memcpy %" G_GSSIZE_FORMAT " memory %p -> %p", size, mem, copy);
 115   memcpy (dinfo.data, sinfo.data + offset, size);
 116   gst_memory_unmap (copy, &dinfo);
 117   gst_memory_unmap (mem, &sinfo);
 118
 119   return copy;
 120 }
 121
 122 static gboolean
 123 _fallback_mem_is_span (GstMemory * mem1, GstMemory * mem2, gsize * offset)
 124 {
 125   return FALSE;
 126 }
 127
 128 static void
 129 gst_allocator_init (GstAllocator * allocator)
 130 {
 131   allocator->priv = GST_ALLOCATOR_GET_PRIVATE (allocator);
 132
 133   allocator->mem_copy = _fallback_mem_copy;
 134   allocator->mem_is_span = _fallback_mem_is_span;
 135 }
 136
 137 G_DEFINE_BOXED_TYPE (GstAllocationParams, gst_allocation_params,
 138     (GBoxedCopyFunc) gst_allocation_params_copy,
 139     (GBoxedFreeFunc) gst_allocation_params_free);
 140
 141 /**
 142  * gst_allocation_params_init:
 143  * @params: a #GstAllocationParams
 144  *
 145  * Initialize @params to its default values
 146  */
 147 void
 148 gst_allocation_params_init (GstAllocationParams * params)
 149 {
 150   g_return_if_fail (params != NULL);
 151
 152   memset (params, 0, sizeof (GstAllocationParams));
 153 }
 154
 155 /**
 156  * gst_allocation_params_copy:
 157  * @params: (transfer none): a #GstAllocationParams
 158  *
 159  * Create a copy of @params.
 160  *
 161  * Free-function: gst_allocation_params_free
 162  *
 163  * Returns: (transfer full): a new ##GstAllocationParams, free with
 164  * gst_allocation_params_free().
 165  */
 166 GstAllocationParams *
 167 gst_allocation_params_copy (const GstAllocationParams * params)
 168 {
 169   GstAllocationParams *result = NULL;
 170
 171   if (params) {
 172     result =
 173         (GstAllocationParams *) g_slice_copy (sizeof (GstAllocationParams),
 174         params);
 175   }
 176   return result;
 177 }
 178
 179 /**
 180  * gst_allocation_params_free:
 181  * @params: (in) (transfer full): a #GstAllocationParams
 182  *
 183  * Free @params
 184  */
 185 void
 186 gst_allocation_params_free (GstAllocationParams * params)
 187 {
 188   g_slice_free (GstAllocationParams, params);
 189 }
 190
 191 /**
 192  * gst_allocator_register:
 193  * @name: the name of the allocator
 194  * @allocator: (transfer full): #GstAllocator
 195  *
 196  * Registers the memory @allocator with @name. This function takes ownership of
 197  * @allocator.
 198  */
 199 void
 200 gst_allocator_register (const gchar * name, GstAllocator * allocator)
 201 {
 202   g_return_if_fail (name != NULL);
 203   g_return_if_fail (allocator != NULL);
 204
 205   GST_CAT_DEBUG (GST_CAT_MEMORY, "registering allocator %p with name \"%s\"",
 206       allocator, name);
 207
 208   g_rw_lock_writer_lock (&lock);
 209   g_hash_table_insert (allocators, (gpointer) name, (gpointer) allocator);
 210   g_rw_lock_writer_unlock (&lock);
 211 }
 212
 213 /**
 214  * gst_allocator_find:
 215  * @name: the name of the allocator
 216  *
 217  * Find a previously registered allocator with @name. When @name is NULL, the
 218  * default allocator will be returned.
 219  *
 220  * Returns: (transfer full): a #GstAllocator or NULL when the allocator with @name was not
 221  * registered. Use gst_object_unref() to release the allocator after usage.
 222  */
 223 GstAllocator *
 224 gst_allocator_find (const gchar * name)
 225 {
 226   GstAllocator *allocator;
 227
 228   g_rw_lock_reader_lock (&lock);
 229   if (name) {
 230     allocator = g_hash_table_lookup (allocators, (gconstpointer) name);
 231   } else {
 232     allocator = _default_allocator;
 233   }
 234   if (allocator)
 235     gst_object_ref (allocator);
 236   g_rw_lock_reader_unlock (&lock);
 237
 238   return allocator;
 239 }
 240
 241 /**
 242  * gst_allocator_set_default:
 243  * @allocator: (transfer full): a #GstAllocator
 244  *
 245  * Set the default allocator. This function takes ownership of @allocator.
 246  */
 247 void
 248 gst_allocator_set_default (GstAllocator * allocator)
 249 {
 250   GstAllocator *old;
 251
 252   g_return_if_fail (GST_IS_ALLOCATOR (allocator));
 253
 254   g_rw_lock_writer_lock (&lock);
 255   old = _default_allocator;
 256   _default_allocator = allocator;
 257   g_rw_lock_writer_unlock (&lock);
 258
 259   if (old)
 260     gst_object_unref (old);
 261 }
 262
 263 /**
 264  * gst_allocator_alloc:
 265  * @allocator: (transfer none) (allow-none): a #GstAllocator to use
 266  * @size: size of the visible memory area
 267  * @params: (transfer none) (allow-none): optional parameters
 268  *
 269  * Use @allocator to allocate a new memory block with memory that is at least
 270  * @size big.
 271  *
 272  * The optional @params can specify the prefix and padding for the memory. If
 273  * NULL is passed, no flags, no extra prefix/padding and a default alignment is
 274  * used.
 275  *
 276  * The prefix/padding will be filled with 0 if flags contains
 277  * #GST_MEMORY_FLAG_ZERO_PREFIXED and #GST_MEMORY_FLAG_ZERO_PADDED respectively.
 278  *
 279  * When @allocator is NULL, the default allocator will be used.
 280  *
 281  * The alignment in @params is given as a bitmask so that @align + 1 equals
 282  * the amount of bytes to align to. For example, to align to 8 bytes,
 283  * use an alignment of 7.
 284  *
 285  * Returns: (transfer full): a new #GstMemory.
 286  */
 287 GstMemory *
 288 gst_allocator_alloc (GstAllocator * allocator, gsize size,
 289     GstAllocationParams * params)
 290 {
 291   GstMemory *mem;
 292   static GstAllocationParams defparams = { 0, 0, 0, 0, };
 293   GstAllocatorClass *aclass;
 294
 295   if (params) {
 296     g_return_val_if_fail (((params->align + 1) & params->align) == 0, NULL);
 297   } else {
 298     params = &defparams;
 299   }
 300
 301   if (allocator == NULL)
 302     allocator = _default_allocator;
 303
 304   aclass = GST_ALLOCATOR_GET_CLASS (allocator);
 305   if (aclass->alloc)
 306     mem = aclass->alloc (allocator, size, params);
 307   else
 308     mem = NULL;
 309
 310   return mem;
 311 }
 312
 313 /**
 314  * gst_allocator_free:
 315  * @allocator: (transfer none): a #GstAllocator to use
 316  * @memory: (transfer full): the memory to free
 317  *
 318  * Free @memory that was previously allocated with gst_allocator_alloc().
 319  */
 320 void
 321 gst_allocator_free (GstAllocator * allocator, GstMemory * memory)
 322 {
 323   GstAllocatorClass *aclass;
 324
 325   g_return_if_fail (GST_IS_ALLOCATOR (allocator));
 326   g_return_if_fail (memory != NULL);
 327   g_return_if_fail (memory->allocator == allocator);
 328
 329   aclass = GST_ALLOCATOR_GET_CLASS (allocator);
 330   if (aclass->free)
 331     aclass->free (allocator, memory);
 332 }
 333
 334 /* default memory implementation */
 335 typedef struct
 336 {
 337   GstMemory mem;
 338
 339   gsize slice_size;
 340   guint8 *data;
 341
 342   gpointer user_data;
 343   GDestroyNotify notify;
 344 } GstMemoryDefault;
 345
 346 typedef struct
 347 {
 348   GstAllocator parent;
 349 } GstDefaultAllocator;
 350
 351 typedef struct
 352 {
 353   GstAllocatorClass parent_class;
 354 } GstDefaultAllocatorClass;
 355
 356 GType gst_default_allocator_get_type (void);
 357 G_DEFINE_TYPE (GstDefaultAllocator, gst_default_allocator, GST_TYPE_ALLOCATOR);
 358
 359 /* initialize the fields */
 360 static inline void
 361 _default_mem_init (GstMemoryDefault * mem, GstMemoryFlags flags,
 362     GstMemory * parent, gsize slice_size,
 363     gpointer data, gsize maxsize, gsize align, gsize offset, gsize size,
 364     gpointer user_data, GDestroyNotify notify)
 365 {
 366   gst_memory_init (GST_MEMORY_CAST (mem),
 367       flags, _sysmem_allocator, parent, maxsize, align, offset, size);
 368
 369   mem->slice_size = slice_size;
 370   mem->data = data;
 371   mem->user_data = user_data;
 372   mem->notify = notify;
 373 }
 374
 375 /* create a new memory block that manages the given memory */
 376 static inline GstMemoryDefault *
 377 _default_mem_new (GstMemoryFlags flags,
 378     GstMemory * parent, gpointer data, gsize maxsize, gsize align, gsize offset,
 379     gsize size, gpointer user_data, GDestroyNotify notify)
 380 {
 381   GstMemoryDefault *mem;
 382   gsize slice_size;
 383
 384   slice_size = sizeof (GstMemoryDefault);
 385
 386   mem = g_slice_alloc (slice_size);
 387   _default_mem_init (mem, flags, parent, slice_size,
 388       data, maxsize, align, offset, size, user_data, notify);
 389
 390   return mem;
 391 }
 392
 393 /* allocate the memory and structure in one block */
 394 static GstMemoryDefault *
 395 _default_mem_new_block (GstMemoryFlags flags,
 396     gsize maxsize, gsize align, gsize offset, gsize size)
 397 {
 398   GstMemoryDefault *mem;
 399   gsize aoffset, slice_size, padding;
 400   guint8 *data;
 401
 402   /* ensure configured alignment */
 403   align |= gst_memory_alignment;
 404   /* allocate more to compensate for alignment */
 405   maxsize += align;
 406   /* alloc header and data in one block */
 407   slice_size = sizeof (GstMemoryDefault) + maxsize;
 408
 409   mem = g_slice_alloc (slice_size);
 410   if (mem == NULL)
 411     return NULL;
 412
 413   data = (guint8 *) mem + sizeof (GstMemoryDefault);
 414
 415   /* do alignment */
 416   if ((aoffset = ((guintptr) data & align))) {
 417     aoffset = (align + 1) - aoffset;
 418     data += aoffset;
 419     maxsize -= aoffset;
 420   }
 421
 422   if (offset && (flags & GST_MEMORY_FLAG_ZERO_PREFIXED))
 423     memset (data, 0, offset);
 424
 425   padding = maxsize - (offset + size);
 426   if (padding && (flags & GST_MEMORY_FLAG_ZERO_PADDED))
 427     memset (data + offset + size, 0, padding);
 428
 429   _default_mem_init (mem, flags, NULL, slice_size, data, maxsize,
 430       align, offset, size, NULL, NULL);
 431
 432   return mem;
 433 }
 434
 435 static gpointer
 436 _default_mem_map (GstMemoryDefault * mem, gsize maxsize, GstMapFlags flags)
 437 {
 438   return mem->data;
 439 }
 440
 441 static gboolean
 442 _default_mem_unmap (GstMemoryDefault * mem)
 443 {
 444   return TRUE;
 445 }
 446
 447 static GstMemoryDefault *
 448 _default_mem_copy (GstMemoryDefault * mem, gssize offset, gsize size)
 449 {
 450   GstMemoryDefault *copy;
 451
 452   if (size == -1)
 453     size = mem->mem.size > offset ? mem->mem.size - offset : 0;
 454
 455   copy =
 456       _default_mem_new_block (0, mem->mem.maxsize, mem->mem.align,
 457       mem->mem.offset + offset, size);
 458   GST_CAT_DEBUG (GST_CAT_PERFORMANCE,
 459       "memcpy %" G_GSIZE_FORMAT " memory %p -> %p", mem->mem.maxsize, mem,
 460       copy);
 461   memcpy (copy->data, mem->data, mem->mem.maxsize);
 462
 463   return copy;
 464 }
 465
 466 static GstMemoryDefault *
 467 _default_mem_share (GstMemoryDefault * mem, gssize offset, gsize size)
 468 {
 469   GstMemoryDefault *sub;
 470   GstMemory *parent;
 471
 472   /* find the real parent */
 473   if ((parent = mem->mem.parent) == NULL)
 474     parent = (GstMemory *) mem;
 475
 476   if (size == -1)
 477     size = mem->mem.size - offset;
 478
 479   /* the shared memory is always readonly */
 480   sub =
 481       _default_mem_new (GST_MINI_OBJECT_FLAGS (parent) |
 482       GST_MINI_OBJECT_FLAG_LOCK_READONLY, parent, mem->data, mem->mem.maxsize,
 483       mem->mem.align, mem->mem.offset + offset, size, NULL, NULL);
 484
 485   return sub;
 486 }
 487
 488 static gboolean
 489 _default_mem_is_span (GstMemoryDefault * mem1, GstMemoryDefault * mem2,
 490     gsize * offset)
 491 {
 492
 493   if (offset) {
 494     GstMemoryDefault *parent;
 495
 496     parent = (GstMemoryDefault *) mem1->mem.parent;
 497
 498     *offset = mem1->mem.offset - parent->mem.offset;
 499   }
 500
 501   /* and memory is contiguous */
 502   return mem1->data + mem1->mem.offset + mem1->mem.size ==
 503       mem2->data + mem2->mem.offset;
 504 }
 505
 506 static GstMemory *
 507 default_alloc (GstAllocator * allocator, gsize size,
 508     GstAllocationParams * params)
 509 {
 510   gsize maxsize = size + params->prefix + params->padding;
 511
 512   return (GstMemory *) _default_mem_new_block (params->flags,
 513       maxsize, params->align, params->prefix, size);
 514 }
 515
 516 static void
 517 default_free (GstAllocator * allocator, GstMemory * mem)
 518 {
 519   GstMemoryDefault *dmem = (GstMemoryDefault *) mem;
 520   gsize slice_size;
 521
 522   if (dmem->notify)
 523     dmem->notify (dmem->user_data);
 524
 525   slice_size = dmem->slice_size;
 526
 527 #ifdef USE_POISONING
 528   /* just poison the structs, not all the data */
 529   memset (mem, 0xff, sizeof (GstMemoryDefault));
 530 #endif
 531
 532   g_slice_free1 (slice_size, mem);
 533 }
 534
 535 static void
 536 gst_default_allocator_finalize (GObject * obj)
 537 {
 538   g_warning ("The default memory allocator was freed!");
 539 }
 540
 541 static void
 542 gst_default_allocator_class_init (GstDefaultAllocatorClass * klass)
 543 {
 544   GObjectClass *gobject_class;
 545   GstAllocatorClass *allocator_class;
 546
 547   gobject_class = (GObjectClass *) klass;
 548   allocator_class = (GstAllocatorClass *) klass;
 549
 550   gobject_class->finalize = gst_default_allocator_finalize;
 551
 552   allocator_class->alloc = default_alloc;
 553   allocator_class->free = default_free;
 554 }
 555
 556 static void
 557 gst_default_allocator_init (GstDefaultAllocator * allocator)
 558 {
 559   GstAllocator *alloc = GST_ALLOCATOR_CAST (allocator);
 560
 561   GST_CAT_DEBUG (GST_CAT_MEMORY, "init allocator %p", allocator);
 562
 563   alloc->mem_type = GST_ALLOCATOR_SYSMEM;
 564   alloc->mem_map = (GstMemoryMapFunction) _default_mem_map;
 565   alloc->mem_unmap = (GstMemoryUnmapFunction) _default_mem_unmap;
 566   alloc->mem_copy = (GstMemoryCopyFunction) _default_mem_copy;
 567   alloc->mem_share = (GstMemoryShareFunction) _default_mem_share;
 568   alloc->mem_is_span = (GstMemoryIsSpanFunction) _default_mem_is_span;
 569 }
 570
 571 void
 572 _priv_gst_memory_initialize (void)
 573 {
 574   g_rw_lock_init (&lock);
 575   allocators = g_hash_table_new (g_str_hash, g_str_equal);
 576
 577 #ifdef HAVE_GETPAGESIZE
 578 #ifdef MEMORY_ALIGNMENT_PAGESIZE
 579   gst_memory_alignment = getpagesize () - 1;
 580 #endif
 581 #endif
 582
 583   GST_CAT_DEBUG (GST_CAT_MEMORY, "memory alignment: %" G_GSIZE_FORMAT,
 584       gst_memory_alignment);
 585
 586   _sysmem_allocator = g_object_new (gst_default_allocator_get_type (), NULL);
 587
 588   gst_allocator_register (GST_ALLOCATOR_SYSMEM,
 589       gst_object_ref (_sysmem_allocator));
 590
 591   _default_allocator = gst_object_ref (_sysmem_allocator);
 592 }
 593
 594 /**
 595  * gst_memory_new_wrapped:
 596  * @flags: #GstMemoryFlags
 597  * @data: data to wrap
 598  * @maxsize: allocated size of @data
 599  * @offset: offset in @data
 600  * @size: size of valid data
 601  * @user_data: user_data
 602  * @notify: called with @user_data when the memory is freed
 603  *
 604  * Allocate a new memory block that wraps the given @data.
 605  *
 606  * The prefix/padding must be filled with 0 if @flags contains
 607  * #GST_MEMORY_FLAG_ZERO_PREFIXED and #GST_MEMORY_FLAG_ZERO_PADDED respectively.
 608  *
 609  * Returns: a new #GstMemory.
 610  */
 611 GstMemory *
 612 gst_memory_new_wrapped (GstMemoryFlags flags, gpointer data,
 613     gsize maxsize, gsize offset, gsize size, gpointer user_data,
 614     GDestroyNotify notify)
 615 {
 616   GstMemoryDefault *mem;
 617
 618   g_return_val_if_fail (data != NULL, NULL);
 619   g_return_val_if_fail (offset + size <= maxsize, NULL);
 620
 621   mem =
 622       _default_mem_new (flags, NULL, data, maxsize, 0, offset, size, user_data,
 623       notify);
 624
 625   return (GstMemory *) mem;
 626 }