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