Class MiniObject

java.lang.Object
org.javagi.base.ProxyInstance
org.freedesktop.gstreamer.gst.MiniObject
All Implemented Interfaces:
Proxy
@Generated("org.javagi.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 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