GstMiniObject

GstMiniObject — Lightweight base class for the GStreamer object hierarchy

Functions

Types and Values

Object Hierarchy


Includes

#include <gst/gst.h>

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.

Last reviewed on 2012-06-15 (0.11.93)

Functions

GstMiniObjectCopyFunction ()

GstMiniObject *
(*GstMiniObjectCopyFunction) (const GstMiniObject *obj);

Function prototype for methods to create copies of instances.

Parameters

obj

MiniObject to copy

 

Returns

reference to cloned instance.


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.

Parameters

obj

MiniObject to dispose

 

Returns

TRUE if the object should be cleaned up.


GstMiniObjectFreeFunction ()

void
(*GstMiniObjectFreeFunction) (GstMiniObject *obj);

Virtual function prototype for methods to free ressources used by mini-objects.

Parameters

obj

MiniObject to free

 

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.

Parameters

user_data

data that was provided when the notify was added

 

obj

the mini object

 

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.

Parameters

obj

MiniObject to return type for.

 

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.

Parameters

obj

MiniObject to return flags for.

 

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.

Parameters

obj

MiniObject to check for flags.

 

flag

Flag to check for

 

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.

Parameters

obj

MiniObject to set flag in.

 

flag

Flag to set, can by any number of bits in guint32.

 

GST_MINI_OBJECT_FLAG_UNSET()

#define GST_MINI_OBJECT_FLAG_UNSET(obj,flag)         (GST_MINI_OBJECT_FLAGS (obj) &= ~(flag))

This macro usets the given bits.

Parameters

obj

MiniObject to unset flag in.

 

flag

Flag to set, must be a single bit in guint32.

 

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().

Parameters

obj

a GstMiniObject

 

GST_LOCK_FLAG_READWRITE

#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


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.

Parameters

obj

a GstMiniObject

 

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.

Parameters

obj

a GstMiniObject

 

GST_DEFINE_MINI_OBJECT_TYPE()

#define             GST_DEFINE_MINI_OBJECT_TYPE(TypeName,type_name)

Define a new mini-object type with the given name

Parameters

TypeName

name of the new type in CamelCase

 

type_name

name of the new type

 

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.

Parameters

mini_object

a GstMiniObject

 

flags

initial GstMiniObjectFlags

 

type

the GType of the mini-object to create

 

copy_func

the copy function, or NULL.

[allow-none]

dispose_func

the dispose function, or NULL.

[allow-none]

free_func

the free function or NULL.

[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 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.

Parameters

mini_object

the mini-object

 

Returns

the mini-object.

[transfer full]


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.

Parameters

mini_object

the mini-object

 

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).

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.

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 .

Parameters

object

the mini-object to lock

 

flags

GstLockFlags

 

Returns

TRUE if object could be locked.


gst_mini_object_unlock ()

void
gst_mini_object_unlock (GstMiniObject *object,
                        GstLockFlags flags);

Unlock the mini-object with the specified access mode in flags .

Parameters

object

the mini-object to unlock

 

flags

GstLockFlags

 

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.

Parameters

mini_object

the mini-object to check

 

Returns

TRUE if the object 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

Parameters

mini_object

the mini-object to make writable.

[transfer full]

Returns

a mini-object (possibly the same pointer) that is writable.

[transfer full]


gst_mini_object_copy ()

GstMiniObject *
gst_mini_object_copy (const GstMiniObject *mini_object);

Creates a copy of the mini-object.

MT safe

Parameters

mini_object

the mini-object to copy

 

Returns

the new mini-object.

[transfer full]


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 (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 .

Parameters

object

a GstMiniObject

 

quark

A GQuark, naming the user data pointer

 

data

An opaque user data pointer

 

destroy

Function to invoke with data as argument, when data needs to be freed

 

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

 

Returns

The user data pointer set, or NULL.

[transfer none]


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

 

Returns

The user data pointer set, or NULL.

[transfer full]


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.

Parameters

olddata

pointer to a pointer to a mini-object to be replaced.

[inout][transfer full]

newdata

pointer to new mini-object

 

Returns

TRUE if newdata was different from olddata


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.

Parameters

olddata

pointer to a pointer to a mini-object to be replaced.

[inout][transfer full]

newdata

pointer to new mini-object

 

Returns

TRUE if newdata was different from olddata


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.

Parameters

olddata

pointer to a pointer to a mini-object to be stolen.

[inout][transfer full]

Returns

the GstMiniObject at oldata

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. 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

Members

GType type;

the GType of the object

 

gint refcount;

atomic refcount

 

gint lockstate;

atomic state of the locks

 

guint flags;

extra flags.

 

GstMiniObjectCopyFunction copy;

a copy function

 

GstMiniObjectDisposeFunction dispose;

a dispose function

 

GstMiniObjectFreeFunction free;

the free function

 

enum GstMiniObjectFlags

Flags for the mini object

Members

GST_MINI_OBJECT_FLAG_LOCKABLE

the object can be locked and unlocked with gst_mini_object_lock() and gst_mini_object_unlock().

 

GST_MINI_OBJECT_FLAG_LOCK_READONLY

the object is permanently locked in READONLY mode. Only read locks can be performed on the object.

 

GST_MINI_OBJECT_FLAG_LAST

first flag that can be used by subclasses.

 

enum GstLockFlags

Flags used when locking miniobjects

Members

GST_LOCK_FLAG_READ

lock for read access

 

GST_LOCK_FLAG_WRITE

lock for write access

 

GST_LOCK_FLAG_EXCLUSIVE

lock for exclusive access

 

GST_LOCK_FLAG_LAST

first flag that can be used for custom purposes