GStreamer 1.0 Core Reference Manual: GstMiniObject

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

## Functions

GstMiniObject * | (*GstMiniObjectCopyFunction) ()
gboolean | (*GstMiniObjectDisposeFunction) ()
void | (*GstMiniObjectFreeFunction) ()
void | (*GstMiniObjectNotify) ()
#define | GST_MINI_OBJECT_TYPE()
#define | GST_MINI_OBJECT_FLAGS()
#define | GST_MINI_OBJECT_FLAG_IS_SET()
#define | GST_MINI_OBJECT_FLAG_SET()
#define | GST_MINI_OBJECT_FLAG_UNSET()
#define | GST_MINI_OBJECT_IS_LOCKABLE()
#define | GST_LOCK_FLAG_READWRITE
#define | GST_MINI_OBJECT_REFCOUNT()
#define | GST_MINI_OBJECT_REFCOUNT_VALUE()
#define | GST_DEFINE_MINI_OBJECT_TYPE()
void | gst_mini_object_init ()
GstMiniObject * | gst_mini_object_ref ()
void | gst_mini_object_unref ()
void | gst_mini_object_weak_ref ()
void | gst_mini_object_weak_unref ()
gboolean | gst_mini_object_lock ()
void | gst_mini_object_unlock ()
gboolean | gst_mini_object_is_writable ()
GstMiniObject * | gst_mini_object_make_writable ()
GstMiniObject * | gst_mini_object_copy ()
void | gst_mini_object_set_qdata ()
gpointer | gst_mini_object_get_qdata ()
gpointer | gst_mini_object_steal_qdata ()
gboolean | gst_mini_object_replace ()
gboolean | gst_mini_object_take ()
GstMiniObject * | gst_mini_object_steal ()

## Types and Values

struct | GstMiniObject
enum | GstMiniObjectFlags
enum | GstLockFlags

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