summary | shortlog | log | commit | commitdiff | tree
raw | patch | inline | side by side (parent: f3aa2d7)
raw | patch | inline | side by side (parent: f3aa2d7)
author | Wim Taymans <wim.taymans@gmail.com> | |
Tue, 8 Mar 2005 14:38:06 +0000 (14:38 +0000) | ||
committer | Wim Taymans <wim.taymans@gmail.com> | |
Tue, 8 Mar 2005 14:38:06 +0000 (14:38 +0000) |
Original commit message from CVS:
* docs/design/part-MT-refcounting.txt:
* docs/design/part-conventions.txt:
* docs/design/part-gstobject.txt:
* docs/design/part-relations.txt:
* docs/design/part-standards.txt:
* gst/gstbin.c: (gst_bin_add_func), (gst_bin_add),
(gst_bin_remove_func), (gst_bin_remove), (gst_bin_iterate_recurse),
(gst_bin_get_by_name), (gst_bin_get_by_interface),
(gst_bin_iterate_all_by_interface):
* gst/gstbuffer.h:
* gst/gstclock.h:
* gst/gstelement.c: (gst_element_class_init),
(gst_element_change_state), (gst_element_set_loop_function):
* gst/gstelement.h:
* gst/gstiterator.c:
* gst/gstobject.c: (gst_object_class_init), (gst_object_ref),
(gst_object_unref), (gst_object_sink), (gst_object_dispose),
(gst_object_dispatch_properties_changed), (gst_object_set_name),
(gst_object_set_parent), (gst_object_unparent),
(gst_object_check_uniqueness):
* gst/gstobject.h:
Docs updates, clean up some headers.
Free iterators in GstBin.
GstObject is now looking good.
* docs/design/part-MT-refcounting.txt:
* docs/design/part-conventions.txt:
* docs/design/part-gstobject.txt:
* docs/design/part-relations.txt:
* docs/design/part-standards.txt:
* gst/gstbin.c: (gst_bin_add_func), (gst_bin_add),
(gst_bin_remove_func), (gst_bin_remove), (gst_bin_iterate_recurse),
(gst_bin_get_by_name), (gst_bin_get_by_interface),
(gst_bin_iterate_all_by_interface):
* gst/gstbuffer.h:
* gst/gstclock.h:
* gst/gstelement.c: (gst_element_class_init),
(gst_element_change_state), (gst_element_set_loop_function):
* gst/gstelement.h:
* gst/gstiterator.c:
* gst/gstobject.c: (gst_object_class_init), (gst_object_ref),
(gst_object_unref), (gst_object_sink), (gst_object_dispose),
(gst_object_dispatch_properties_changed), (gst_object_set_name),
(gst_object_set_parent), (gst_object_unparent),
(gst_object_check_uniqueness):
* gst/gstobject.h:
Docs updates, clean up some headers.
Free iterators in GstBin.
GstObject is now looking good.
14 files changed:
diff --git a/ChangeLog b/ChangeLog
index 313f3270175721215fd5856878c917d9d249aa03..5f3942768bee1dad8121553148b979fc9eb5997d 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
+2005-03-08 Wim Taymans <wim@fluendo.com>
+
+ * docs/design/part-MT-refcounting.txt:
+ * docs/design/part-conventions.txt:
+ * docs/design/part-gstobject.txt:
+ * docs/design/part-relations.txt:
+ * docs/design/part-standards.txt:
+ * gst/gstbin.c: (gst_bin_add_func), (gst_bin_add),
+ (gst_bin_remove_func), (gst_bin_remove), (gst_bin_iterate_recurse),
+ (gst_bin_get_by_name), (gst_bin_get_by_interface),
+ (gst_bin_iterate_all_by_interface):
+ * gst/gstbuffer.h:
+ * gst/gstclock.h:
+ * gst/gstelement.c: (gst_element_class_init),
+ (gst_element_change_state), (gst_element_set_loop_function):
+ * gst/gstelement.h:
+ * gst/gstiterator.c:
+ * gst/gstobject.c: (gst_object_class_init), (gst_object_ref),
+ (gst_object_unref), (gst_object_sink), (gst_object_dispose),
+ (gst_object_dispatch_properties_changed), (gst_object_set_name),
+ (gst_object_set_parent), (gst_object_unparent),
+ (gst_object_check_uniqueness):
+ * gst/gstobject.h:
+ Docs updates, clean up some headers.
+
2005-03-07 Wim Taymans <wim@fluendo.com>
* check/.cvsignore:
index e3b1e2ebd76ad335d38d750a236c3275152bf955..3d45064ec1866bc0b4002b5b2c03f9f553efe0f8 100644 (file)
anymore of the pad. If you need to be sure it is, you need to extend the
critical section to include the operations on the peer.
+ The following code is equivalent to the above but with using the functions
+ to access object properties.
+
+ peer = gst_pad_get_parent (pad);
+ if (peer) {
+ ... use peer ...
+
+ gst_object_unref (GST_OBJECT (peer));
+ }
+
Example:
Accessing the name of an object makes a copy of the name. The caller of the
... use name ...
g_free (name);
+
+ or:
+
+ name = gst_object_get_name (object);
+
+ ... use name ...
+
+ g_free (name);
* Accessor methods
index f2610a7278bb10afc54818967fd9d52dd4f86827..5569644d6ca1be6e512469470fac2587f8611967 100644 (file)
element flags should be cross-checked with the header, as there are currently two conventions in use: with and without
_FLAGS_ in the middle.
-FIXME: check flags for consistency.
-
Drawing conventions
===================
index a85480e21c1541a7ac35e4b79fb80c15f7c0bef5..9e1d9f87876881239d843a4d6bb06aa66c4475e7 100644 (file)
GstElement (inside a bin)
GstPad (inside an element)
+
Refcounting
-----------
-- GObject refcount is not threadsafe.
- GStreamer sets it to a constant value on each _ref/_unref()
+- GObject refcount is not threadsafe. This will be changed in the future.
+ GStreamer for now sets it to a constant value on each _ref/_unref()
and uses an atomic int "refcount" instead for threadsafe refcounting
This implies you should always use gst_object_ref() and gst_object_unref() !
+
Naming
------
- names of objects cannot be changed when they are parented
a more identifiable name. Typically a parent will call _set_name_prefix
on children, taking a lock on them to do so.
+
Locking
-------
All members of the GstObject structure marked as
/*< public >*/ /* with LOCK */
are protected by this lock. These members can only be accessed for reading
-or writing while the lock is held.
+or writing while the lock is held. All members should be copied or reffed
+if they are used after releasing the LOCK.
Note that this does *not* mean that no other thread can modify the object at
the same time that the lock is held. It only means that any two sections of
code that obey the lock are guaranteed to not be running simultaneously. "The
lock is voluntary and cooperative".
-This lock will ideally be used for parentage and refcounting, which is
+This lock will ideally be used for parentage, flags and naming, which is
reasonable, since they are the only possible things to protect in the
GstObject.
+
Path Generation
---------------
-FIXME: rethink this ?
Due to the base nature of the GstObject, it becomes the only reasonable place
to put this particular function (_get_path_string). It will generate a string
-describing the parent hierarchy of a given GstObject. Currently it is forced
-to use several child-class-specific functions, because we do not properly use
-the base capabilities (parentage, etc.) of GstObject properly.
+describing the parent hierarchy of a given GstObject.
+
+
+Flags
+-----
+
+Each object in the GStreamer object hierarchy can have flags associated with it,
+which are used to describe a state or a feature of the object.
+GstObject has flags to mark its lifecycle: FLOATING, DISPOSING and DESTROYED.
+
+
+Class signals
+-------------
+
+It is possible to know when a new object is loaded by connecting to the
+GstObjectClass signal. This feature is not very much used and might be removed
+at some point.
index f2deabbff45433f959c90fe9c7e94fe9b0ed6613..a84e4477cf7faaed6e380e6b0b6f5cd0aeeea8b0 100644 (file)
Object relation types
---------------------
+This document describes the relations between objects that exist in GStreamer.
+It will also describe the way of handling the relation wrt locking and
+refcounting.
+
1) parent-child relation
+---------+ +-------+
index c28b0246f85da1d5b5100f86c2294184b4e5cc89..27eac4cd23f628431d3c33a989e7adadc48bb463 100644 (file)
Strings:
Arguments passed into a function are owned by the caller, and the function will make a copy of the string for its own
-internal use. The string should be const gchar *. Strings returned from a function remain the property of the
-function called, and the caller must make a copy if it is to use the string for an extended duration.
+internal use. The string should be const gchar *. Strings returned from a function are always a copy of the
+original and should be freed after usage by the caller.
Objects:
-The ownership of an object during a function call depends on the type of function. If the function is simply returning
-something from the object, such as _get_name(), the caller retains ownership. If the object passed is to be
-manipulated in some way, it is generally the case that the function will take over the ownership. This should be
-expressed as a reference increment on that object, but isn't in the general case (yet).
diff --git a/gst/gstbin.c b/gst/gstbin.c
index 12d519dfb073f5b7e31ba817d60cea7b10c1870a..9bd330179e58d6c0a233c7e95e826888480d273e 100644 (file)
--- a/gst/gstbin.c
+++ b/gst/gstbin.c
/* ERROR handling here */
adding_itself:
- GST_LOCK (bin);
- g_warning ("Cannot add bin %s to itself", GST_ELEMENT_NAME (bin));
- GST_UNLOCK (bin);
- return FALSE;
-
+ {
+ GST_LOCK (bin);
+ g_warning ("Cannot add bin %s to itself", GST_ELEMENT_NAME (bin));
+ GST_UNLOCK (bin);
+ return FALSE;
+ }
duplicate_name:
- g_warning ("Name %s is not unique in bin %s, not adding",
- elem_name, GST_ELEMENT_NAME (bin));
- GST_UNLOCK (bin);
- g_free (elem_name);
- return FALSE;
-
+ {
+ g_warning ("Name %s is not unique in bin %s, not adding",
+ elem_name, GST_ELEMENT_NAME (bin));
+ GST_UNLOCK (bin);
+ g_free (elem_name);
+ return FALSE;
+ }
had_parent:
- g_warning ("Element %s already has parent", elem_name);
- GST_UNLOCK (bin);
- g_free (elem_name);
- return FALSE;
+ {
+ g_warning ("Element %s already has parent", elem_name);
+ GST_UNLOCK (bin);
+ g_free (elem_name);
+ return FALSE;
+ }
}
/**
return result;
+ /* ERROR handling */
no_function:
- g_warning ("adding elements to bin %s is not supported",
- GST_ELEMENT_NAME (bin));
- return FALSE;
+ {
+ g_warning ("adding elements to bin %s is not supported",
+ GST_ELEMENT_NAME (bin));
+ return FALSE;
+ }
}
/* remove an element from the bin
return TRUE;
+ /* ERROR handling */
not_in_bin:
- g_warning ("Element %s is not in bin %s", elem_name, GST_ELEMENT_NAME (bin));
- GST_UNLOCK (bin);
- g_free (elem_name);
- return FALSE;
+ {
+ g_warning ("Element %s is not in bin %s", elem_name,
+ GST_ELEMENT_NAME (bin));
+ GST_UNLOCK (bin);
+ g_free (elem_name);
+ return FALSE;
+ }
}
/**
return result;
+ /* ERROR handling */
no_function:
- g_warning ("removing elements from bin %s is not supported",
- GST_ELEMENT_NAME (bin));
- return FALSE;
+ {
+ g_warning ("removing elements from bin %s is not supported",
+ GST_ELEMENT_NAME (bin));
+ return FALSE;
+ }
}
static GstIteratorItem
GST_UNLOCK (bin);
return result;
- return NULL;
}
-
/**
* gst_bin_child_state_change:
* @bin: #GstBin with the child
children = gst_bin_iterate_recurse (bin);
result = gst_iterator_find_custom (children,
(GCompareFunc) compare_name, (gpointer) name);
+ gst_iterator_free (children);
return GST_ELEMENT_CAST (result);
}
children = gst_bin_iterate_recurse (bin);
result = gst_iterator_find_custom (children, (GCompareFunc) compare_interface,
GINT_TO_POINTER (interface));
+ gst_iterator_free (children);
return GST_ELEMENT_CAST (result);
}
children = gst_bin_iterate_recurse (bin);
result = gst_iterator_filter (children, (GCompareFunc) compare_interface,
GINT_TO_POINTER (interface));
+ gst_iterator_free (children);
return result;
}
diff --git a/gst/gstbuffer.h b/gst/gstbuffer.h
index ed2f932d452bb8d40146402beb4d036a650cdfb0..c30af9577f76b53b37891a150f4b47ebbae0947c 100644 (file)
--- a/gst/gstbuffer.h
+++ b/gst/gstbuffer.h
* @GST_BUFFER_ORIGINAL: buffer is not a copy of another buffer.
* @GST_BUFFER_DONTFREE: do not try to free the data when this buffer is
* unreferenced.
- * @GST_BUFFER_KEY_UNIT: the buffer holds a key unit, a unit that can be
- * decoded independently of other buffers.
- * This flag has been deprecated, see #GST_BUFFER_DELTA_UNIT.
- * @GST_BUFFER_DONTKEEP: the buffer should not be ref()ed, but copied instead
- * before doing anything with it (for specially allocated hw buffers and such)
+ * @GST_BUFFER_PREROLL: the buffer is part of a preroll and should not be
+ * displayed.
+ * @GST_BUFFER_DISCONT: the buffer marks a discontinuity in the stream.
* @GST_BUFFER_IN_CAPS: the buffer has been added as a field in a #GstCaps.
* @GST_BUFFER_GAP: the buffer has been created to fill a gap in the stream.
* @GST_BUFFER_DELTA_UNIT: this unit cannot be decoded independently.
diff --git a/gst/gstclock.h b/gst/gstclock.h
index 41a6b001c0a7bd38a798f59e193162004b80c19c..264d419d1f567c0effa372195cbb270693fcc3a4 100644 (file)
--- a/gst/gstclock.h
+++ b/gst/gstclock.h
#define GST_TIME_TO_TIMESPEC(t,ts) \
G_STMT_START { \
(ts).tv_sec = (t) / GST_SECOND; \
- (ts).tv_usec = ((t) - (ts).tv_sec * GST_SECOND) / GST_NSECOND; \
+ (ts).tv_nsec = ((t) - (ts).tv_sec * GST_SECOND) / GST_NSECOND; \
} G_STMT_END
/* timestamp debugging macros */
diff --git a/gst/gstelement.c b/gst/gstelement.c
index dd6a6d89e7366cbe54b724f48b1a9f19f1e1f5c6..92b59c30a916beb08477b46ce9709603d0c7f81a 100644 (file)
--- a/gst/gstelement.c
+++ b/gst/gstelement.c
parent_class = g_type_class_ref (GST_TYPE_OBJECT);
/**
- * GstElement::state-change:
+ * GstElement::state-change:
* @gstelement: the object which received the signal
* @int:
* @int:
- *
- * the #GstElementState of the element has been changed
- */
+ *
+ * the #GstElementState of the element has been changed
+ */
gst_element_signals[STATE_CHANGE] =
g_signal_new ("state-change", G_TYPE_FROM_CLASS (klass),
G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstElementClass, state_change), NULL,
NULL, gst_marshal_VOID__INT_INT, G_TYPE_NONE, 2, G_TYPE_INT, G_TYPE_INT);
/**
- * GstElement::new-pad:
+ * GstElement::new-pad:
* @gstelement: the object which received the signal
* @object:
- *
- * a new #GstPad has been added to the element
- */
+ *
+ * a new #GstPad has been added to the element
+ */
gst_element_signals[NEW_PAD] =
g_signal_new ("new-pad", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
G_STRUCT_OFFSET (GstElementClass, new_pad), NULL, NULL,
gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, G_TYPE_OBJECT);
/**
- * GstElement::pad-removed:
+ * GstElement::pad-removed:
* @gstelement: the object which received the signal
* @object:
- *
- * a #GstPad has been removed from the element
- */
+ *
+ * a #GstPad has been removed from the element
+ */
gst_element_signals[PAD_REMOVED] =
g_signal_new ("pad-removed", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
G_STRUCT_OFFSET (GstElementClass, pad_removed), NULL, NULL,
gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, G_TYPE_OBJECT);
/**
- * GstElement::error:
+ * GstElement::error:
* @gstelement: the object which received the signal
* @element:
* @error:
* @message:
- *
- * a #GstError has occured during data processing
- */
+ *
+ * a #GstError has occured during data processing
+ */
gst_element_signals[ERROR] =
g_signal_new ("error", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
G_STRUCT_OFFSET (GstElementClass, error), NULL, NULL,
gst_marshal_VOID__OBJECT_BOXED_STRING, G_TYPE_NONE, 3, GST_TYPE_ELEMENT,
GST_TYPE_G_ERROR, G_TYPE_STRING);
/**
- * GstElement::eos:
+ * GstElement::eos:
* @gstelement: the object which received the signal
- *
- * the end of the stream has been reached
- */
+ *
+ * the end of the stream has been reached
+ */
gst_element_signals[EOS] =
g_signal_new ("eos", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
G_STRUCT_OFFSET (GstElementClass, eos), NULL, NULL,
gst_marshal_VOID__VOID, G_TYPE_NONE, 0);
/**
- * GstElement::found-tag:
+ * GstElement::found-tag:
* @gstelement: the object which received the signal
* @element:
* @tags:
- *
- * tags for the incomming stream have been received
- */
+ *
+ * tags for the incomming stream have been received
+ */
gst_element_signals[FOUND_TAG] =
g_signal_new ("found-tag", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
G_STRUCT_OFFSET (GstElementClass, found_tag), NULL, NULL,
gst_marshal_VOID__OBJECT_BOXED, G_TYPE_NONE, 2, GST_TYPE_ELEMENT,
GST_TYPE_TAG_LIST);
/**
- * GstElement::no-more-pads:
+ * GstElement::no-more-pads:
* @gstelement: the object which received the signal
- *
- * ?
- */
+ *
+ * ?
+ */
gst_element_signals[NO_MORE_PADS] =
g_signal_new ("no-more-pads", G_TYPE_FROM_CLASS (klass),
G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstElementClass, no_more_pads), NULL,
return NULL;
}
-/**
- * gst_element_get_pad_template_list:
- * @element: a #GstElement to get pad templates of.
- *
- * Retrieves a list of the pad templates associated with the element.
- * (FIXME: Should be deprecated in favor of
- * gst_element_class_get_pad_template_list).
- *
- * Returns: the #GList of padtemplates.
- */
-GList *
-gst_element_get_pad_template_list (GstElement * element)
-{
- g_return_val_if_fail (element != NULL, NULL);
- g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
-
- return GST_ELEMENT_GET_CLASS (element)->padtemplates;
-}
-
-/**
- * gst_element_get_pad_template:
- * @element: a #GstElement to get the pad template of.
- * @name: the name of the #GstPadTemplate to get.
- *
- * Retrieves a padtemplate from this element with the
- * given name.
- * (FIXME: Should be deprecated in favor of gst_element_class_get_pad_template).
- *
- * Returns: the #GstPadTemplate with the given name, or NULL if none was found.
- * No unreferencing is necessary.
- */
-GstPadTemplate *
-gst_element_get_pad_template (GstElement * element, const gchar * name)
-{
- g_return_val_if_fail (element != NULL, NULL);
- g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
- g_return_val_if_fail (name != NULL, NULL);
-
- return gst_element_class_get_pad_template (GST_ELEMENT_GET_CLASS (element),
- name);
-}
-
static void
gst_element_error_func (GstElement * element, GstElement * source,
GError * error, gchar * debug)
diff --git a/gst/gstelement.h b/gst/gstelement.h
index f6621edf0fb3322820f66c37eeab4d809b1049d9..11305664c6b536780de2638dd3fbef5c94420245 100644 (file)
--- a/gst/gstelement.h
+++ b/gst/gstelement.h
gpointer _gst_reserved[GST_PADDING - 1];
};
+GType gst_element_get_type (void);
+
+/* element class pad templates */
void gst_element_class_add_pad_template (GstElementClass *klass, GstPadTemplate *templ);
-void gst_element_class_install_std_props (GstElementClass *klass,
- const gchar *first_name, ...);
+GstPadTemplate* gst_element_class_get_pad_template (GstElementClass *element_class, const gchar *name);
+GList* gst_element_class_get_pad_template_list (GstElementClass *element_class);
+
+/* element class details */
void gst_element_class_set_details (GstElementClass *klass,
const GstElementDetails *details);
void gst_element_default_error (GObject *object, GstObject *orig, GError *error, gchar *debug);
-GType gst_element_get_type (void);
void gst_element_set_loop_function (GstElement *element,
GstElementLoopFunction loop);
GstPad* gst_element_get_request_pad (GstElement *element, const gchar *name);
void gst_element_release_request_pad (GstElement *element, GstPad *pad);
-GstIterator *gst_element_iterate_pads (GstElement * element);
-
-GstPad* gst_element_get_compatible_pad (GstElement *element, GstPad *pad);
-GstPad* gst_element_get_compatible_pad_filtered (GstElement *element, GstPad *pad,
- const GstCaps *filtercaps);
-
-GstPadTemplate* gst_element_class_get_pad_template (GstElementClass *element_class, const gchar *name);
-GList* gst_element_class_get_pad_template_list (GstElementClass *element_class);
-GstPadTemplate* gst_element_get_pad_template (GstElement *element, const gchar *name);
-GList* gst_element_get_pad_template_list (GstElement *element);
-GstPadTemplate* gst_element_get_compatible_pad_template (GstElement *element, GstPadTemplate *compattempl);
-
-gboolean gst_element_link (GstElement *src, GstElement *dest);
-gboolean gst_element_link_many (GstElement *element_1,
- GstElement *element_2, ...);
-gboolean gst_element_link_filtered (GstElement *src, GstElement *dest,
- const GstCaps *filtercaps);
-void gst_element_unlink (GstElement *src, GstElement *dest);
-void gst_element_unlink_many (GstElement *element_1,
- GstElement *element_2, ...);
-
-gboolean gst_element_link_pads (GstElement *src, const gchar *srcpadname,
- GstElement *dest, const gchar *destpadname);
-gboolean gst_element_link_pads_filtered (GstElement *src, const gchar *srcpadname,
- GstElement *dest, const gchar *destpadname,
- const GstCaps *filtercaps);
-void gst_element_unlink_pads (GstElement *src, const gchar *srcpadname,
- GstElement *dest, const gchar *destpadname);
+GstIterator * gst_element_iterate_pads (GstElement * element);
G_CONST_RETURN GstEventMask*
gst_element_get_event_masks (GstElement *element);
void gst_element_wait_state_change (GstElement *element);
-G_CONST_RETURN gchar* gst_element_state_get_name (GstElementState state);
-
GstElementFactory* gst_element_get_factory (GstElement *element);
GstBin* gst_element_get_managing_bin (GstElement *element);
diff --git a/gst/gstiterator.c b/gst/gstiterator.c
index 0091e15b54cdafcd9946c4466d7f24d07331e509..ac912f0e1527ecb36ec5615af6be31c785c1296c 100644 (file)
--- a/gst/gstiterator.c
+++ b/gst/gstiterator.c
*
* Create a new iterator. This function is mainly used for objects
* implementing the next/resync/free function to iterate a data structure.
+ *
+ * For each item retrieved, the @item function is called with the lock
+ * held. The @free function is called when the iterator is freed.
*
* Returns: the new #GstIterator.
*
* @master_cookie: pointer to a guint32 to protect the list.
* @list: pointer to the list
* @owner: object owning the list
- * @ref: function to ref each item
- * @unref: function to unref each item
- * @free: function to free the owner of the list
+ * @item: function to call for each item
+ * @free: function to call when the iterator is freed
*
* Create a new iterator designed for iterating @list.
*
diff --git a/gst/gstobject.c b/gst/gstobject.c
index d2d5b964fc7e0e2ccf2ef49a5aee6710759252f9..282b6febb19dddf8a130e5c9d2755bcc578a86da 100644 (file)
--- a/gst/gstobject.c
+++ b/gst/gstobject.c
* creating a new object to symbolically 'take ownership' of the object.
* Use #gst_object_set_parent to have this done for you.
*
- * This function takes the object lock.
- *
- * MT safe.
+ * MT safe. This function grabs and releases the object lock.
*/
void
gst_object_sink (GstObject * object)
* function, it does not take any locks. You might want to lock
* the object owning the oldobj pointer before calling this
* function.
+ *
+ * Make sure not to LOCK the oldobj because it might be unreffed
+ * which could cause a deadlock when it is disposed.
*/
void
gst_object_replace (GstObject ** oldobj, GstObject * newobj)
* @excluded_props: a set of user-specified properties to exclude or
* NULL to show all changes.
*
- * Adds a default deep_notify signal callback to an
- * element. The user data should contain a pointer to an array of
- * strings that should be excluded from the notify.
- * The default handler will print the new value of the property
+ * A default deep_notify signal callback for an element. The user data
+ * should contain a pointer to an array of strings that should be excluded
+ * from the notify. The default handler will print the new value of the property
* using g_print.
*
- * MT safe.
+ * MT safe. This function grabs and releases the object's LOCK or getting the
+ * path string of the object.
*/
void
gst_object_default_deep_notify (GObject * object, GstObject * orig,
*
* Returns: the name of the object. g_free() after usage.
*
- * MT safe.
+ * MT safe. This function grabs and releases the object's LOCK.
*/
gchar *
gst_object_get_name (GstObject * object)
*
* Returns: the name prefix of the object. g_free() after usage.
*
- * MT safe.
+ * MT safe. This function grabs and releases the object's LOCK.
*/
gchar *
gst_object_get_name_prefix (GstObject * object)
* Sets the parent of @object. The object's reference count will be incremented,
* and any floating reference will be removed (see gst_object_sink()).
*
- * This function takes the object lock.
- *
* Causes the parent-set signal to be emitted.
*
* Returns: TRUE if the parent could be set or FALSE when the object
* already had a parent, the object and parent are the same or wrong
* parameters were provided.
*
- * MT safe.
+ * MT safe. Grabs and releases the object's LOCK.
*/
gboolean
gst_object_set_parent (GstObject * object, GstObject * parent)
}
g_signal_emit (G_OBJECT (object), gst_object_signals[PARENT_SET], 0, parent);
+
return TRUE;
- /* ERROR */
+ /* ERROR handling */
had_parent:
{
GST_UNLOCK (object);
* Returns: parent of the object, this can be NULL if the object has no
* parent. unref after usage.
*
- * MT safe.
+ * MT safe. Grabs and releases the object's LOCK.
*/
GstObject *
gst_object_get_parent (GstObject * object)
* This function decreases the refcount of the object so the object
* might not point to valid memory anymore after calling this function.
*
- * MT safe.
+ * MT safe. Grabs and releases the object's lock.
*/
void
gst_object_unparent (GstObject * object)
*
* Returns: TRUE if the name does not appear in the list, FALSE if it does.
*
- * MT safe.
+ * MT safe. Grabs and releases the LOCK of each object in the list.
*/
gboolean
gst_object_check_uniqueness (GList * list, const gchar * name)
* Returns: a string describing the path of the object. You must
* g_free() the string after usage.
*
- * MT safe.
+ * MT safe. Grabs and releases the object's LOCK for all objects
+ * in the hierarchy.
*/
gchar *
gst_object_get_path_string (GstObject * object)
diff --git a/gst/gstobject.h b/gst/gstobject.h
index d3be094d835b52d0f6599bb12b6df033e107f48a..034a02e0295f8e09621592856cc640233da59cc2 100644 (file)
--- a/gst/gstobject.h
+++ b/gst/gstobject.h
* Boston, MA 02111-1307, USA.
*/
-
#ifndef __GST_OBJECT_H__
#define __GST_OBJECT_H__
#define GST_FLAG_SET(obj,flag) G_STMT_START{ (GST_FLAGS (obj) |= (1<<(flag))); }G_STMT_END
#define GST_FLAG_UNSET(obj,flag) G_STMT_START{ (GST_FLAGS (obj) &= ~(1<<(flag))); }G_STMT_END
+#define GST_OBJECT_IS_DISPOSING(obj) (GST_FLAG_IS_SET (obj, GST_OBJECT_DISPOSING))
#define GST_OBJECT_IS_DESTROYED(obj) (GST_FLAG_IS_SET (obj, GST_OBJECT_DESTROYED))
#define GST_OBJECT_IS_FLOATING(obj) (GST_FLAG_IS_SET (obj, GST_OBJECT_FLOATING))
/*< public >*/ /* with LOCK */
GMutex *lock; /* object LOCK */
gchar *name; /* object name */
+ gchar *name_prefix; /* used for debugging */
GstObject *parent; /* this object's parent, weak ref */
guint32 flags;
- gchar *name_prefix; /* used for debugging */
/*< private >*/
gpointer _gst_reserved[GST_PADDING];