+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:
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
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
===================
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.
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
+---------+ +-------+
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).
/* 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;
}
* @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.
#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 */
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)
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);
*
* 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.
*
* 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)
* 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];
projects / platform / upstream / gstreamer.git / commitdiff