Class MemoryCleaner

java.lang.Object
org.javagi.interop.MemoryCleaner
@NullMarked public class MemoryCleaner extends Object
This class keeps a cache of all memory addresses for which a Proxy object was created (except for GObject instances; those are handled in the InstanceCache).

When a cached (and owned) Proxy object is garbage-collected, the native memory is released using g_boxed_free, a custom free-function, or (as a last resort), g_free.

When ownership of a memory address transfers to native code, the cleaner will not free the memory. Take and yield ownership with takeOwnership(Proxy) and yieldOwnership(Proxy).

  • Constructor Details

    • MemoryCleaner

      public MemoryCleaner()

  • Method Details

    • setFreeFunc

      public static void setFreeFunc(Proxy proxy, String freeFunc)
      Register a specialized cleanup function for this proxy instance, instead of the default GLib.free(MemorySegment).
      Parameters:
      proxy - the proxy instance
      freeFunc - the specialized cleanup function to call

    • setBoxedType

      public static void setBoxedType(Proxy proxy, @Nullable Type boxedType)
      For a boxed type, g_boxed_free(type, pointer) will be used as cleanup function.
      Parameters:
      proxy - the proxy instance
      boxedType - the boxed type

    • takeOwnership

      public static void takeOwnership(Proxy proxy)
      Take ownership of this memory address: when the proxy object is garbage-collected, the memory will automatically be released.
      Parameters:
      proxy - the proxy instance

    • yieldOwnership

      public static void yieldOwnership(Proxy proxy)
      Yield ownership of this memory address: when the proxy object is garbage-collected, the memory will not be released.
      Parameters:
      proxy - the proxy instance

    • free

      public static void free(@Nullable MemorySegment address)
      Run the MemoryCleaner.StructFinalizer associated with this memory address, by invoking Cleaner.Cleanable.clean().

      The cleaner action will only ever run once, so any further attempts to free this instance (including by the GC) will be a no-op.

      Parameters:
      address - the memory address to free