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