mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2025-04-28 16:04:54 +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

74
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
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`.
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
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
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
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
marked with `/*< public >*/` `/* with <lock_type> */`, where `<lock_type>` can be
`LOCK` or `STATE_LOCK` or any other lock to mark the type(s) of lock to be
marked with `/*< public >*/` `/* with <lock_type> */`, where `<lock_type>` can
be `LOCK` or `STATE_LOCK` or any other lock to mark the type(s) of lock to be
held.
**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
also a macro to access the property.
```
struct _GstRealPad {
``` c
struct _GstRealPad {
...
/*< public >*/ /* with LOCK */
...
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:
```
GST_OBJECT_LOCK (pad);
direction = GST_RPAD_DIRECTION (pad);
GST_OBJECT_UNLOCK (pad);
``` c
GST_OBJECT_LOCK (pad);
direction = GST_RPAD_DIRECTION (pad);
GST_OBJECT_UNLOCK (pad);
```
### Property lifetime
@ -265,14 +265,14 @@ lock is released, the peer could be unreffed and disposed, making the
pointer obtained in the critical section point to invalid memory.
``` c
GST_OBJECT_LOCK (pad);
peer = GST_RPAD_PEER (pad);
if (peer)
gst_object_ref (GST_OBJECT (peer));
GST_OBJECT_UNLOCK (pad);
... use peer ...
GST_OBJECT_LOCK (pad);
peer = GST_RPAD_PEER (pad);
if (peer)
gst_object_ref (GST_OBJECT (peer));
GST_OBJECT_UNLOCK (pad);
... use peer ...
if (peer)
if (peer)
gst_object_unref (GST_OBJECT (peer));
```
@ -284,12 +284,12 @@ The following code is equivalent to the above but with using the functions
to access object properties.
``` c
peer = gst_pad_get_peer (pad);
if (peer) {
peer = gst_pad_get_peer (pad);
if (peer) {
... use peer ...
gst_object_unref (GST_OBJECT (peer));
}
}
```
**Example**:
@ -298,22 +298,22 @@ Accessing the name of an object makes a copy of the name. The caller of the
function should `g_free()` the name after usage.
``` c
GST_OBJECT_LOCK (object)
name = g_strdup (GST_OBJECT_NAME (object));
GST_OBJECT_UNLOCK (object)
... use name ...
GST_OBJECT_LOCK (object)
name = g_strdup (GST_OBJECT_NAME (object));
GST_OBJECT_UNLOCK (object)
... use name ...
g_free (name);
g_free (name);
```
or:
``` 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
@ -359,11 +359,11 @@ that whenever we reacquire the lock, we check for updates to the cookie to
decide if we are still iterating the right list.
``` c
GST_OBJECT_LOCK (lock);
/* grab list and cookie */
cookie = object->list_cookie;
list = object-list;
while (list) {
GST_OBJECT_LOCK (lock);
/* grab list and cookie */
cookie = object->list_cookie;
list = object-list;
while (list) {
GstObject *item = GST_OBJECT (list->data);
/* need to ref the item before releasing the lock */
gst_object_ref (item);
@ -388,8 +388,8 @@ decide if we are still iterating the right list.
else {
list = g_list_next (list);
}
}
GST_OBJECT_UNLOCK (lock);
}
GST_OBJECT_UNLOCK (lock);
```
### GstIterator