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 Details

    • InstanceCache

      public InstanceCache()

  • Method Details

    • getForInstanceInit

      public static @Nullable TypeInstance getForInstanceInit(MemorySegment address, MemorySegment gClass)
      For a GObject-derived class that is declared in Java, a new instance is already available in the "CONSTRUCTING" scoped value. We set its address and return it.

      This function is only called from `GInstanceInitFunc` because that's the first time the Java side is informed about the new instance.

      To determine the GType of the new instance, we use the gClass parameter, because the typeclass of address will be set to the parent typeclass initially.

      Parameters:
      address - the native address of the new instance
      gClass - the target typeclass of the instance
      Returns:
      the Java instance, with the correct native memory address

    • getForType

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

    • get

      public static @Nullable Proxy get(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

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

    • getTypeClass

      public static @Nullable Proxy getTypeClass(@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 object, @Nullable Type type, long size, @Nullable Object @Nullable ... properties)
      Construct a new GObject instance and set the provided Java proxy to its address.
      Parameters:
      object - the Java proxy for the newly constructed GObject instance
      type - 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)
      Remove toggle ref from a GObject instance. Called directly or from the default GLib MainContext.
      Parameters:
      address - address of the object
      Returns:
      always 0