Package org.javagi.gobject

Class InstanceCache

java.lang.Object

org.javagi.gobject.InstanceCache

@NullMarked
public class InstanceCache
extends Object

Caches TypeInstances so the same instance is used for the same memory address.

Constructor Summary

Constructors

Constructor	Description
InstanceCache()

Method Summary

Modifier and Type	Method	Description
static int	getCacheSize()	Get the size of the instance cache, which is the number of cached object instances (both strong and weak references).
static @Nullable Proxy	getForType(MemorySegment address, Function<MemorySegment,? extends Proxy> fallback)	Get a Proxy object for the provided native memory address.
static @Nullable Proxy	getForTypeClass(@Nullable MemorySegment address, Function<MemorySegment,? extends Proxy> fallback)	Get a Proxy object for the provided native memory address of a TypeClass.
static void	newGObject(GObject proxy, @Nullable Type objectType, long size, @Nullable Object @Nullable ... properties)	Construct a new GObject instance and set the provided Java proxy to its address.
static Proxy	put(MemorySegment address, GObject object)	Add the new GObject instance to the cache.
static void	refOnce(@Nullable MemorySegment address)	Call g_object_ref if the reference is not cached.
static void	refUnownedUserDefinedInstance(GObject object)	Increase the refcount of a GObject instance that was defined in Java.
static int	removeToggleRef(MemorySegment address)
static void	unrefUnownedUserDefinedInstance(GObject object)	Decrease the refcount of a GObject instance that was defined in Java.

Methods inherited from class java.lang.Object

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

Constructor Details

InstanceCache

public InstanceCache()

Method Details

getForType

public static @Nullable Proxy getForType(MemorySegment address,
 Function<MemorySegment,? extends Proxy> fallback)

Get a Proxy object for the provided native memory address. If a Proxy object does not yet exist for this address, a new Proxy object is instantiated and added to the cache. The type of the Proxy object is read from the gtype field of the native instance. Invalid references are removed from the cache using a GObject toggle reference.

Parameters:

address - memory address of the native object

fallback - fallback constructor to use when the type is not found in the TypeCache

Returns:

a Proxy instance for the provided memory address

getForTypeClass

public static @Nullable Proxy getForTypeClass(@Nullable MemorySegment address,
 Function<MemorySegment,? extends Proxy> fallback)

Get a Proxy object for the provided native memory address of a TypeClass. The type of the Proxy object is read from the gtype field of the native TypeClass.

Parameters:

address - memory address of the native object

fallback - fallback constructor to use when the type is not found in the TypeCache

Returns:

a Proxy instance for the provided memory address

put

public static Proxy put(MemorySegment address,
 GObject object)

Add the new GObject instance to the cache. Floating references are sunk, and a toggle reference is installed.

Parameters:

address - the memory address of the native instance

object - the GObject instance

Returns:

the cached GObject instance

getCacheSize

public static int getCacheSize()

Get the size of the instance cache, which is the number of cached object instances (both strong and weak references). This is intended for debugging purposes.

Returns:

the size of the instance cache

newGObject

public static void newGObject(GObject proxy,
 @Nullable Type objectType,
 long size,
 @Nullable Object @Nullable ... properties)

Construct a new GObject instance and set the provided Java proxy to its address.

Parameters:

proxy - the Java Proxy for the newly constructed GObject instance

objectType - the GType, if null it will be queried from the TypeCache

size - the size of the native instance

properties - pairs of property names and values (optional). A trailing null will be added automatically.

refOnce

public static void refOnce(@Nullable MemorySegment address)

Call g_object_ref if the reference is not cached.

The refcount is only increased once. On subsequent uses, the refcount is not increased anymore.

Parameters:

address - address of a GObject

refUnownedUserDefinedInstance

public static void refUnownedUserDefinedInstance(GObject object)

Increase the refcount of a GObject instance that was defined in Java. This prevents a double free when the object is owned by native code.

Parameters:

object - the object to ref

unrefUnownedUserDefinedInstance

public static void unrefUnownedUserDefinedInstance(GObject object)

Decrease the refcount of a GObject instance that was defined in Java. This prevents a memory leak when native code doesn't have ownership and therefore will not free the instance.

Parameters:

object - the object to unref

removeToggleRef

public static int removeToggleRef(MemorySegment address)