mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2024-12-24 01:00:37 +00:00
Code Issues 1 Projects Releases Wiki Activity

design: MT-refcounting: fix missing markup, improve formatting and other fixes

Browse source
This commit is contained in:
Reynaldo H. Verdejo Pinochet 2017-02-10 15:33:06 -08:00
parent 979d92d458
commit df5be8ff92
1 changed files with 65 additions and 65 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

130
markdown/design/MT-refcounting.md
View file

@ -101,7 +101,7 @@ object.
All readers and writers acquire the lock before accessing the object. Only one All readers and writers acquire the lock before accessing the object. Only one
thread is allowed access the protected structures at a time. thread is allowed access the protected structures at a time.
Object locking is used for all objects extending from GstObject such as Object locking is used for all objects extending from `GstObject` such as
`GstElement`, `GstPad`. `GstElement`, `GstPad`.
Object locking can be done with recursive locks or regular mutexes. Object Object locking can be done with recursive locks or regular mutexes. Object
@ -153,7 +153,7 @@ not extend from the base `GstObject` class these macros can be different.
### refcounting ### refcounting
All new objects created have the FLOATING flag set. This means that the object All new objects created have the `FLOATING` flag set. This means that the object
is not owned or managed yet by anybody other than the one holding a reference is not owned or managed yet by anybody other than the one holding a reference
to the object. The object in this state has a reference count of 1. to the object. The object in this state has a reference count of 1.
@ -211,8 +211,8 @@ object. Two types of properties might exist: accessible with or without
holding the object lock. All properties should only be accessed with their holding the object lock. All properties should only be accessed with their
corresponding macros. The public object properties are marked in the .h files corresponding macros. The public object properties are marked in the .h files
with /*< public >*/. The public properties that require a lock to be held are with /*< public >*/. The public properties that require a lock to be held are
marked with `/*< public >*/` `/* with <lock_type> */`, where `<lock_type>` can be marked with `/*< public >*/` `/* with <lock_type> */`, where `<lock_type>` can
`LOCK` or `STATE_LOCK` or any other lock to mark the type(s) of lock to be be `LOCK` or `STATE_LOCK` or any other lock to mark the type(s) of lock to be
held. held.
**Example**: **Example**:
@ -221,24 +221,24 @@ in `GstPad` there is a public property `direction`. It can be found in the
section marked as public and requiring the LOCK to be held. There exists section marked as public and requiring the LOCK to be held. There exists
also a macro to access the property. also a macro to access the property.
``` ``` c
struct _GstRealPad { struct _GstRealPad {
... ...
/*< public >*/ /* with LOCK */ /*< public >*/ /* with LOCK */
... ...
GstPadDirection direction; GstPadDirection direction;
... ...
}; };
#define GST_RPAD_DIRECTION(pad) (GST_REAL_PAD_CAST(pad)->direction) #define GST_RPAD_DIRECTION(pad) (GST_REAL_PAD_CAST(pad)->direction)
``` ```
Accessing the property is therefore allowed with the following code example: Accessing the property is therefore allowed with the following code example:
``` ``` c
GST_OBJECT_LOCK (pad); GST_OBJECT_LOCK (pad);
direction = GST_RPAD_DIRECTION (pad); direction = GST_RPAD_DIRECTION (pad);
GST_OBJECT_UNLOCK (pad); GST_OBJECT_UNLOCK (pad);
``` ```
### Property lifetime ### Property lifetime
@ -264,16 +264,16 @@ required to increase the refcount of the peer pad because as soon as the
lock is released, the peer could be unreffed and disposed, making the lock is released, the peer could be unreffed and disposed, making the
pointer obtained in the critical section point to invalid memory. pointer obtained in the critical section point to invalid memory.
``` c ``` c
GST_OBJECT_LOCK (pad); GST_OBJECT_LOCK (pad);
peer = GST_RPAD_PEER (pad); peer = GST_RPAD_PEER (pad);
if (peer) if (peer)
gst_object_ref (GST_OBJECT (peer)); gst_object_ref (GST_OBJECT (peer));
GST_OBJECT_UNLOCK (pad); GST_OBJECT_UNLOCK (pad);
... use peer ... ... use peer ...
if (peer) if (peer)
gst_object_unref (GST_OBJECT (peer)); gst_object_unref (GST_OBJECT (peer));
``` ```
Note that after releasing the lock the peer might not actually be the peer Note that after releasing the lock the peer might not actually be the peer
@ -283,13 +283,13 @@ critical section to include the operations on the peer.
The following code is equivalent to the above but with using the functions The following code is equivalent to the above but with using the functions
to access object properties. to access object properties.
``` c ``` c
peer = gst_pad_get_peer (pad); peer = gst_pad_get_peer (pad);
if (peer) { if (peer) {
... use peer ... ... use peer ...
gst_object_unref (GST_OBJECT (peer)); gst_object_unref (GST_OBJECT (peer));
} }
``` ```
**Example**: **Example**:
@ -297,23 +297,23 @@ to access object properties.
Accessing the name of an object makes a copy of the name. The caller of the Accessing the name of an object makes a copy of the name. The caller of the
function should `g_free()` the name after usage. function should `g_free()` the name after usage.
``` c ``` c
GST_OBJECT_LOCK (object) GST_OBJECT_LOCK (object)
name = g_strdup (GST_OBJECT_NAME (object)); name = g_strdup (GST_OBJECT_NAME (object));
GST_OBJECT_UNLOCK (object) GST_OBJECT_UNLOCK (object)
... use name ... ... use name ...
g_free (name); g_free (name);
``` ```
or: or:
``` c ``` c
name = gst_object_get_name (object); name = gst_object_get_name (object);
... use name ... ... use name ...
g_free (name); g_free (name);
``` ```
### Accessor methods ### Accessor methods
@ -359,37 +359,37 @@ that whenever we reacquire the lock, we check for updates to the cookie to
decide if we are still iterating the right list. decide if we are still iterating the right list.
``` c ``` c
GST_OBJECT_LOCK (lock); GST_OBJECT_LOCK (lock);
/* grab list and cookie */ /* grab list and cookie */
cookie = object->list_cookie; cookie = object->list_cookie;
list = object-list; list = object-list;
while (list) { while (list) {
GstObject *item = GST_OBJECT (list->data); GstObject *item = GST_OBJECT (list->data);
/* need to ref the item before releasing the lock */ /* need to ref the item before releasing the lock */
gst_object_ref (item); gst_object_ref (item);
GST_OBJECT_UNLOCK (lock); GST_OBJECT_UNLOCK (lock);
... use/change item here... ... use/change item here...
/* release item here */ /* release item here */
gst_object_unref (item); gst_object_unref (item);
GST_OBJECT_LOCK (lock); GST_OBJECT_LOCK (lock);
if (cookie != object->list_cookie) { if (cookie != object->list_cookie) {
/* handle rollback caused by concurrent modification /* handle rollback caused by concurrent modification
* of the list here */ * of the list here */
...rollback changes to items... ...rollback changes to items...
/* grab new cookie and list */ /* grab new cookie and list */
cookie = object->list_cookie; cookie = object->list_cookie;
list = object->list; list = object->list;
} }
else { else {
list = g_list_next (list); list = g_list_next (list);
} }
} }
GST_OBJECT_UNLOCK (lock); GST_OBJECT_UNLOCK (lock);
``` ```
### GstIterator ### GstIterator
@ -399,7 +399,7 @@ list. The following code example is equivalent to the previous example.
**Example**: **Example**:
``` c ``` c
it = _get_iterator(object); it = _get_iterator(object);
while (!done) { while (!done) {
switch (gst_iterator_next (it, &item)) { switch (gst_iterator_next (it, &item)) {