GstMiniObject

## 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`