GstMiniObject

## GstMiniObject GstMiniObject — Lightweight base class for the GStreamer object hierarchy |

## Synopsis

    #include <gst/gst.h>

    struct              GstMiniObject;
    enum                GstMiniObjectFlags;
    GstMiniObject *     (*GstMiniObjectCopyFunction)        (const GstMiniObject *obj);
    gboolean            (*GstMiniObjectDisposeFunction)     (GstMiniObject *obj);
    void                (*GstMiniObjectFreeFunction)        (GstMiniObject *obj);
    void                (*GstMiniObjectWeakNotify)          (gpointer data,
                                                             GstMiniObject *where_the_mini_object_was);
    #define             GST_MINI_OBJECT_TYPE                (obj)
    #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_REFCOUNT            (obj)
    #define             GST_MINI_OBJECT_REFCOUNT_VALUE      (obj)
    #define             GST_MINI_OBJECT_SIZE                (obj)
    #define             GST_DEFINE_MINI_OBJECT_TYPE         (TypeName,
                                                             type_name)
    void                gst_mini_object_init                (GstMiniObject *mini_object,
                                                             GType type,
                                                             gsize size);
    GstMiniObject *     gst_mini_object_copy                (const GstMiniObject *mini_object);
    gboolean            gst_mini_object_is_writable         (const GstMiniObject *mini_object);
    GstMiniObject *     gst_mini_object_make_writable       (GstMiniObject *mini_object);
    GstMiniObject *     gst_mini_object_ref                 (GstMiniObject *mini_object);
    void                gst_mini_object_unref               (GstMiniObject *mini_object);
    void                gst_mini_object_weak_ref            (GstMiniObject *object,
                                                             GstMiniObjectWeakNotify notify,
                                                             gpointer data);
    void                gst_mini_object_weak_unref          (GstMiniObject *object,
                                                             GstMiniObjectWeakNotify notify,
                                                             gpointer data);
    gboolean            gst_mini_object_replace             (GstMiniObject **olddata,
                                                             GstMiniObject *newdata);
    GstMiniObject *     gst_mini_object_steal               (GstMiniObject **olddata);
    gboolean            gst_mini_object_take                (GstMiniObject **olddata,
                                                             GstMiniObject *newdata);

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

Last reviewed on 2012-03-28 (0.11.3)

## Details

### struct GstMiniObject

    struct GstMiniObject {
      GType   type;

      gint    refcount;
      guint   flags;
      gsize   size;

      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
guint `flags`; | extra flags.
gsize `size`; | the size of the structure
GstMiniObjectCopyFunction `copy`; | a copy function
GstMiniObjectDisposeFunction `dispose`; | a dispose function
GstMiniObjectFreeFunction `free`; | the free function

### enum GstMiniObjectFlags

    typedef enum {
      /* padding */
      GST_MINI_OBJECT_FLAG_LAST = (1<<4)
    } GstMiniObjectFlags;

Flags for the mini object

`GST_MINI_OBJECT_FLAG_LAST` | first flag that can be used by subclasses.

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

### GstMiniObjectWeakNotify ()

    void                (*GstMiniObjectWeakNotify)          (gpointer data,
                                                             GstMiniObject *where_the_mini_object_was);

A GstMiniObjectWeakNotify function can be added to a mini object as a callback that gets triggered when the mini object is finalized. Since the mini object is already being finalized when the GstMiniObjectWeakNotify is called, there's not much you could do with the object, apart from e.g. using its adress as hash-index or the like.

`data` : | data that was provided when the weak reference was established
`where_the_mini_object_was` : | the mini object being finalized

Since 0.10.35

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

### 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_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_MINI_OBJECT_SIZE()

    #define GST_MINI_OBJECT_SIZE(obj)              ((GST_MINI_OBJECT_CAST(obj))->size)

Get the allocated size of `obj`.

`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,
                                                             GType type,
                                                             gsize size);

Initializes a mini-object with the desired type and size.

MT safe

`mini_object` : | a GstMiniObject
`type` : | the GType of the mini-object to create
`size` : | the size of the data
Returns : | the new mini-object. [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_is_writable ()

    gboolean            gst_mini_object_is_writable         (const GstMiniObject *mini_object);

Checks if a mini-object is writable. A mini-object is writable if the reference count is one. Modification of a mini-object should only be done after verifying that it is writable.

MT safe

`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_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,
                                                             GstMiniObjectWeakNotify 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

Since 0.10.35

### gst_mini_object_weak_unref ()

    void                gst_mini_object_weak_unref          (GstMiniObject *object,
                                                             GstMiniObjectWeakNotify notify,
                                                             gpointer data);

Removes a weak reference callback to a mini object.

`object` : | GstMiniObject to remove a weak reference from
`notify` : | callback to search for
`data` : | data to search for

Since 0.10.35

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

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