MiniObject

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)

class MiniObject {

protected

GstMiniObject* gstMiniObject;

GstMiniObject* getMiniObjectStruct();

void* getStruct();

this(GstMiniObject* gstMiniObject);

void init(uint flags, GType type, GstMiniObjectCopyFunction copyFunc, GstMiniObjectDisposeFunction disposeFunc, GstMiniObjectFreeFunction freeFunc);

MiniObject doref();

void unref();

void weakRef(GstMiniObjectNotify notify, void* data);

void weakUnref(GstMiniObjectNotify notify, void* data);

int lock(GstLockFlags flags);

void unlock(GstLockFlags flags);

int isWritable();

MiniObject makeWritable();

MiniObject copy();

void setQdata(GQuark quark, void* data, GDestroyNotify destroy);

void* getQdata(GQuark quark);

void* stealQdata(GQuark quark);

static int replace(MiniObject olddata, MiniObject newdata);

static int take(GstMiniObject** olddata, MiniObject newdata);

static MiniObject steal(GstMiniObject** olddata);

}

Constructors

this this(GstMiniObject* gstMiniObject): Sets our main struct and passes it to the parent class

Members

Functions

copy MiniObject copy(): Creates a copy of the mini-object. MT safe
doref MiniObject doref(): 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.
getMiniObjectStruct GstMiniObject* getMiniObjectStruct(): Get the main Gtk struct
getQdata void* getQdata(GQuark quark): This function gets back user data pointers stored via gst_mini_object_set_qdata().
getStruct void* getStruct(): the main Gtk struct as a void*
init void init(uint flags, GType type, GstMiniObjectCopyFunction copyFunc, GstMiniObjectDisposeFunction disposeFunc, GstMiniObjectFreeFunction freeFunc): Initializes a mini-object with the desired type and copy/dispose/free functions.
isWritable int isWritable(): 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.
lock int lock(GstLockFlags flags): Lock the mini-object with the specified access mode in flags.
makeWritable MiniObject makeWritable(): 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
setQdata void setQdata(GQuark quark, void* 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.
stealQdata void* stealQdata(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).
unlock void unlock(GstLockFlags flags): Unlock the mini-object with the specified access mode in flags.
unref void unref(): Decreases the reference count of the mini-object, possibly freeing the mini-object.
weakRef void weakRef(GstMiniObjectNotify notify, void* 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).
weakUnref void weakUnref(GstMiniObjectNotify notify, void* data): Removes a weak reference callback from a mini object.

Static functions

replace int replace(MiniObject olddata, MiniObject 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.
steal
MiniObject steal(GstMiniObject** olddata): Replace the current GstMiniObject pointer to by olddata with NULL and return the old value.
take
int take(GstMiniObject** olddata, MiniObject 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.

Variables

gstMiniObject GstMiniObject* gstMiniObject;: the main Gtk struct