mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2025-01-11 18:05:37 +00:00
Code Issues 1 Projects Releases Wiki Activity

design: miniobject: fix missing markup, improve formatting and other fixes

Browse source
This commit is contained in:
Reynaldo H. Verdejo Pinochet 2017-02-10 15:01:40 -08:00
parent 9f25890d2b
commit 979d92d458
1 changed files with 27 additions and 26 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

53
markdown/design/miniobject.md
View file

@ -1,8 +1,8 @@
# GstMiniObject # GstMiniObject
This document describes the design of the miniobject base class. This document describes the design of the `GstMiniObject` base class.
The miniobject abstract base class is used to construct lightweight The `GstMiniObject` abstract base class is used to construct lightweight,
refcounted and boxed types that are frequently created and destroyed. refcounted and boxed types that are frequently created and destroyed.
## Requirements ## Requirements
@ -70,7 +70,7 @@ _my_object_free (MyObject *obj)
`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.
@ -81,7 +81,7 @@ 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`
@ -109,11 +109,10 @@ miniobjects are managed in a Copy-On-Write way. A copy is only made when
it is known that the object is shared between multiple objects or it is known that the object is shared between multiple objects or
threads. threads.
There are 2 methods implemented for controlling access to the There are 2 methods implemented for controlling access to the miniobject.
miniobject.
- A first method relies on the refcount of the object to control - A first method relies on the refcount of the object to control
writability. Objects using this method have the LOCKABLE flag unset. writability. Objects using this method have the `LOCKABLE` flag unset.
- 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
@ -124,8 +123,8 @@ miniobject.
### 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
to control writability of the object. value 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
least 2 objects and is thus considered unwritable. A copy must be made before a least 2 objects and is thus considered unwritable. A copy must be made before a
@ -134,20 +133,21 @@ modification to the object can be done.
Using the refcount to control writability is problematic for many language Using the refcount to control writability is problematic for many language
bindings that can keep additional references to the objects. This method is bindings that can keep additional references to the objects. This method is
mainly for historical reasons until all users of the miniobjects are mainly for historical reasons until all users of the miniobjects are
converted to use the LOCAKBLE flag. converted to use the `LOCKABLE` 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
see the changes from other owners of the same `GstMiniObject` needs to lock the want to see the changes from other owners of the same `GstMiniObject` needs to
`GstMiniObject` in EXCLUSIVE mode, which will increase the exclusive counter. lock the `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 `GstMiniObject`. The counter is initially 0, meaning that the object is not
@ -164,29 +164,30 @@ 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
GstMiniObject in READWRITE, READ and WRITE mode. Memory locked in READ mode the `GstMiniObject` in `READWRITE`, `READ` and `WRITE` mode. Memory locked in
cannot be locked recursively in WRITE or READWRITE mode. `READ` 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
to another object while keeping it writable. When the `GstMiniObject` is created `GstMiniObject` to another object while keeping it writable. When the
with a shared count of 0, it is writable. When the `GstMiniObject` is then added `GstMiniObject` is created with a shared count of 0, it is writable. When the
to another object, the shared count is incremented to 1 and the GstMiniObject `GstMiniObject` is then added to another object, the shared count is incremented
remains writable. The 0 share counter has a similar purpose as the floating to 1 and the `GstMiniObject` remains writable. The 0 share counter has a similar
reference in `GObject`. purpose as the floating reference in `GObject`.
## Weak references ## Weak references