GlobalRef (Jython API documentation)
Date: 2024-08-18

org.python.modules._weakref

## Class GlobalRef

- java.lang.Object
- - java.lang.ref.Reference<T>
  - - java.lang.ref.WeakReference<PyObject>
    - - org.python.modules._weakref.GlobalRef

- All Implemented Interfaces:
    ReferenceBackend

      public class GlobalRef
      extends java.lang.ref.WeakReference<PyObject>
      implements ReferenceBackend

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static ReferenceBackendFactory` | `factory` This is a hook for JyNI to insert a native-objects-aware implementation of ReferenceBackend.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `GlobalRef(PyObject object)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `add(AbstractReference ref)`
    `int` | `count()`
    `boolean` | `equals(java.lang.Object o)` Allow `GlobalRef`s to be used as hashtable-keys.
    `AbstractReference` | `find(java.lang.Class<?> cls)` Search for a reusable reference.
    `static int` | `getCount(PyObject object)` Return the number of references to the specified `PyObject`.
    `static PyList` | `getRefs(PyObject object)` Return a list of references to the specified `PyObject`.
    `static boolean` | `hasDelayedCallbacks()`
    `int` | `hashCode()` Allows `GlobalRef` to be used as hashtable-keys.
    `boolean` | `isCleared()`
    `static ReferenceBackend` | `newInstance(PyObject object)` Create a new tracked `ReferenceBackend`.
    `static void` | `processDelayedCallbacks()` Call all callbacks that were enqueued via `delayedCallback(GlobalRef)` method.
    `int` | `pythonHashCode()` The publicly used `hashCode`, for the {@link org.python.modules.
    `PyList` | `refs()`
    `void` | `restore(PyObject formerReferent)` Restores this weak reference to its former referent.

    - ### Methods inherited from class java.lang.ref.Reference

      `clear, enqueue, get, isEnqueued`

    - ### Methods inherited from class java.lang.Object

      `getClass, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface org.python.modules._weakref.ReferenceBackend

      `get`

- - ### Field Detail

    - #### factory

          public static ReferenceBackendFactory factory

      This is a hook for JyNI to insert a native-objects-aware implementation of ReferenceBackend.

  - ### Constructor Detail

    - #### GlobalRef

          public GlobalRef(PyObject object)

  - ### Method Detail

    - #### add

          public void add(AbstractReference ref)

      Specified by:
        `add` in interface `ReferenceBackend`

    - #### find

          public AbstractReference find(java.lang.Class<?> cls)

      Search for a reusable reference. To be reused, it must be of the same class and it must not have a callback.
      Specified by:
        `find` in interface `ReferenceBackend`

    - #### processDelayedCallbacks

          public static void processDelayedCallbacks()

      Call all callbacks that were enqueued via `delayedCallback(GlobalRef)` method.
      See Also:
        `delayedCallback(GlobalRef)`

    - #### hasDelayedCallbacks

          public static boolean hasDelayedCallbacks()

    - #### isCleared

          public boolean isCleared()

      Specified by:
        `isCleared` in interface `ReferenceBackend`

    - #### count

          public int count()

      Specified by:
        `count` in interface `ReferenceBackend`

    - #### refs

          public PyList refs()

      Specified by:
        `refs` in interface `ReferenceBackend`

    - #### newInstance

          public static ReferenceBackend newInstance(PyObject object)

      Create a new tracked `ReferenceBackend`. If no `ReferenceBackendFactory` is registered, it actually returns a `GlobalRef`.
      Parameters:
        `object` - a `PyObject` to reference
      Returns:
        a new tracked `ReferenceBackend`

    - #### restore

          public void restore(PyObject formerReferent)

      Restores this weak reference to its former referent. This actually means that a fresh `GlobalRef` is created and inserted into all adjacent `AbstractReference`s. The current `GlobalRef` is disbanded. If the given `PyObject` is not the former referent of this weak reference, an `IllegalArgumentException` is thrown.
      Specified by:
        `restore` in interface `ReferenceBackend`
      Throws:
        `java.lang.IllegalArgumentException` - if `formerReferent` is not the actual former referent.

    - #### getCount

          public static int getCount(PyObject object)

      Return the number of references to the specified `PyObject`.
      Parameters:
        `object` - a PyObject
      Returns:
        an int reference count

    - #### getRefs

          public static PyList getRefs(PyObject object)

      Return a list of references to the specified `PyObject`.
      Parameters:
        `object` - a `PyObject`
      Returns:
        a `PyList` of references. May be empty.

    - #### equals

          public boolean equals(java.lang.Object o)

      Allow `GlobalRef`s to be used as hashtable-keys.
      Overrides:
        `equals` in class `java.lang.Object`

    - #### hashCode

          public int hashCode()

      Allows `GlobalRef` to be used as hashtable-keys.
      Overrides:
        `hashCode` in class `java.lang.Object`
      Returns:
        a hashCode `int`-value

    - #### pythonHashCode

          public int pythonHashCode()

      The publicly used `hashCode`, for the `AbstractReference` wrapper.
      Specified by:
        `pythonHashCode` in interface `ReferenceBackend`
      Returns:
        a hashCode `int`-value

Jython homepage