![]() |
![]() |
![]() |
GStreamer 1.0 Core Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#include <gst/gst.h> struct GstMiniObject; GstMiniObject * (*GstMiniObjectCopyFunction) (const GstMiniObject *obj
); gboolean (*GstMiniObjectDisposeFunction) (GstMiniObject *obj
); void (*GstMiniObjectFreeFunction) (GstMiniObject *obj
); void (*GstMiniObjectNotify) (gpointer user_data
,GstMiniObject *obj
); #define GST_MINI_OBJECT_TYPE (obj) enum GstMiniObjectFlags; #define GST_MINI_OBJECT_FLAGS (obj) #define GST_MINI_OBJECT_FLAG_IS_SET (obj, flag) #define GST_MINI_OBJECT_FLAG_SET (obj, flag) #define GST_MINI_OBJECT_FLAG_UNSET (obj, flag) #define GST_MINI_OBJECT_IS_LOCKABLE (obj) enum GstLockFlags; #define GST_LOCK_FLAG_READWRITE #define GST_MINI_OBJECT_REFCOUNT (obj) #define GST_MINI_OBJECT_REFCOUNT_VALUE (obj) #define GST_DEFINE_MINI_OBJECT_TYPE (TypeName, type_name) void gst_mini_object_init (GstMiniObject *mini_object
,guint flags
,GType type
,GstMiniObjectCopyFunction copy_func
,GstMiniObjectDisposeFunction dispose_func
,GstMiniObjectFreeFunction free_func
); GstMiniObject * gst_mini_object_ref (GstMiniObject *mini_object
); void gst_mini_object_unref (GstMiniObject *mini_object
); void gst_mini_object_weak_ref (GstMiniObject *object
,GstMiniObjectNotify notify
,gpointer data
); void gst_mini_object_weak_unref (GstMiniObject *object
,GstMiniObjectNotify notify
,gpointer data
); gboolean gst_mini_object_lock (GstMiniObject *object
,GstLockFlags flags
); void gst_mini_object_unlock (GstMiniObject *object
,GstLockFlags flags
); gboolean gst_mini_object_is_writable (const GstMiniObject *mini_object
); GstMiniObject * gst_mini_object_make_writable (GstMiniObject *mini_object
); GstMiniObject * gst_mini_object_copy (const GstMiniObject *mini_object
); void gst_mini_object_set_qdata (GstMiniObject *object
,GQuark quark
,gpointer data
,GDestroyNotify destroy
); gpointer gst_mini_object_get_qdata (GstMiniObject *object
,GQuark quark
); gpointer gst_mini_object_steal_qdata (GstMiniObject *object
,GQuark quark
); gboolean gst_mini_object_replace (GstMiniObject **olddata
,GstMiniObject *newdata
); gboolean gst_mini_object_take (GstMiniObject **olddata
,GstMiniObject *newdata
); GstMiniObject * gst_mini_object_steal (GstMiniObject **olddata
);
GstMiniObject is a simple structure that can be used to implement refcounted types.
Subclasses will include GstMiniObject as the first member in their structure
and then call gst_mini_object_init()
to initialize the GstMiniObject fields.
gst_mini_object_ref()
and gst_mini_object_unref()
increment and decrement the
refcount respectively. When the refcount of a mini-object reaches 0, the
dispose function is called first and when this returns TRUE
, the free
function of the miniobject is called.
A copy can be made with gst_mini_object_copy()
.
gst_mini_object_is_writable()
will return TRUE
when the refcount of the
object is exactly 1, meaning the current caller has the only reference to the
object. gst_mini_object_make_writable()
will return a writable version of the
object, which might be a new copy when the refcount was not 1.
Opaque data can be associated with a GstMiniObject with
gst_mini_object_set_qdata()
and gst_mini_object_get_qdata()
. The data is
meant to be specific to the particular object and is not automatically copied
with gst_mini_object_copy()
or similar methods.
A weak reference can be added and remove with gst_mini_object_weak_ref()
and gst_mini_object_weak_unref()
respectively.
Last reviewed on 2012-06-15 (0.11.93)
struct GstMiniObject { GType type; gint refcount; gint lockstate; guint flags; GstMiniObjectCopyFunction copy; GstMiniObjectDisposeFunction dispose; GstMiniObjectFreeFunction free; };
Base class for refcounted lightweight objects. Ref Func: gst_mini_object_ref Unref Func: gst_mini_object_unref Set Value Func: g_value_set_boxed Get Value Func: g_value_get_boxed
the GType of the object | |
atomic refcount | |
atomic state of the locks | |
extra flags. | |
a copy function | |
GstMiniObjectDisposeFunction |
a dispose function |
the free function |
GstMiniObject * (*GstMiniObjectCopyFunction) (const GstMiniObject *obj
);
Function prototype for methods to create copies of instances.
|
MiniObject to copy |
Returns : |
reference to cloned instance. |
gboolean (*GstMiniObjectDisposeFunction) (GstMiniObject *obj
);
Function prototype for when a miniobject has lost its last refcount.
Implementation of the mini object are allowed to revive the
passed object by doing a gst_mini_object_ref()
. If the object is not
revived after the dispose function, the function should return TRUE
and the memory associated with the object is freed.
|
MiniObject to dispose |
Returns : |
TRUE if the object should be cleaned up. |
void (*GstMiniObjectFreeFunction) (GstMiniObject *obj
);
Virtual function prototype for methods to free ressources used by mini-objects.
|
MiniObject to free |
void (*GstMiniObjectNotify) (gpointer user_data
,GstMiniObject *obj
);
A GstMiniObjectNotify function can be added to a mini object as a
callback that gets triggered when gst_mini_object_unref()
drops the
last ref and obj
is about to be freed.
|
data that was provided when the notify was added |
|
the mini object |
#define GST_MINI_OBJECT_TYPE(obj) (GST_MINI_OBJECT_CAST(obj)->type)
This macro returns the type of the mini-object.
|
MiniObject to return type for. |
typedef enum { GST_MINI_OBJECT_FLAG_LOCKABLE = (1 << 0), GST_MINI_OBJECT_FLAG_LOCK_READONLY = (1 << 1), /* padding */ GST_MINI_OBJECT_FLAG_LAST = (1 << 4) } GstMiniObjectFlags;
Flags for the mini object
the object can be locked and unlocked with
gst_mini_object_lock() and gst_mini_object_unlock() .
|
|
the object is permanently locked in READONLY mode. Only read locks can be performed on the object. | |
first flag that can be used by subclasses. |
#define GST_MINI_OBJECT_FLAGS(obj) (GST_MINI_OBJECT_CAST(obj)->flags)
This macro returns the entire set of flags for the mini-object.
|
MiniObject to return flags for. |
#define GST_MINI_OBJECT_FLAG_IS_SET(obj,flag) !!(GST_MINI_OBJECT_FLAGS (obj) & (flag))
This macro checks to see if the given flag is set.
|
MiniObject to check for flags. |
|
Flag to check for |
#define GST_MINI_OBJECT_FLAG_SET(obj,flag) (GST_MINI_OBJECT_FLAGS (obj) |= (flag))
This macro sets the given bits.
|
MiniObject to set flag in. |
|
Flag to set, can by any number of bits in guint32. |
#define GST_MINI_OBJECT_FLAG_UNSET(obj,flag) (GST_MINI_OBJECT_FLAGS (obj) &= ~(flag))
This macro usets the given bits.
|
MiniObject to unset flag in. |
|
Flag to set, must be a single bit in guint32. |
#define GST_MINI_OBJECT_IS_LOCKABLE(obj) GST_MINI_OBJECT_FLAG_IS_SET(obj, GST_MINI_OBJECT_FLAG_LOCKABLE)
Check if obj
is lockable. A lockable object can be locked and unlocked with
gst_mini_object_lock()
and gst_mini_object_unlock()
.
|
a GstMiniObject |
typedef enum { GST_LOCK_FLAG_READ = (1 << 0), GST_LOCK_FLAG_WRITE = (1 << 1), GST_LOCK_FLAG_EXCLUSIVE = (1 << 2), GST_LOCK_FLAG_LAST = (1 << 8) } GstLockFlags;
Flags used when locking miniobjects
#define GST_LOCK_FLAG_READWRITE (GST_LOCK_FLAG_READ | GST_LOCK_FLAG_WRITE)
GstLockFlags value alias for GST_LOCK_FLAG_READ | GST_LOCK_FLAG_WRITE
#define GST_MINI_OBJECT_REFCOUNT(obj) ((GST_MINI_OBJECT_CAST(obj))->refcount)
Get access to the reference count field of the mini-object.
|
a GstMiniObject |
#define GST_MINI_OBJECT_REFCOUNT_VALUE(obj) (g_atomic_int_get (&(GST_MINI_OBJECT_CAST(obj))->refcount))
Get the reference count value of the mini-object.
|
a GstMiniObject |
#define GST_DEFINE_MINI_OBJECT_TYPE(TypeName,type_name)
Define a new mini-object type with the given name
|
name of the new type in CamelCase |
|
name of the new type |
void gst_mini_object_init (GstMiniObject *mini_object
,guint flags
,GType type
,GstMiniObjectCopyFunction copy_func
,GstMiniObjectDisposeFunction dispose_func
,GstMiniObjectFreeFunction free_func
);
Initializes a mini-object with the desired type and copy/dispose/free functions.
|
a GstMiniObject |
|
initial GstMiniObjectFlags |
|
the GType of the mini-object to create |
|
the copy function, or NULL. [allow-none] |
|
the dispose function, or NULL. [allow-none] |
|
the free function or NULL. [allow-none] |
GstMiniObject * gst_mini_object_ref (GstMiniObject *mini_object
);
Increase the reference count of the mini-object.
Note that the refcount affects the writeability
of mini
-object, see gst_mini_object_is_writable()
. It is
important to note that keeping additional references to
GstMiniObject instances can potentially increase the number
of memcpy operations in a pipeline, especially if the miniobject
is a GstBuffer.
|
the mini-object |
Returns : |
the mini-object. [transfer full] |
void gst_mini_object_unref (GstMiniObject *mini_object
);
Decreases the reference count of the mini-object, possibly freeing the mini-object.
|
the mini-object |
void gst_mini_object_weak_ref (GstMiniObject *object
,GstMiniObjectNotify notify
,gpointer data
);
Adds a weak reference callback to a mini object. Weak references are
used for notification when a mini object is finalized. They are called
"weak references" because they allow you to safely hold a pointer
to the mini object without calling gst_mini_object_ref()
(gst_mini_object_ref()
adds a strong reference, that is, forces the object
to stay alive).
|
GstMiniObject to reference weakly |
|
callback to invoke before the mini object is freed |
|
extra data to pass to notify |
void gst_mini_object_weak_unref (GstMiniObject *object
,GstMiniObjectNotify notify
,gpointer data
);
Removes a weak reference callback from a mini object.
|
GstMiniObject to remove a weak reference from |
|
callback to search for |
|
data to search for |
gboolean gst_mini_object_lock (GstMiniObject *object
,GstLockFlags flags
);
Lock the mini-object with the specified access mode in flags
.
|
the mini-object to lock |
|
GstLockFlags |
Returns : |
TRUE if object could be locked. |
void gst_mini_object_unlock (GstMiniObject *object
,GstLockFlags flags
);
Unlock the mini-object with the specified access mode in flags
.
|
the mini-object to unlock |
|
GstLockFlags |
gboolean gst_mini_object_is_writable (const GstMiniObject *mini_object
);
If mini_object
has the LOCKABLE flag set, check if the current EXCLUSIVE
lock on object
is the only one, this means that changes to the object will
not be visible to any other object.
If the LOCKABLE flag is not set, check if the refcount of mini_object
is
exactly 1, meaning that no other reference exists to the object and that the
object is therefore writable.
Modification of a mini-object should only be done after verifying that it is writable.
|
the mini-object to check |
Returns : |
TRUE if the object is writable. |
GstMiniObject * gst_mini_object_make_writable (GstMiniObject *mini_object
);
Checks if a mini-object is writable. If not, a writable copy is made and returned. This gives away the reference to the original mini object, and returns a reference to the new object.
MT safe
|
the mini-object to make writable. [transfer full] |
Returns : |
a mini-object (possibly the same pointer) that is writable. [transfer full] |
GstMiniObject * gst_mini_object_copy (const GstMiniObject *mini_object
);
Creates a copy of the mini-object.
MT safe
|
the mini-object to copy |
Returns : |
the new mini-object. [transfer full] |
void gst_mini_object_set_qdata (GstMiniObject *object
,GQuark quark
,gpointer data
,GDestroyNotify destroy
);
This sets an opaque, named pointer on a miniobject.
The name is specified through a GQuark (retrived e.g. via
g_quark_from_static_string()
), and the pointer
can be gotten back from the object
with gst_mini_object_get_qdata()
until the object
is disposed.
Setting a previously set user data pointer, overrides (frees)
the old pointer set, using NULL as pointer essentially
removes the data stored.
destroy
may be specified which is called with data
as argument
when the object
is disposed, or the data is being overwritten by
a call to gst_mini_object_set_qdata()
with the same quark
.
|
a GstMiniObject |
|
A GQuark, naming the user data pointer |
|
An opaque user data pointer |
|
Function to invoke with data as argument, when data
needs to be freed |
gpointer gst_mini_object_get_qdata (GstMiniObject *object
,GQuark quark
);
This function gets back user data pointers stored via
gst_mini_object_set_qdata()
.
|
The GstMiniObject to get a stored user data pointer from |
|
A GQuark, naming the user data pointer |
Returns : |
The user data pointer set, or NULL . [transfer none]
|
gpointer gst_mini_object_steal_qdata (GstMiniObject *object
,GQuark quark
);
This function gets back user data pointers stored via gst_mini_object_set_qdata()
and removes the data from object
without invoking its destroy()
function (if
any was set).
|
The GstMiniObject to get a stored user data pointer from |
|
A GQuark, naming the user data pointer |
Returns : |
The user data pointer set, or NULL . [transfer full]
|
gboolean gst_mini_object_replace (GstMiniObject **olddata
,GstMiniObject *newdata
);
Atomically modifies a pointer to point to a new mini-object.
The reference count of olddata
is decreased and the reference count of
newdata
is increased.
Either newdata
and the value pointed to by olddata
may be NULL.
|
pointer to a pointer to a mini-object to be replaced. [inout][transfer full] |
|
pointer to new mini-object |
Returns : |
TRUE if newdata was different from olddata
|
gboolean gst_mini_object_take (GstMiniObject **olddata
,GstMiniObject *newdata
);
Modifies a pointer to point to a new mini-object. The modification
is done atomically. This version is similar to gst_mini_object_replace()
except that it does not increase the refcount of newdata
and thus
takes ownership of newdata
.
Either newdata
and the value pointed to by olddata
may be NULL.
|
pointer to a pointer to a mini-object to be replaced. [inout][transfer full] |
|
pointer to new mini-object |
Returns : |
TRUE if newdata was different from olddata
|
GstMiniObject * gst_mini_object_steal (GstMiniObject **olddata
);
Replace the current GstMiniObject pointer to by olddata
with NULL and
return the old value.
|
pointer to a pointer to a mini-object to be stolen. [inout][transfer full] |
Returns : |
the GstMiniObject at oldata
|