Top |
Functions
Types and Values
struct | GstMiniObject |
enum | GstMiniObjectFlags |
enum | GstLockFlags |
#define | GST_LOCK_FLAG_READWRITE |
Description
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.
Functions
GstMiniObjectCopyFunction ()
GstMiniObject *
(*GstMiniObjectCopyFunction) (const GstMiniObject *obj
);
Function prototype for methods to create copies of instances.
GstMiniObjectDisposeFunction ()
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.
GstMiniObjectFreeFunction ()
void
(*GstMiniObjectFreeFunction) (GstMiniObject *obj
);
Virtual function prototype for methods to free resources used by mini-objects.
GstMiniObjectNotify ()
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.
GST_MINI_OBJECT_TYPE()
#define GST_MINI_OBJECT_TYPE(obj) (GST_MINI_OBJECT_CAST(obj)->type)
This macro returns the type of the mini-object.
GST_MINI_OBJECT_FLAGS()
#define GST_MINI_OBJECT_FLAGS(obj) (GST_MINI_OBJECT_CAST(obj)->flags)
This macro returns the entire set of flags for the mini-object.
GST_MINI_OBJECT_FLAG_IS_SET()
#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.
GST_MINI_OBJECT_FLAG_SET()
#define GST_MINI_OBJECT_FLAG_SET(obj,flag) (GST_MINI_OBJECT_FLAGS (obj) |= (flag))
This macro sets the given bits.
GST_MINI_OBJECT_FLAG_UNSET()
#define GST_MINI_OBJECT_FLAG_UNSET(obj,flag) (GST_MINI_OBJECT_FLAGS (obj) &= ~(flag))
This macro unsets the given bits.
GST_MINI_OBJECT_IS_LOCKABLE()
#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()
.
GST_MINI_OBJECT_REFCOUNT()
#define GST_MINI_OBJECT_REFCOUNT(obj) ((GST_MINI_OBJECT_CAST(obj))->refcount)
Get access to the reference count field of the mini-object.
GST_MINI_OBJECT_REFCOUNT_VALUE()
#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.
GST_DEFINE_MINI_OBJECT_TYPE()
#define GST_DEFINE_MINI_OBJECT_TYPE(TypeName,type_name)
Define a new mini-object type with the given name
gst_mini_object_init ()
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.
[skip]
Parameters
mini_object |
||
flags |
initial GstMiniObjectFlags |
|
type |
the GType of the mini-object to create |
|
copy_func |
the copy function, or |
[allow-none] |
dispose_func |
the dispose function, or |
[allow-none] |
free_func |
the free function or |
[allow-none] |
gst_mini_object_ref ()
GstMiniObject *
gst_mini_object_ref (GstMiniObject *mini_object
);
Increase the reference count of the mini-object.
Note that the refcount affects the writability
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.
[skip]
gst_mini_object_unref ()
void
gst_mini_object_unref (GstMiniObject *mini_object
);
Decreases the reference count of the mini-object, possibly freeing the mini-object.
[skip]
gst_mini_object_weak_ref ()
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).
[skip]
Parameters
object |
GstMiniObject to reference weakly |
|
notify |
callback to invoke before the mini object is freed |
|
data |
extra data to pass to notify |
gst_mini_object_weak_unref ()
void gst_mini_object_weak_unref (GstMiniObject *object
,GstMiniObjectNotify notify
,gpointer data
);
Removes a weak reference callback from a mini object.
[skip]
Parameters
object |
GstMiniObject to remove a weak reference from |
|
notify |
callback to search for |
|
data |
data to search for |
gst_mini_object_lock ()
gboolean gst_mini_object_lock (GstMiniObject *object
,GstLockFlags flags
);
Lock the mini-object with the specified access mode in flags
.
gst_mini_object_unlock ()
void gst_mini_object_unlock (GstMiniObject *object
,GstLockFlags flags
);
Unlock the mini-object with the specified access mode in flags
.
gst_mini_object_is_writable ()
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.
gst_mini_object_make_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
[skip]
gst_mini_object_copy ()
GstMiniObject *
gst_mini_object_copy (const GstMiniObject *mini_object
);
Creates a copy of the mini-object.
MT safe
[skip]
gst_mini_object_set_qdata ()
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 (retrieved 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
.
Parameters
object |
||
quark |
A GQuark, naming the user data pointer |
|
data |
An opaque user data pointer |
|
destroy |
Function to invoke with |
gst_mini_object_get_qdata ()
gpointer gst_mini_object_get_qdata (GstMiniObject *object
,GQuark quark
);
This function gets back user data pointers stored via
gst_mini_object_set_qdata()
.
Parameters
object |
The GstMiniObject to get a stored user data pointer from |
|
quark |
A GQuark, naming the user data pointer |
gst_mini_object_steal_qdata ()
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).
Parameters
object |
The GstMiniObject to get a stored user data pointer from |
|
quark |
A GQuark, naming the user data pointer |
gst_mini_object_replace ()
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
.
gst_mini_object_take ()
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
.
gst_mini_object_steal ()
GstMiniObject *
gst_mini_object_steal (GstMiniObject **olddata
);
Replace the current GstMiniObject pointer to by olddata
with NULL
and
return the old value.
[skip]
Types and Values
struct GstMiniObject
struct GstMiniObject { GType type; gint refcount; gint lockstate; guint flags; GstMiniObjectCopyFunction copy; GstMiniObjectDisposeFunction dispose; GstMiniObjectFreeFunction free; };
Base class for refcounted lightweight objects.
Members
GType |
the GType of the object |
|
gint |
atomic refcount |
|
gint |
atomic state of the locks |
|
guint |
extra flags. |
|
a copy function |
||
GstMiniObjectDisposeFunction |
a dispose function |
|
the free function |
enum GstMiniObjectFlags
Flags for the mini object
Members
the object can be locked and unlocked with
|
||
the object is permanently locked in READONLY mode. Only read locks can be performed on the object. |
||
the object is expected to stay alive
even after |
||
first flag that can be used by subclasses. |