mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2025-04-26 04:56:14 +00:00
Code Issues 1 Projects Releases Wiki Activity

design: miniobject: add missing markup

Browse source
This commit is contained in:
Reynaldo H. Verdejo Pinochet 2016-12-27 21:11:56 -08:00
parent 737dced0df
commit 5240dc0581
1 changed files with 35 additions and 35 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

70
markdown/design/miniobject.md
View file

@ -15,8 +15,8 @@ object is readable and writable.
## Usage ## Usage
Users of the GstMiniObject infrastructure will need to define a Users of the `GstMiniObject` infrastructure will need to define a
structure that includes the GstMiniObject structure as the first field. structure that includes the `GstMiniObject` structure as the first field.
``` c ``` c
struct { struct {
@ -29,8 +29,8 @@ struct {
The subclass should then implement a constructor method where it The subclass should then implement a constructor method where it
allocates the memory for its structure and initializes the miniobject allocates the memory for its structure and initializes the miniobject
structure with `gst\_mini\_object\_init()`. Copy and Free functions are structure with `gst_mini_object_init()`. Copy and Free functions are
provided to the `gst\_mini\_object\_init()` function. provided to the `gst_mini_object_init()` function.
``` c ``` c
MyObject * MyObject *
@ -67,31 +67,31 @@ _my_object_free (MyObject *obj)
## Lifecycle ## Lifecycle
GstMiniObject is refcounted. When a GstMiniObject is first created, it `GstMiniObject` is refcounted. When a `GstMiniObject` is first created, it
has a refcount of 1. has a refcount of 1.
Each variable holding a reference to a GstMiniObject is responsible for Each variable holding a reference to a GstMiniObject is responsible for
updating the refcount. This includes incrementing the refcount with updating the refcount. This includes incrementing the refcount with
`gst\_mini\_object\_ref()` when a reference is kept to a miniobject or `gst_mini_object_ref()` when a reference is kept to a miniobject or
`gst\_mini\_object\_unref()` when a reference is released. `gst_mini_object_unref()` when a reference is released.
When the refcount reaches 0, and thus no objects hold a reference to the When the refcount reaches 0, and thus no objects hold a reference to the
miniobject anymore, we can free the miniobject. miniobject anymore, we can free the miniobject.
When freeing the miniobject, first the GstMiniObjectDisposeFunction is When freeing the miniobject, first the `GstMiniObjectDisposeFunction` is
called. This function is allowed to revive the object again by called. This function is allowed to revive the object again by
incrementing the refcount, in which case it should return FALSE from the incrementing the refcount, in which case it should return FALSE from the
dispose function. The dispose function is used by GstBuffer to revive dispose function. The dispose function is used by GstBuffer to revive
the buffer back into the GstBufferPool when needed. the buffer back into the `GstBufferPool` when needed.
When the dispose function returns TRUE, the GstMiniObjectFreeFunction When the dispose function returns TRUE, the `GstMiniObjectFreeFunction`
will be called and the miniobject will be freed. will be called and the miniobject will be freed.
## Copy ## Copy
A miniobject can be copied with `gst\_mini\_object\_copy()`. This function A miniobject can be copied with `gst_mini_object_copy()`. This function
will call the custom copy function that was provided when registering will call the custom copy function that was provided when registering
the new GstMiniObject subclass. the new `GstMiniObject` subclass.
The copy function should try to preserve as much info from the original The copy function should try to preserve as much info from the original
object as possible. object as possible.
@ -100,8 +100,8 @@ The new copy should be writable.
## Access management ## Access management
GstMiniObject can be shared between multiple threads. It is important `GstMiniObject` can be shared between multiple threads. It is important
that when a thread writes to a GstMiniObject that the other threads that when a thread writes to a `GstMiniObject` that the other threads
don’t not see the changes. don’t not see the changes.
To avoid exposing changes from one thread to another thread, the To avoid exposing changes from one thread to another thread, the
@ -118,13 +118,13 @@ miniobject.
- A second method relies on a separate counter for controlling the - A second method relies on a separate counter for controlling the
access to the object. Objects using this method have the LOCKABLE access to the object. Objects using this method have the LOCKABLE
flag set. flag set.
You can check if an object is writable with gst_mini_object_is_writable() and You can check if an object is writable with `gst_mini_object_is_writable()` and
you can make any miniobject writable with gst_mini_object_make_writable(). you can make any miniobject writable with `gst_mini_object_make_writable()`.
This will create a writable copy when the object was not writable. This will create a writable copy when the object was not writable.
### non-LOCKABLE GstMiniObjects ### non-LOCKABLE GstMiniObjects
These GstMiniObjects have the LOCKABLE flag unset. They use the refcount value These `GstMiniObjects` have the LOCKABLE flag unset. They use the refcount value
to control writability of the object. to control writability of the object.
When the refcount of the miniobject is > 1, the objects it referenced by at When the refcount of the miniobject is > 1, the objects it referenced by at
@ -138,22 +138,22 @@ converted to use the LOCAKBLE flag.
### LOCKABLE GstMiniObjects ### LOCKABLE GstMiniObjects
These GstMiniObjects have the LOCKABLE flag set. They use a separate counter These `GstMiniObjects` have the LOCKABLE flag set. They use a separate counter
for controlling writability and access to the object. for controlling writability and access to the object.
It consists of 2 components: It consists of 2 components:
#### exclusive counter #### exclusive counter
Each object that wants to keep a reference to a GstMiniObject and doesn't want to Each object that wants to keep a reference to a `GstMiniObject` and doesn't want to
see the changes from other owners of the same GstMiniObject needs to lock the see the changes from other owners of the same `GstMiniObject` needs to lock the
GstMiniObject in EXCLUSIVE mode, which will increase the exclusive counter. `GstMiniObject` in EXCLUSIVE mode, which will increase the exclusive counter.
The exclusive counter counts the amount of objects that share this The exclusive counter counts the amount of objects that share this
GstMiniObject. The counter is initially 0, meaning that the object is not shared with `GstMiniObject`. The counter is initially 0, meaning that the object is not
any object. shared with any object.
When a reference to a GstMiniObject release, both the ref count and the When a reference to a `GstMiniObject` release, both the ref count and the
exclusive counter will be decreased with `gst_mini_object_unref()` and exclusive counter will be decreased with `gst_mini_object_unref()` and
`gst_mini_object_unlock()` respectively. `gst_mini_object_unlock()` respectively.
@ -163,37 +163,37 @@ All read and write access must be performed between a `gst_mini_object_lock()`
and `gst_mini_object_unlock()` pair with the requested access method. and `gst_mini_object_unlock()` pair with the requested access method.
A `gst_mini_object_lock()` can fail when a `WRITE` lock is requested and the A `gst_mini_object_lock()` can fail when a `WRITE` lock is requested and the
exclusive counter is > 1. Indeed a GstMiniObject object with an exclusive exclusive counter is > 1. Indeed a `GstMiniObject` object with an exclusive
counter > 1 is locked EXCLUSIVELY by at least 2 objects and is therefore not counter > 1 is locked EXCLUSIVELY by at least 2 objects and is therefore not
writable. writable.
Once the GstMiniObject is locked with a certain access mode, it can be Once the `GstMiniObject` is locked with a certain access mode, it can be
recursively locked with the same or narrower access mode. For example, first recursively locked with the same or narrower access mode. For example, first
locking the GstMiniObject in READWRITE mode allows you to recusively lock the locking the `GstMiniObject` in READWRITE mode allows you to recusively lock the
GstMiniObject in READWRITE, READ and WRITE mode. Memory locked in READ mode GstMiniObject in READWRITE, READ and WRITE mode. Memory locked in READ mode
cannot be locked recursively in WRITE or READWRITE mode. cannot be locked recursively in WRITE or READWRITE mode.
Note that multiple threads can READ lock the GstMiniObject concurrently but Note that multiple threads can READ lock the `GstMiniObject` concurrently but
cannot lock the object in WRITE mode because the exclusive counter must be > 1. cannot lock the object in WRITE mode because the exclusive counter must be > 1.
All calls to `gst_mini_object_lock()` need to be paired with one All calls to `gst_mini_object_lock()` need to be paired with one
`gst_mini_object_unlock()` call with the same access mode. When the last `gst_mini_object_unlock()` call with the same access mode. When the last
refcount of the object is removed, there should be no more outstanding locks. refcount of the object is removed, there should be no more outstanding locks.
Note that a shared counter of both 0 and 1 leaves the GstMiniObject writable. Note that a shared counter of both 0 and 1 leaves the `GstMiniObject` writable.
The reason is to make it easy to create and pass ownership of the GstMiniObject The reason is to make it easy to create and pass ownership of the `GstMiniObject`
to another object while keeping it writable. When the GstMiniObject is created to another object while keeping it writable. When the `GstMiniObject` is created
with a shared count of 0, it is writable. When the GstMiniObject is then added with a shared count of 0, it is writable. When the `GstMiniObject` is then added
to another object, the shared count is incremented to 1 and the GstMiniObject to another object, the shared count is incremented to 1 and the GstMiniObject
remains writable. The 0 share counter has a similar purpose as the floating remains writable. The 0 share counter has a similar purpose as the floating
reference in GObject. reference in `GObject`.
## Weak references ## Weak references
GstMiniObject has support for weak references. A callback will be called `GstMiniObject` has support for weak references. A callback will be called
when the object is freed for all registered weak references. when the object is freed for all registered weak references.
## QData ## QData
Extra data can be associated with a GstMiniObject by using the QData Extra data can be associated with a `GstMiniObject` by using the `QData`
API. API.