gstreamer/docs/design/part-memory.txt
Wim Taymans 80f4716a61 memory: check semantics of nested mappings
Count how many mappings are currently active and also with what access pattern.
Update the design doc with restrictions on the access patterns for nested
mappings.
Check if nested mappings obey the access mode restrictions of the design doc.
Add various unit tests to check the desired behaviour.
2012-01-06 13:10:18 +01:00

156 lines
5.1 KiB
Text

GstMemory
---------
This document describes the design of the memory objects.
GstMemory objects are usually added to GstBuffer objects and contain the
multimedia data passed around in the pipeline.
Requirements
~~~~~~~~~~~~
- It must be possible to have different memory allocators
- It must be possible to efficiently share memory objects, copy, span
and trim.
Allocators
~~~~~~~~~~
GstMemory objects are created by allocators. Allocators are registered to the
memory system with a set of methods contained in a GstMemoryInfo structure.
struct _GstMemoryInfo {
GstMemoryAllocFunction alloc;
GstMemoryGetSizesFunction get_sizes;
GstMemoryResizeFunction resize;
GstMemoryMapFunction map;
GstMemoryUnmapFunction unmap;
GstMemoryFreeFunction free;
GstMemoryCopyFunction copy;
GstMemoryShareFunction share;
GstMemoryIsSpanFunction is_span;
gpointer user_data;
};
After an allocator is registerd, new GstMemory can be created with
GstMemory * gst_allocator_alloc (const GstAllocator * allocator,
gsize maxsize, gsize align);
The GstMemory object is a refcounted object that must be freed with
gst_memory_unref ().
It is also possible to create a new GstMemory object that wraps existing
memory with:
GstMemory * gst_memory_new_wrapped (GstMemoryFlags flags, gpointer data,
GFreeFunc free_func, gsize maxsize,
gsize offset, gsize size);
Lifecycle
~~~~~~~~~
GstMemory objects are refcounted. When the GstMemory object is first created, it
has a refcount of 1.
Each variable holding a reference to the GstMemory object is responsible for
updating the refcount.
The refcount determines the writability of the object. If the refcount > 1, it is
by definition used by multipled objects and thus cannot be safely written to.
When the refcount reaches 0, and thus no objects hold a reference anymore, we
can free the memory. The GstMemoryFreeFunction of the allocator will be called
to cleanup the memory.
Memory layout
~~~~~~~~~~~~~
GstMemory manages a memory region. The accesible part of the managed region is
defined by an offset relative to the start of the region and a size. This
means that the managed region can be larger than what is visible to the user of
GstMemory API.
Schematically, GstMemory has a pointer to a memory region of _maxsize_. The area
starting from _offset_ and _size_ is accessible.
memory
GstMemory ->*----------------------------------------------------*
^----------------------------------------------------^
maxsize
^--------------------------------------^
offset size
The current properties of the accessible memory can be retrieved with:
gsize gst_memory_get_sizes (GstMemory *mem, gsize *offset, gsize *maxsize);
The offset and size can be changed with:
void gst_memory_resize (GstMemory *mem, gssize offset, gsize size);
The memory object is always readable. The memory block is writable when:
- the refcount is exactly 1
- the memory object has no parent, or if it has a parent, the parent is
writable.
- the memory object is not marked as READONLY.
Data Access
~~~~~~~~~~~
Access to the memory region is always controlled with a map and unmap method
call. This allows the implementation to monitor the access patterns or set up
the required memory mappings when needed.
Mapping a memory region requires the caller to specify the access method: READ
and/or WRITE. For write access, the GstMemory object must be writable.
After the data has been accessed in the object, the unmap call must be
performed. The call will update the new memory size with the specified size.
It is allowed to map multiple times with different access modes. for each of
the map calls, an corresponding unmap call needs to be made. WRITE-only memory
cannot be mapped in READ mode and READ-only memory cannot be mapped in WRITE
mode.
The memory pointer returned from the map call is guaranteed to remain valid in
the requested mapping mode until the corresponding unmap call is performed on
the pointer.
When multiple map operations are nested and return the same pointer, the pointer
is valid until the last unmap call is done.
When the final reference on a memory object is dropped, all outstanding
mappings are automatically unmapped.
Resizing a GstMemory does not influence any current mappings an any way. Note
however that the unmap call can resize the buffer again.
Copy
~~~~
A GstMemory copy can be made with the gst_memory_copy() call. Normally,
allocators will implement a custom version of this function to make a copy of
the same kind of memory as the original one.
This is what the fallback version of the copy function will do, albeit slower
than what as custom implementation could do.
The copy operation is only required to copy the visible range of the memory
block.
Share
~~~~~
A memory region can be shared between GstMemory object with the
gst_memory_share() operation.