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  * 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.
  34  *
  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
  37  * be used.
  38  *
  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().
  42  *
  43  * New memory can be created with gst_memory_new_wrapped() that wraps the memory
  44  * allocated elsewhere.
  45  *
  46  * Refcounting of the memory block is performed with gst_memory_ref() and
  47  * gst_memory_unref().
  48  *
  49  * The size of the memory can be retrieved and changed with
  50  * gst_memory_get_sizes() and gst_memory_resize() respectively.
  51  *
  52  * Getting access to the data of the memory is performed with gst_memory_map().
  53  * The call will return a pointer to offset bytes into the region of memory.
  54  * After the memory access is completed, gst_memory_unmap() should be called.
  55  *
  56  * Memory can be copied with gst_memory_copy(), which will return a writable
  57  * copy. gst_memory_share() will create a new memory block that shares the
  58  * memory with an existing memory block at a custom offset and with a custom
  59  * size.
  60  *
  61  * Memory can be efficiently merged when gst_memory_is_span() returns TRUE.
  62  *
  63  * Last reviewed on 2011-06-08 (0.11.0)
  64  */
  65
  66 #ifdef HAVE_CONFIG_H
  67 #include "config.h"
  68 #endif
  69
  70 #include "gst_private.h"
  71 #include "gstmemory.h"
  72
  73 #ifndef GST_DISABLE_TRACE
  74 #include "gsttrace.h"
  75 static GstAllocTrace *_gst_memory_trace;
  76 static GstAllocTrace *_gst_allocator_trace;
  77 #endif
  78
  79 G_DEFINE_BOXED_TYPE (GstMemory, gst_memory, (GBoxedCopyFunc) gst_memory_ref,
  80     (GBoxedFreeFunc) gst_memory_unref);
  81
  82 G_DEFINE_BOXED_TYPE (GstAllocator, gst_allocator,
  83     (GBoxedCopyFunc) gst_allocator_ref, (GBoxedFreeFunc) gst_allocator_unref);
  84
  85 G_DEFINE_BOXED_TYPE (GstAllocationParams, gst_allocation_params,
  86     (GBoxedCopyFunc) gst_allocation_params_copy,
  87     (GBoxedFreeFunc) gst_allocation_params_free);
  88
  89 /**
  90  * gst_memory_alignment:
  91  *
  92  * The default memory alignment in bytes - 1
  93  * an alignment of 7 would be the same as what malloc() guarantees.
  94  */
  95 #if defined(MEMORY_ALIGNMENT_MALLOC)
  96 size_t gst_memory_alignment = 7;
  97 #elif defined(MEMORY_ALIGNMENT_PAGESIZE)
  98 /* we fill this in in the _init method */
  99 size_t gst_memory_alignment = 0;
 100 #elif defined(MEMORY_ALIGNMENT)
 101 size_t gst_memory_alignment = MEMORY_ALIGNMENT - 1;
 102 #else
 103 #error "No memory alignment configured"
 104 size_t gst_memory_alignment = 0;
 105 #endif
 106
 107 struct _GstAllocator
 108 {
 109   gint refcount;
 110
 111   GstMemoryInfo info;
 112
 113   gpointer user_data;
 114   GDestroyNotify notify;
 115 };
 116
 117 /* default memory implementation */
 118 typedef struct
 119 {
 120   GstMemory mem;
 121   gsize slice_size;
 122   guint8 *data;
 123   gpointer user_data;
 124   GDestroyNotify notify;
 125 } GstMemoryDefault;
 126
 127 /* the default allocator */
 128 static GstAllocator *_default_allocator;
 129
 130 /* our predefined allocators */
 131 static GstAllocator *_default_mem_impl;
 132
 133 /* initialize the fields */
 134 static void
 135 _default_mem_init (GstMemoryDefault * mem, GstMemoryFlags flags,
 136     GstMemory * parent, gsize slice_size, gpointer data,
 137     gsize maxsize, gsize offset, gsize size, gsize align,
 138     gpointer user_data, GDestroyNotify notify)
 139 {
 140   mem->mem.allocator = _default_mem_impl;
 141   mem->mem.flags = flags;
 142   mem->mem.refcount = 1;
 143   mem->mem.parent = parent ? gst_memory_ref (parent) : NULL;
 144   mem->mem.state = (flags & GST_MEMORY_FLAG_READONLY ? 0x1 : 0);
 145   mem->mem.maxsize = maxsize;
 146   mem->mem.align = align;
 147   mem->mem.offset = offset;
 148   mem->mem.size = size;
 149   mem->slice_size = slice_size;
 150   mem->data = data;
 151   mem->user_data = user_data;
 152   mem->notify = notify;
 153
 154   GST_CAT_DEBUG (GST_CAT_MEMORY, "new memory %p, maxsize:%" G_GSIZE_FORMAT
 155       " offset:%" G_GSIZE_FORMAT " size:%" G_GSIZE_FORMAT, mem, maxsize,
 156       offset, size);
 157 }
 158
 159 /* create a new memory block that manages the given memory */
 160 static GstMemoryDefault *
 161 _default_mem_new (GstMemoryFlags flags, GstMemory * parent, gpointer data,
 162     gsize maxsize, gsize offset, gsize size, gsize align, gpointer user_data,
 163     GDestroyNotify notify)
 164 {
 165   GstMemoryDefault *mem;
 166   gsize slice_size;
 167
 168   slice_size = sizeof (GstMemoryDefault);
 169
 170   mem = g_slice_alloc (slice_size);
 171   _default_mem_init (mem, flags, parent, slice_size,
 172       data, maxsize, offset, size, align, user_data, notify);
 173
 174   return mem;
 175 }
 176
 177 /* allocate the memory and structure in one block */
 178 static GstMemoryDefault *
 179 _default_mem_new_block (GstMemoryFlags flags, gsize maxsize, gsize align,
 180     gsize offset, gsize size)
 181 {
 182   GstMemoryDefault *mem;
 183   gsize aoffset, slice_size, padding;
 184   guint8 *data;
 185
 186   /* ensure configured alignment */
 187   align |= gst_memory_alignment;
 188   /* allocate more to compensate for alignment */
 189   maxsize += align;
 190   /* alloc header and data in one block */
 191   slice_size = sizeof (GstMemoryDefault) + maxsize;
 192
 193   mem = g_slice_alloc (slice_size);
 194   if (mem == NULL)
 195     return NULL;
 196
 197   data = (guint8 *) mem + sizeof (GstMemoryDefault);
 198
 199   /* do alignment */
 200   if ((aoffset = ((guintptr) data & align))) {
 201     aoffset = (align + 1) - aoffset;
 202     data += aoffset;
 203     maxsize -= aoffset;
 204   }
 205
 206   if (offset && (flags & GST_MEMORY_FLAG_ZERO_PREFIXED))
 207     memset (data, 0, offset);
 208
 209   padding = maxsize - (offset + size);
 210   if (padding && (flags & GST_MEMORY_FLAG_ZERO_PADDED))
 211     memset (data + offset + size, 0, padding);
 212
 213   _default_mem_init (mem, flags, NULL, slice_size, data, maxsize,
 214       offset, size, align, NULL, NULL);
 215
 216   return mem;
 217 }
 218
 219 static GstMemory *
 220 _default_alloc_alloc (GstAllocator * allocator, gsize size,
 221     GstAllocationParams * params, gpointer user_data)
 222 {
 223   gsize maxsize = size + params->prefix + params->padding;
 224
 225   return (GstMemory *) _default_mem_new_block (params->flags,
 226       maxsize, params->align, params->prefix, size);
 227 }
 228
 229 static gpointer
 230 _default_mem_map (GstMemoryDefault * mem, GstMapFlags flags)
 231 {
 232   return mem->data;
 233 }
 234
 235 static gboolean
 236 _default_mem_unmap (GstMemoryDefault * mem)
 237 {
 238   return TRUE;
 239 }
 240
 241 static void
 242 _default_mem_free (GstMemoryDefault * mem)
 243 {
 244   GST_CAT_DEBUG (GST_CAT_MEMORY, "free memory %p", mem);
 245
 246   if (mem->mem.parent)
 247     gst_memory_unref (mem->mem.parent);
 248
 249   if (mem->notify)
 250     mem->notify (mem->user_data);
 251
 252   g_slice_free1 (mem->slice_size, mem);
 253 }
 254
 255 static GstMemoryDefault *
 256 _default_mem_copy (GstMemoryDefault * mem, gssize offset, gsize size)
 257 {
 258   GstMemoryDefault *copy;
 259
 260   if (size == -1)
 261     size = mem->mem.size > offset ? mem->mem.size - offset : 0;
 262
 263   copy =
 264       _default_mem_new_block (0, mem->mem.maxsize, 0, mem->mem.offset + offset,
 265       size);
 266   memcpy (copy->data, mem->data, mem->mem.maxsize);
 267   GST_CAT_DEBUG (GST_CAT_PERFORMANCE, "copy memory %p -> %p", mem, copy);
 268
 269   return copy;
 270 }
 271
 272 static GstMemoryDefault *
 273 _default_mem_share (GstMemoryDefault * mem, gssize offset, gsize size)
 274 {
 275   GstMemoryDefault *sub;
 276   GstMemory *parent;
 277
 278   /* find the real parent */
 279   if ((parent = mem->mem.parent) == NULL)
 280     parent = (GstMemory *) mem;
 281
 282   if (size == -1)
 283     size = mem->mem.size - offset;
 284
 285   sub =
 286       _default_mem_new (parent->flags, parent, mem->data,
 287       mem->mem.maxsize, mem->mem.offset + offset, size, mem->mem.align, NULL,
 288       NULL);
 289
 290   return sub;
 291 }
 292
 293 static gboolean
 294 _default_mem_is_span (GstMemoryDefault * mem1, GstMemoryDefault * mem2,
 295     gsize * offset)
 296 {
 297
 298   if (offset) {
 299     GstMemoryDefault *parent;
 300
 301     parent = (GstMemoryDefault *) mem1->mem.parent;
 302
 303     *offset = mem1->mem.offset - parent->mem.offset;
 304   }
 305
 306   /* and memory is contiguous */
 307   return mem1->data + mem1->mem.offset + mem1->mem.size ==
 308       mem2->data + mem2->mem.offset;
 309 }
 310
 311 static GstMemory *
 312 _fallback_mem_copy (GstMemory * mem, gssize offset, gssize size)
 313 {
 314   GstMemory *copy;
 315   GstMapInfo sinfo, dinfo;
 316   GstAllocationParams params = { 0, 0, 0, mem->align, };
 317
 318   if (!gst_memory_map (mem, &sinfo, GST_MAP_READ))
 319     return NULL;
 320
 321   if (size == -1)
 322     size = sinfo.size > offset ? sinfo.size - offset : 0;
 323
 324   /* use the same allocator as the memory we copy  */
 325   copy = gst_allocator_alloc (mem->allocator, size, &params);
 326   if (!gst_memory_map (copy, &dinfo, GST_MAP_WRITE)) {
 327     GST_CAT_WARNING (GST_CAT_MEMORY, "could not write map memory %p", copy);
 328     gst_memory_unmap (mem, &sinfo);
 329     return NULL;
 330   }
 331
 332   memcpy (dinfo.data, sinfo.data + offset, size);
 333   GST_CAT_DEBUG (GST_CAT_PERFORMANCE, "copy memory %p -> %p", mem, copy);
 334   gst_memory_unmap (copy, &dinfo);
 335   gst_memory_unmap (mem, &sinfo);
 336
 337   return copy;
 338 }
 339
 340 static gboolean
 341 _fallback_mem_is_span (GstMemory * mem1, GstMemory * mem2, gsize * offset)
 342 {
 343   return FALSE;
 344 }
 345
 346 static GRWLock lock;
 347 static GHashTable *allocators;
 348
 349 static void
 350 _priv_sysmem_notify (gpointer user_data)
 351 {
 352   g_warning ("The default memory allocator was freed!");
 353 }
 354
 355 void
 356 _priv_gst_memory_initialize (void)
 357 {
 358   static const GstMemoryInfo _mem_info = {
 359     GST_ALLOCATOR_SYSMEM,
 360     (GstAllocatorAllocFunction) _default_alloc_alloc,
 361     (GstMemoryMapFunction) _default_mem_map,
 362     (GstMemoryUnmapFunction) _default_mem_unmap,
 363     (GstMemoryFreeFunction) _default_mem_free,
 364     (GstMemoryCopyFunction) _default_mem_copy,
 365     (GstMemoryShareFunction) _default_mem_share,
 366     (GstMemoryIsSpanFunction) _default_mem_is_span,
 367   };
 368
 369 #ifndef GST_DISABLE_TRACE
 370   _gst_memory_trace = _gst_alloc_trace_register ("GstMemory", -1);
 371   _gst_allocator_trace = _gst_alloc_trace_register ("GstAllocator", -1);
 372 #endif
 373
 374   g_rw_lock_init (&lock);
 375   allocators = g_hash_table_new (g_str_hash, g_str_equal);
 376
 377 #ifdef HAVE_GETPAGESIZE
 378 #ifdef MEMORY_ALIGNMENT_PAGESIZE
 379   gst_memory_alignment = getpagesize () - 1;
 380 #endif
 381 #endif
 382
 383   GST_CAT_DEBUG (GST_CAT_MEMORY, "memory alignment: %" G_GSIZE_FORMAT,
 384       gst_memory_alignment);
 385
 386   _default_mem_impl = gst_allocator_new (&_mem_info, NULL, _priv_sysmem_notify);
 387
 388   _default_allocator = gst_allocator_ref (_default_mem_impl);
 389   gst_allocator_register (GST_ALLOCATOR_SYSMEM,
 390       gst_allocator_ref (_default_mem_impl));
 391 }
 392
 393 /**
 394  * gst_memory_new_wrapped:
 395  * @flags: #GstMemoryFlags
 396  * @data: data to wrap
 397  * @maxsize: allocated size of @data
 398  * @offset: offset in @data
 399  * @size: size of valid data
 400  * @user_data: user_data
 401  * @notify: called with @user_data when the memory is freed
 402  *
 403  * Allocate a new memory block that wraps the given @data.
 404  *
 405  * The prefix/padding must be filled with 0 if @flags contains
 406  * #GST_MEMORY_FLAG_ZERO_PREFIXED and #GST_MEMORY_FLAG_ZERO_PADDED respectively.
 407  *
 408  * Returns: a new #GstMemory.
 409  */
 410 GstMemory *
 411 gst_memory_new_wrapped (GstMemoryFlags flags, gpointer data,
 412     gsize maxsize, gsize offset, gsize size, gpointer user_data,
 413     GDestroyNotify notify)
 414 {
 415   GstMemoryDefault *mem;
 416
 417   g_return_val_if_fail (data != NULL, NULL);
 418   g_return_val_if_fail (offset + size <= maxsize, NULL);
 419
 420   mem =
 421       _default_mem_new (flags, NULL, data, maxsize, offset, size, 0, user_data,
 422       notify);
 423
 424 #ifndef GST_DISABLE_TRACE
 425   _gst_alloc_trace_new (_gst_memory_trace, mem);
 426 #endif
 427
 428   return (GstMemory *) mem;
 429 }
 430
 431 /**
 432  * gst_memory_ref:
 433  * @mem: a #GstMemory
 434  *
 435  * Increases the refcount of @mem.
 436  *
 437  * Returns: @mem with increased refcount
 438  */
 439 GstMemory *
 440 gst_memory_ref (GstMemory * mem)
 441 {
 442   g_return_val_if_fail (mem != NULL, NULL);
 443
 444   GST_CAT_TRACE (GST_CAT_MEMORY, "memory %p, %d->%d", mem, mem->refcount,
 445       mem->refcount + 1);
 446
 447   g_atomic_int_inc (&mem->refcount);
 448
 449   return mem;
 450 }
 451
 452 /**
 453  * gst_memory_unref:
 454  * @mem: a #GstMemory
 455  *
 456  * Decreases the refcount of @mem. When the refcount reaches 0, the free
 457  * function of @mem will be called.
 458  */
 459 void
 460 gst_memory_unref (GstMemory * mem)
 461 {
 462   g_return_if_fail (mem != NULL);
 463   g_return_if_fail (mem->allocator != NULL);
 464
 465   GST_CAT_TRACE (GST_CAT_MEMORY, "memory %p, %d->%d", mem, mem->refcount,
 466       mem->refcount - 1);
 467
 468   if (g_atomic_int_dec_and_test (&mem->refcount)) {
 469     /* there should be no outstanding mappings */
 470     g_return_if_fail (g_atomic_int_get (&mem->state) < 4);
 471 #ifndef GST_DISABLE_TRACE
 472     _gst_alloc_trace_free (_gst_memory_trace, mem);
 473 #endif
 474     mem->allocator->info.mem_free (mem);
 475   }
 476 }
 477
 478 /**
 479  * gst_memory_is_exclusive:
 480  * @mem: a #GstMemory
 481  *
 482  * Check if the current ref to @mem is exclusive, this means that no other
 483  * references exist other than @mem.
 484  */
 485 gboolean
 486 gst_memory_is_exclusive (GstMemory * mem)
 487 {
 488   g_return_val_if_fail (mem != NULL, FALSE);
 489
 490   return (g_atomic_int_get (&mem->refcount) == 1);
 491 }
 492
 493 /**
 494  * gst_memory_get_sizes:
 495  * @mem: a #GstMemory
 496  * @offset: pointer to offset
 497  * @maxsize: pointer to maxsize
 498  *
 499  * Get the current @size, @offset and @maxsize of @mem.
 500  *
 501  * Returns: the current sizes of @mem
 502  */
 503 gsize
 504 gst_memory_get_sizes (GstMemory * mem, gsize * offset, gsize * maxsize)
 505 {
 506   g_return_val_if_fail (mem != NULL, 0);
 507
 508   if (offset)
 509     *offset = mem->offset;
 510   if (maxsize)
 511     *maxsize = mem->maxsize;
 512
 513   return mem->size;
 514 }
 515
 516 /**
 517  * gst_memory_resize:
 518  * @mem: a #GstMemory
 519  * @offset: a new offset
 520  * @size: a new size
 521  *
 522  * Resize the memory region. @mem should be writable and offset + size should be
 523  * less than the maxsize of @mem.
 524  *
 525  * #GST_MEMORY_FLAG_ZERO_PREFIXED and #GST_MEMORY_FLAG_ZERO_PADDED will be
 526  * cleared when offset or padding is increased respectively.
 527  */
 528 void
 529 gst_memory_resize (GstMemory * mem, gssize offset, gsize size)
 530 {
 531   g_return_if_fail (mem != NULL);
 532   g_return_if_fail (offset >= 0 || mem->offset >= -offset);
 533   g_return_if_fail (size + mem->offset + offset <= mem->maxsize);
 534
 535   /* if we increase the prefix, we can't guarantee it is still 0 filled */
 536   if ((offset > 0) && GST_MEMORY_IS_ZERO_PREFIXED (mem))
 537     GST_MEMORY_FLAG_UNSET (mem, GST_MEMORY_FLAG_ZERO_PREFIXED);
 538
 539   /* if we increase the padding, we can't guarantee it is still 0 filled */
 540   if ((offset + size < mem->size) && GST_MEMORY_IS_ZERO_PADDED (mem))
 541     GST_MEMORY_FLAG_UNSET (mem, GST_MEMORY_FLAG_ZERO_PADDED);
 542
 543   mem->offset += offset;
 544   mem->size = size;
 545 }
 546
 547 static gboolean
 548 gst_memory_lock (GstMemory * mem, GstMapFlags flags)
 549 {
 550   gint access_mode, state, newstate;
 551
 552   access_mode = flags & 3;
 553
 554   do {
 555     state = g_atomic_int_get (&mem->state);
 556     if (state == 0) {
 557       /* nothing mapped, set access_mode and refcount */
 558       newstate = 4 | access_mode;
 559     } else {
 560       /* access_mode must match */
 561       if ((state & access_mode) != access_mode)
 562         goto lock_failed;
 563       /* increase refcount */
 564       newstate = state + 4;
 565     }
 566   } while (!g_atomic_int_compare_and_exchange (&mem->state, state, newstate));
 567
 568   return TRUE;
 569
 570 lock_failed:
 571   {
 572     GST_CAT_DEBUG (GST_CAT_MEMORY, "lock failed %p: state %d, access_mode %d",
 573         mem, state, access_mode);
 574     return FALSE;
 575   }
 576 }
 577
 578 static void
 579 gst_memory_unlock (GstMemory * mem)
 580 {
 581   gint state, newstate;
 582
 583   do {
 584     state = g_atomic_int_get (&mem->state);
 585     /* decrease the refcount */
 586     newstate = state - 4;
 587     /* last refcount, unset access_mode */
 588     if (newstate < 4)
 589       newstate = 0;
 590   } while (!g_atomic_int_compare_and_exchange (&mem->state, state, newstate));
 591 }
 592
 593
 594 /**
 595  * gst_memory_make_mapped:
 596  * @mem: (transfer full): a #GstMemory
 597  * @info: (out): pointer for info
 598  * @flags: mapping flags
 599  *
 600  * Create a #GstMemory object that is mapped with @flags. If @mem is mappable
 601  * with @flags, this function returns the mapped @mem directly. Otherwise a
 602  * mapped copy of @mem is returned.
 603  *
 604  * This function takes ownership of old @mem and returns a reference to a new
 605  * #GstMemory.
 606  *
 607  * Returns: (transfer full): a #GstMemory object mapped with @flags or NULL when
 608  * a mapping is not possible.
 609  */
 610 GstMemory *
 611 gst_memory_make_mapped (GstMemory * mem, GstMapInfo * info, GstMapFlags flags)
 612 {
 613   GstMemory *result;
 614
 615   if (gst_memory_map (mem, info, flags)) {
 616     result = mem;
 617   } else {
 618     result = gst_memory_copy (mem, 0, -1);
 619     gst_memory_unref (mem);
 620
 621     if (result == NULL)
 622       goto cannot_copy;
 623
 624     if (!gst_memory_map (result, info, flags))
 625       goto cannot_map;
 626   }
 627   return result;
 628
 629   /* ERRORS */
 630 cannot_copy:
 631   {
 632     GST_CAT_DEBUG (GST_CAT_MEMORY, "cannot copy memory %p", mem);
 633     return NULL;
 634   }
 635 cannot_map:
 636   {
 637     GST_CAT_DEBUG (GST_CAT_MEMORY, "cannot map memory %p with flags %d", mem,
 638         flags);
 639     gst_memory_unref (result);
 640     return NULL;
 641   }
 642 }
 643
 644 /**
 645  * gst_memory_map:
 646  * @mem: a #GstMemory
 647  * @info: (out): pointer for info
 648  * @flags: mapping flags
 649  *
 650  * Fill @info with the pointer and sizes of the memory in @mem that can be
 651  * accessed according to @flags.
 652  *
 653  * This function can return %FALSE for various reasons:
 654  * - the memory backed by @mem is not accessible with the given @flags.
 655  * - the memory was already mapped with a different mapping.
 656  *
 657  * @info and its contents remain valid for as long as @mem is valid and
 658  * until gst_memory_unmap() is called.
 659  *
 660  * For each gst_memory_map() call, a corresponding gst_memory_unmap() call
 661  * should be done.
 662  *
 663  * Returns: %TRUE if the map operation was successful.
 664  */
 665 gboolean
 666 gst_memory_map (GstMemory * mem, GstMapInfo * info, GstMapFlags flags)
 667 {
 668   g_return_val_if_fail (mem != NULL, FALSE);
 669   g_return_val_if_fail (info != NULL, FALSE);
 670
 671   if (!gst_memory_lock (mem, flags))
 672     goto lock_failed;
 673
 674   info->data = mem->allocator->info.mem_map (mem, mem->maxsize, flags);
 675
 676   if (G_UNLIKELY (info->data == NULL))
 677     goto error;
 678
 679   info->memory = mem;
 680   info->flags = flags;
 681   info->size = mem->size;
 682   info->maxsize = mem->maxsize - mem->offset;
 683   info->data = info->data + mem->offset;
 684
 685   return TRUE;
 686
 687   /* ERRORS */
 688 lock_failed:
 689   {
 690     GST_CAT_DEBUG (GST_CAT_MEMORY, "mem %p: lock %d failed", mem, flags);
 691     return FALSE;
 692   }
 693 error:
 694   {
 695     /* something went wrong, restore the orginal state again */
 696     GST_CAT_ERROR (GST_CAT_MEMORY, "mem %p: map failed", mem);
 697     gst_memory_unlock (mem);
 698     return FALSE;
 699   }
 700 }
 701
 702 /**
 703  * gst_memory_unmap:
 704  * @mem: a #GstMemory
 705  * @info: a #GstMapInfo
 706  *
 707  * Release the memory obtained with gst_memory_map()
 708  */
 709 void
 710 gst_memory_unmap (GstMemory * mem, GstMapInfo * info)
 711 {
 712   g_return_if_fail (mem != NULL);
 713   g_return_if_fail (info != NULL);
 714   g_return_if_fail (info->memory == mem);
 715   /* there must be a ref */
 716   g_return_if_fail (g_atomic_int_get (&mem->state) >= 4);
 717
 718   mem->allocator->info.mem_unmap (mem);
 719   gst_memory_unlock (mem);
 720 }
 721
 722 /**
 723  * gst_memory_copy:
 724  * @mem: a #GstMemory
 725  * @offset: an offset to copy
 726  * @size: size to copy or -1 to copy all bytes from offset
 727  *
 728  * Return a copy of @size bytes from @mem starting from @offset. This copy is
 729  * guaranteed to be writable. @size can be set to -1 to return a copy all bytes
 730  * from @offset.
 731  *
 732  * Returns: a new #GstMemory.
 733  */
 734 GstMemory *
 735 gst_memory_copy (GstMemory * mem, gssize offset, gssize size)
 736 {
 737   GstMemory *copy;
 738
 739   g_return_val_if_fail (mem != NULL, NULL);
 740
 741   copy = mem->allocator->info.mem_copy (mem, offset, size);
 742
 743 #ifndef GST_DISABLE_TRACE
 744   _gst_alloc_trace_new (_gst_memory_trace, copy);
 745 #endif
 746
 747   return copy;
 748 }
 749
 750 /**
 751  * gst_memory_share:
 752  * @mem: a #GstMemory
 753  * @offset: an offset to share
 754  * @size: size to share or -1 to share bytes from offset
 755  *
 756  * Return a shared copy of @size bytes from @mem starting from @offset. No
 757  * memory copy is performed and the memory region is simply shared. The result
 758  * is guaranteed to be not-writable. @size can be set to -1 to return a share
 759  * all bytes from @offset.
 760  *
 761  * Returns: a new #GstMemory.
 762  */
 763 GstMemory *
 764 gst_memory_share (GstMemory * mem, gssize offset, gssize size)
 765 {
 766   GstMemory *shared;
 767
 768   g_return_val_if_fail (mem != NULL, NULL);
 769   g_return_val_if_fail (!GST_MEMORY_FLAG_IS_SET (mem, GST_MEMORY_FLAG_NO_SHARE),
 770       NULL);
 771
 772   shared = mem->allocator->info.mem_share (mem, offset, size);
 773
 774 #ifndef GST_DISABLE_TRACE
 775   _gst_alloc_trace_new (_gst_memory_trace, shared);
 776 #endif
 777
 778   return shared;
 779 }
 780
 781 /**
 782  * gst_memory_is_span:
 783  * @mem1: a #GstMemory
 784  * @mem2: a #GstMemory
 785  * @offset: a pointer to a result offset
 786  *
 787  * Check if @mem1 and mem2 share the memory with a common parent memory object
 788  * and that the memory is contiguous.
 789  *
 790  * If this is the case, the memory of @mem1 and @mem2 can be merged
 791  * efficiently by performing gst_memory_share() on the parent object from
 792  * the returned @offset.
 793  *
 794  * Returns: %TRUE if the memory is contiguous and of a common parent.
 795  */
 796 gboolean
 797 gst_memory_is_span (GstMemory * mem1, GstMemory * mem2, gsize * offset)
 798 {
 799   g_return_val_if_fail (mem1 != NULL, FALSE);
 800   g_return_val_if_fail (mem2 != NULL, FALSE);
 801
 802   /* need to have the same allocators */
 803   if (mem1->allocator != mem2->allocator)
 804     return FALSE;
 805
 806   /* need to have the same parent */
 807   if (mem1->parent == NULL || mem1->parent != mem2->parent)
 808     return FALSE;
 809
 810   /* and memory is contiguous */
 811   if (!mem1->allocator->info.mem_is_span (mem1, mem2, offset))
 812     return FALSE;
 813
 814   return TRUE;
 815 }
 816
 817 /**
 818  * gst_allocator_register:
 819  * @info: a #GstMemoryInfo
 820  * @user_data: user data
 821  * @notify: a #GDestroyNotify for @user_data
 822  *
 823  * Create a new memory allocator with @info and @user_data.
 824  *
 825  * All functions in @info are mandatory exept the copy and is_span
 826  * functions, which will have a default implementation when left NULL.
 827  *
 828  * The @user_data will be passed to all calls of the alloc function. @notify
 829  * will be called with @user_data when the allocator is freed.
 830  *
 831  * Returns: a new #GstAllocator.
 832  */
 833 GstAllocator *
 834 gst_allocator_new (const GstMemoryInfo * info, gpointer user_data,
 835     GDestroyNotify notify)
 836 {
 837   GstAllocator *allocator;
 838
 839 #define INSTALL_FALLBACK(_t) \
 840   if (allocator->info._t == NULL) allocator->info._t = _fallback_ ##_t;
 841
 842   g_return_val_if_fail (info != NULL, NULL);
 843   g_return_val_if_fail (info->alloc != NULL, NULL);
 844   g_return_val_if_fail (info->mem_map != NULL, NULL);
 845   g_return_val_if_fail (info->mem_unmap != NULL, NULL);
 846   g_return_val_if_fail (info->mem_free != NULL, NULL);
 847   g_return_val_if_fail (info->mem_share != NULL, NULL);
 848
 849   allocator = g_slice_new (GstAllocator);
 850   allocator->refcount = 1;
 851   allocator->info = *info;
 852   allocator->user_data = user_data;
 853   allocator->notify = notify;
 854   INSTALL_FALLBACK (mem_copy);
 855   INSTALL_FALLBACK (mem_is_span);
 856 #undef INSTALL_FALLBACK
 857
 858   GST_CAT_DEBUG (GST_CAT_MEMORY, "new allocator %p", allocator);
 859
 860 #ifndef GST_DISABLE_TRACE
 861   _gst_alloc_trace_new (_gst_allocator_trace, allocator);
 862 #endif
 863
 864   return allocator;
 865 }
 866
 867 /**
 868  * gst_alocator_get_memory_type:
 869  * @allocator: a #GstAllocator
 870  *
 871  * Get the memory type allocated by this allocator
 872  *
 873  * Returns: the memory type provided by @allocator
 874  */
 875 const gchar *
 876 gst_allocator_get_memory_type (GstAllocator * allocator)
 877 {
 878   g_return_val_if_fail (allocator != NULL, NULL);
 879
 880   return allocator->info.mem_type;
 881 }
 882
 883 /**
 884  * gst_alocator_ref:
 885  * @allocator: a #GstAllocator
 886  *
 887  * Increases the refcount of @allocator.
 888  *
 889  * Returns: @allocator with increased refcount
 890  */
 891 GstAllocator *
 892 gst_allocator_ref (GstAllocator * allocator)
 893 {
 894   g_return_val_if_fail (allocator != NULL, NULL);
 895
 896   GST_CAT_TRACE (GST_CAT_MEMORY, "alocator %p, %d->%d", allocator,
 897       allocator->refcount, allocator->refcount + 1);
 898
 899   g_atomic_int_inc (&allocator->refcount);
 900
 901   return allocator;
 902 }
 903
 904 /**
 905  * gst_allocator_unref:
 906  * @allocator: a #GstAllocator
 907  *
 908  * Decreases the refcount of @allocator. When the refcount reaches 0, the notify
 909  * function of @allocator will be called and the allocator will be freed.
 910  */
 911 void
 912 gst_allocator_unref (GstAllocator * allocator)
 913 {
 914   g_return_if_fail (allocator != NULL);
 915
 916   GST_CAT_TRACE (GST_CAT_MEMORY, "allocator %p, %d->%d", allocator,
 917       allocator->refcount, allocator->refcount - 1);
 918
 919   if (g_atomic_int_dec_and_test (&allocator->refcount)) {
 920     if (allocator->notify)
 921       allocator->notify (allocator->user_data);
 922 #ifndef GST_DISABLE_TRACE
 923     _gst_alloc_trace_free (_gst_allocator_trace, allocator);
 924 #endif
 925     g_slice_free1 (sizeof (GstAllocator), allocator);
 926   }
 927 }
 928
 929 /**
 930  * gst_allocator_register:
 931  * @name: the name of the allocator
 932  * @allocator: (transfer full): #GstAllocator
 933  *
 934  * Registers the memory @allocator with @name. This function takes ownership of
 935  * @allocator.
 936  */
 937 void
 938 gst_allocator_register (const gchar * name, GstAllocator * allocator)
 939 {
 940   g_return_if_fail (name != NULL);
 941   g_return_if_fail (allocator != NULL);
 942
 943   GST_CAT_DEBUG (GST_CAT_MEMORY, "registering allocator %p with name \"%s\"",
 944       allocator, name);
 945
 946   g_rw_lock_writer_lock (&lock);
 947   g_hash_table_insert (allocators, (gpointer) name, (gpointer) allocator);
 948   g_rw_lock_writer_unlock (&lock);
 949 }
 950
 951 /**
 952  * gst_allocator_find:
 953  * @name: the name of the allocator
 954  *
 955  * Find a previously registered allocator with @name. When @name is NULL, the
 956  * default allocator will be returned.
 957  *
 958  * Returns: (transfer full): a #GstAllocator or NULL when the allocator with @name was not
 959  * registered. Use gst_allocator_unref() to release the allocator after usage.
 960  */
 961 GstAllocator *
 962 gst_allocator_find (const gchar * name)
 963 {
 964   GstAllocator *allocator;
 965
 966   g_rw_lock_reader_lock (&lock);
 967   if (name) {
 968     allocator = g_hash_table_lookup (allocators, (gconstpointer) name);
 969   } else {
 970     allocator = _default_allocator;
 971   }
 972   if (allocator)
 973     gst_allocator_ref (allocator);
 974   g_rw_lock_reader_unlock (&lock);
 975
 976   return allocator;
 977 }
 978
 979 /**
 980  * gst_allocator_set_default:
 981  * @allocator: (transfer full): a #GstAllocator
 982  *
 983  * Set the default allocator. This function takes ownership of @allocator.
 984  */
 985 void
 986 gst_allocator_set_default (GstAllocator * allocator)
 987 {
 988   GstAllocator *old;
 989   g_return_if_fail (allocator != NULL);
 990
 991   g_rw_lock_writer_lock (&lock);
 992   old = _default_allocator;
 993   _default_allocator = allocator;
 994   g_rw_lock_writer_unlock (&lock);
 995
 996   if (old)
 997     gst_allocator_unref (old);
 998 }
 999
1000 /**
1001  * gst_allocation_params_init:
1002  * @params: a #GstAllocationParams
1003  *
1004  * Initialize @params to its default values
1005  */
1006 void
1007 gst_allocation_params_init (GstAllocationParams * params)
1008 {
1009   g_return_if_fail (params != NULL);
1010
1011   memset (params, 0, sizeof (GstAllocationParams));
1012 }
1013
1014 /**
1015  * gst_allocation_params_copy:
1016  * @params: (transfer none): a #GstAllocationParams
1017  *
1018  * Create a copy of @params.
1019  *
1020  * Free-function: gst_allocation_params_free
1021  *
1022  * Returns: (transfer full): a new ##GstAllocationParams, free with
1023  * gst_allocation_params_free().
1024  */
1025 GstAllocationParams *
1026 gst_allocation_params_copy (const GstAllocationParams * params)
1027 {
1028   GstAllocationParams *result = NULL;
1029
1030   if (params) {
1031     result =
1032         (GstAllocationParams *) g_slice_copy (sizeof (GstAllocationParams),
1033         params);
1034   }
1035   return result;
1036 }
1037
1038 /**
1039  * gst_allocation_params_free:
1040  * @params: (in) (transfer full): a #GstAllocationParams
1041  *
1042  * Free @params
1043  */
1044 void
1045 gst_allocation_params_free (GstAllocationParams * params)
1046 {
1047   g_slice_free (GstAllocationParams, params);
1048 }
1049
1050 /**
1051  * gst_allocator_alloc:
1052  * @allocator: (transfer none) (allow-none): a #GstAllocator to use
1053  * @size: size of the visible memory area
1054  * @params: (transfer none) (allow-none): optional parameters
1055  *
1056  * Use @allocator to allocate a new memory block with memory that is at least
1057  * @size big.
1058  *
1059  * The optional @params can specify the prefix and padding for the memory. If
1060  * NULL is passed, no flags, no extra prefix/padding and a default alignment is
1061  * used.
1062  *
1063  * The prefix/padding will be filled with 0 if flags contains
1064  * #GST_MEMORY_FLAG_ZERO_PREFIXED and #GST_MEMORY_FLAG_ZERO_PADDED respectively.
1065  *
1066  * When @allocator is NULL, the default allocator will be used.
1067  *
1068  * The alignment in @params is given as a bitmask so that @align + 1 equals
1069  * the amount of bytes to align to. For example, to align to 8 bytes,
1070  * use an alignment of 7.
1071  *
1072  * Returns: (transfer full): a new #GstMemory.
1073  */
1074 GstMemory *
1075 gst_allocator_alloc (GstAllocator * allocator, gsize size,
1076     GstAllocationParams * params)
1077 {
1078   GstMemory *mem;
1079   static GstAllocationParams defparams = { 0, 0, 0, 0, };
1080
1081   if (params) {
1082     g_return_val_if_fail (((params->align + 1) & params->align) == 0, NULL);
1083   } else {
1084     params = &defparams;
1085   }
1086
1087   if (allocator == NULL)
1088     allocator = _default_allocator;
1089
1090   mem = allocator->info.alloc (allocator, size, params, allocator->user_data);
1091
1092 #ifndef GST_DISABLE_TRACE
1093   _gst_alloc_trace_new (_gst_memory_trace, mem);
1094 #endif
1095   return mem;
1096 }