Package org.freedesktop.gstreamer.gst

Class MiniObject

java.lang.Object

org.javagi.base.ProxyInstance

org.freedesktop.gstreamer.gst.MiniObject

All Implemented Interfaces:

Proxy

@Generated("io.github.jwharm.JavaGI")
public class MiniObject
extends ProxyInstance

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 and there is no parent or a single parent exists and is writable itself, 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.

Constructor Summary

Constructors

Constructor	Description
MiniObject()	Allocate a new MiniObject.
MiniObject(Arena arena)	Allocate a new MiniObject.
MiniObject(MemorySegment address)	Create a MiniObject proxy instance for the provided memory address.
MiniObject(Type type, int refcount, int lockstate, int flags, MiniObjectCopyFunction copy, MiniObjectDisposeFunction dispose, MiniObjectFreeFunction free, int privUint, MemorySegment privPointer)	Allocate a new MiniObject with the fields set to the provided values.
MiniObject(Type type, int refcount, int lockstate, int flags, MiniObjectCopyFunction copy, MiniObjectDisposeFunction dispose, MiniObjectFreeFunction free, int privUint, MemorySegment privPointer, Arena arena)	Allocate a new MiniObject with the fields set to the provided values.

Method Summary

Modifier and Type	Method	Description
void	addParent(MiniObject parent)	This adds parent as a parent for object. Having one ore more parents affects the writability of object: if a parent is not writable, this MiniObject is also not writable, regardless of its refcount.
@Nullable MiniObject	copy()	Creates a copy of the mini-object.
static MemoryLayout	getMemoryLayout()	The memory layout of the native struct.
@Nullable MemorySegment	getQdata(Quark quark)	This function gets back user data pointers stored via gst_mini_object_set_qdata().
static @Nullable Type	getType()	Get the GType of the MiniObject class
void	init(int flags, Type type, @Nullable MiniObjectCopyFunction copyFunc, @Nullable MiniObjectDisposeFunction disposeFunc, @Nullable MiniObjectFreeFunction freeFunc)	Initializes a mini-object with the desired type and copy/dispose/free functions.
boolean	isWritable()	If this MiniObject 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.
boolean	lock(Set<LockFlags> flags)	Lock the mini-object with the specified access mode in flags.
boolean	lock(LockFlags... flags)	Lock the mini-object with the specified access mode in flags.
@Nullable MiniObject	makeWritable()	Checks if a mini-object is writable.
@Nullable MiniObjectCopyFunction	readCopy()	Read the value of the field copy.
@Nullable MiniObjectDisposeFunction	readDispose()	Read the value of the field dispose.
int	readFlags()	Read the value of the field flags.
@Nullable MiniObjectFreeFunction	readFree()	Read the value of the field free.
int	readLockstate()	Read the value of the field lockstate.
MemorySegment	readPrivPointer()	Read the value of the field priv_pointer.
int	readPrivUint()	Read the value of the field priv_uint.
int	readRefcount()	Read the value of the field refcount.
Type	readType()	Read the value of the field type.
MiniObject	ref()	Increase the reference count of the mini-object.
void	removeParent(MiniObject parent)	This removes parent as a parent for object. See gst_mini_object_add_parent().
static boolean	replace(@Nullable Out<MiniObject> olddata, @Nullable MiniObject newdata)	Atomically modifies a pointer to point to a new mini-object.
void	setQdata(Quark quark, @Nullable MemorySegment data)	This sets an opaque, named pointer on a miniobject.
static @Nullable MiniObject	steal(Out<MiniObject> olddata)	Replace the current GstMiniObject pointer to by olddata with null and return the old value.
@Nullable MemorySegment	stealQdata(Quark quark)	This function gets back user data pointers stored via gst_mini_object_set_qdata() and removes the data from this MiniObject without invoking its destroy() function (if any was set).
static boolean	take(Out<MiniObject> olddata, MiniObject newdata)	Modifies a pointer to point to a new mini-object.
void	unlock(Set<LockFlags> flags)	Unlock the mini-object with the specified access mode in flags.
void	unlock(LockFlags... flags)	Unlock the mini-object with the specified access mode in flags.
void	unref()	Decreases the reference count of the mini-object, possibly freeing the mini-object.
void	weakRef(@Nullable MiniObjectNotify notify)	Adds a weak reference callback to a mini object.
void	weakUnref(@Nullable MiniObjectNotify notify)	Removes a weak reference callback from a mini object.
void	writeCopy(@Nullable MiniObjectCopyFunction copy, Arena _arena)	Write a value in the field copy.
void	writeDispose(@Nullable MiniObjectDisposeFunction dispose, Arena _arena)	Write a value in the field dispose.
void	writeFlags(int flags)	Write a value in the field flags.
void	writeFree(@Nullable MiniObjectFreeFunction free, Arena _arena)	Write a value in the field free.
void	writeLockstate(int lockstate)	Write a value in the field lockstate.
void	writePrivPointer(MemorySegment privPointer)	Write a value in the field priv_pointer.
void	writePrivUint(int privUint)	Write a value in the field priv_uint.
void	writeRefcount(int refcount)	Write a value in the field refcount.
void	writeType(Type type)	Write a value in the field type.

Methods inherited from class org.javagi.base.ProxyInstance

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Details

MiniObject

public MiniObject(MemorySegment address)

Create a MiniObject proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

MiniObject

public MiniObject(Arena arena)

Allocate a new MiniObject.

Parameters:

arena - to control the memory allocation scope

MiniObject

public MiniObject()

Allocate a new MiniObject. The memory is allocated with Arena.ofAuto().

MiniObject

public MiniObject(Type type,
 int refcount,
 int lockstate,
 int flags,
 MiniObjectCopyFunction copy,
 MiniObjectDisposeFunction dispose,
 MiniObjectFreeFunction free,
 int privUint,
 MemorySegment privPointer,
 Arena arena)

Allocate a new MiniObject with the fields set to the provided values.

Parameters:

type - value for the field type

refcount - value for the field refcount

lockstate - value for the field lockstate

flags - value for the field flags

copy - value for the field copy

dispose - value for the field dispose

free - value for the field free

privUint - value for the field privUint

privPointer - value for the field privPointer

arena - to control the memory allocation scope

MiniObject

public MiniObject(Type type,
 int refcount,
 int lockstate,
 int flags,
 MiniObjectCopyFunction copy,
 MiniObjectDisposeFunction dispose,
 MiniObjectFreeFunction free,
 int privUint,
 MemorySegment privPointer)

Allocate a new MiniObject with the fields set to the provided values. The memory is allocated with Arena.ofAuto().

Parameters:

type - value for the field type

refcount - value for the field refcount

lockstate - value for the field lockstate

flags - value for the field flags

copy - value for the field copy

dispose - value for the field dispose

free - value for the field free

privUint - value for the field privUint

privPointer - value for the field privPointer

Method Details

getType

public static @Nullable Type getType()

Get the GType of the MiniObject class

Returns:

the GType

getMemoryLayout

public static MemoryLayout getMemoryLayout()

The memory layout of the native struct.

Returns:

the memory layout

readType

public Type readType()

Read the value of the field type.

Returns:

The value of the field type

writeType

public void writeType(Type type)

Write a value in the field type.

Parameters:

type - The new value for the field type

readRefcount

public int readRefcount()

Read the value of the field refcount.

Returns:

The value of the field refcount

writeRefcount

public void writeRefcount(int refcount)

Write a value in the field refcount.

Parameters:

refcount - The new value for the field refcount

readLockstate

public int readLockstate()

Read the value of the field lockstate.

Returns:

The value of the field lockstate

writeLockstate

public void writeLockstate(int lockstate)

Write a value in the field lockstate.

Parameters:

lockstate - The new value for the field lockstate

readFlags

public int readFlags()

Read the value of the field flags.

Returns:

The value of the field flags

writeFlags

public void writeFlags(int flags)

Write a value in the field flags.

Parameters:

flags - The new value for the field flags

readCopy

public @Nullable MiniObjectCopyFunction readCopy()

Read the value of the field copy.

Returns:

The value of the field copy

writeCopy

public void writeCopy(@Nullable MiniObjectCopyFunction copy,
 Arena _arena)

Write a value in the field copy.

Parameters:

copy - The new value for the field copy

_arena - to control the memory allocation scope

readDispose

public @Nullable MiniObjectDisposeFunction readDispose()

Read the value of the field dispose.

Returns:

The value of the field dispose

writeDispose

public void writeDispose(@Nullable MiniObjectDisposeFunction dispose,
 Arena _arena)

Write a value in the field dispose.

Parameters:

dispose - The new value for the field dispose

_arena - to control the memory allocation scope

readFree

public @Nullable MiniObjectFreeFunction readFree()

Read the value of the field free.

Returns:

The value of the field free

writeFree

public void writeFree(@Nullable MiniObjectFreeFunction free,
 Arena _arena)

Write a value in the field free.

Parameters:

free - The new value for the field free

_arena - to control the memory allocation scope

readPrivUint

public int readPrivUint()

Read the value of the field priv_uint.

Returns:

The value of the field priv_uint

writePrivUint

public void writePrivUint(int privUint)

Write a value in the field priv_uint.

Parameters:

privUint - The new value for the field priv_uint

readPrivPointer

public MemorySegment readPrivPointer()

Read the value of the field priv_pointer.

Returns:

The value of the field priv_pointer

writePrivPointer

public void writePrivPointer(MemorySegment privPointer)

Write a value in the field priv_pointer.

Parameters:

privPointer - The new value for the field priv_pointer

replace

public static boolean replace(@Nullable Out<MiniObject> olddata,
 @Nullable 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.

Parameters:

olddata - pointer to a pointer to a mini-object to be replaced

newdata - pointer to new mini-object

Returns:

true if newdata was different from olddata

steal

public static @Nullable MiniObject steal(Out<MiniObject> 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

Returns:

the GstMiniObject at oldata

take

public static boolean take(Out<MiniObject> 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.

Parameters:

olddata - pointer to a pointer to a mini-object to be replaced

newdata - pointer to new mini-object

Returns:

true if newdata was different from olddata

addParent

public void addParent(MiniObject parent)

This adds parent as a parent for object. Having one ore more parents affects the writability of object: if a parent is not writable, this MiniObject is also not writable, regardless of its refcount. this MiniObject is only writable if all the parents are writable and its own refcount is exactly 1.

Note: This function does not take ownership of parent and also does not take an additional reference. It is the responsibility of the caller to remove the parent again at a later time.

Parameters:

parent - a parent GstMiniObject

Since:

1.16

copy

public @Nullable MiniObject copy()

Creates a copy of the mini-object.

MT safe

Returns:

the new mini-object if copying is possible, null otherwise.

getQdata

public @Nullable MemorySegment getQdata(Quark quark)

This function gets back user data pointers stored via gst_mini_object_set_qdata().

Parameters:

quark - A GQuark, naming the user data pointer

Returns:

The user data pointer set, or null

init

public void init(int flags,
 Type type,
 @Nullable MiniObjectCopyFunction copyFunc,
 @Nullable MiniObjectDisposeFunction disposeFunc,
 @Nullable MiniObjectFreeFunction freeFunc)

Initializes a mini-object with the desired type and copy/dispose/free functions.

Parameters:

flags - initial GstMiniObjectFlags

type - the GType of the mini-object to create

copyFunc - the copy function, or null

disposeFunc - the dispose function, or null

freeFunc - the free function or null

isWritable

public boolean isWritable()

If this MiniObject 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 this MiniObject 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.

Returns:

true if the object is writable.

lock

public boolean lock(Set<LockFlags> flags)

Lock the mini-object with the specified access mode in flags.

Parameters:

flags - GstLockFlags

Returns:

true if this MiniObject could be locked.

lock

public boolean lock(LockFlags... flags)

Lock the mini-object with the specified access mode in flags.

Parameters:

flags - GstLockFlags

Returns:

true if this MiniObject could be locked.

makeWritable

public @Nullable 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

Returns:

a writable mini-object (which may or may not be the same as miniObject) or null if copying is required but not possible.

ref

public MiniObject ref()

Increase the reference count of the mini-object.

Note that the refcount affects the writability of miniObject, 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.

Returns:

the mini-object.

removeParent

public void removeParent(MiniObject parent)

This removes parent as a parent for object. See gst_mini_object_add_parent().

Parameters:

parent - a parent GstMiniObject

Since:

1.16

setQdata

public void setQdata(Quark quark,
 @Nullable MemorySegment data)

This sets an opaque, named pointer on a miniobject. The name is specified through a GQuark (retrieved e.g. via g_quark_from_static_string()), and the pointer can be gotten back from the this MiniObject with gst_mini_object_get_qdata() until the this MiniObject 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 this MiniObject is disposed, or the data is being overwritten by a call to gst_mini_object_set_qdata() with the same quark.

Parameters:

quark - A GQuark, naming the user data pointer

data - An opaque user data pointer

stealQdata

public @Nullable MemorySegment stealQdata(Quark quark)

This function gets back user data pointers stored via gst_mini_object_set_qdata() and removes the data from this MiniObject without invoking its destroy() function (if any was set).

Parameters:

quark - A GQuark, naming the user data pointer

Returns:

The user data pointer set, or null

unlock

public void unlock(Set<LockFlags> flags)

Unlock the mini-object with the specified access mode in flags.

Parameters:

flags - GstLockFlags

unlock

public void unlock(LockFlags... flags)

Unlock the mini-object with the specified access mode in flags.

Parameters:

flags - GstLockFlags

unref

public void unref()

Decreases the reference count of the mini-object, possibly freeing the mini-object.

weakRef

public void weakRef(@Nullable MiniObjectNotify notify)

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:

notify - callback to invoke before the mini object is freed

weakUnref

public void weakUnref(@Nullable MiniObjectNotify notify)

Removes a weak reference callback from a mini object.

Parameters:

notify - callback to search for