GstMiniObject

GstMiniObject — Lightweight base class for the GStreamer object hierarchy

Synopsis

#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);

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)

Details

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

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

GstMiniObjectCopyFunction ()

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

Function prototype for methods to create copies of instances.

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.

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.

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.

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.

obj :

MiniObject to return type for.

enum GstMiniObjectFlags

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

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.

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.

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.

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.

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.

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

obj :

a GstMiniObject

enum GstLockFlags

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

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

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.

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.

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

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.

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.

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.

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

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.

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.

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.

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.

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

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

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.

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

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

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.

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.

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.

olddata :

pointer to a pointer to a mini-object to be stolen. [inout][transfer full]

Returns :

the GstMiniObject at oldata