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

org.python.core

## Class JyAttribute

- java.lang.Object
- - org.python.core.JyAttribute

- All Implemented Interfaces:
    java.io.Serializable

      public abstract class JyAttribute
      extends java.lang.Object
      implements java.io.Serializable

  Manages a linked list of general purpose Object-attributes that can be attached to arbitrary `PyObject`s. This method replaces the formerly used method of maintaining weak hash-maps (`WeakHashMap`) for such cases. These weak hash-maps were used to map `PyObject`s to such attributes, for instance to attach `GlobalRef`-objects in the `WeakrefModule`.

  Attributes attached via the weak hash-map-method break, if the `PyObject` is resurrected in its finalizer. The `JyAttribute`-method is resurrection-safe.

  To reduce memory footprint of `PyObject`s, the fields for `FinalizeTrigger`s and `javaProxy` are included in the list; `javaProxy` always on top so there is no speed-regression, `FinalizeTrigger` on bottom, as it is usually never accessed.

  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static byte` | `FINALIZE_TRIGGER_ATTR`
    `static byte` | `GC_CYCLE_MARK_ATTR` Used by `gc`-module to mark cyclic trash.
    `static byte` | `GC_DELAYED_FINALIZE_CRITICAL_MARK_ATTR` Used by `gc`-module to mark finalizable objects that might have been resurrected during a delayed finalization process.
    `static byte` | `JAVA_PROXY_ATTR`
    `static byte` | `JYNI_HANDLE_ATTR` Reserved for use by JyNI.
    `static byte` | `PY_ID_ATTR` Allows the id of a `PyObject` to persist resurrection of that object.
    `static byte` | `PYCLASS_PY2JY_CACHE_ATTR` Only used internally by `Py.javaPyClass(PyObject, Class)`
    `static byte` | `WEAK_REF_ATTR` Stores list of weak references linking to this `PyObject`.
    `static byte` | `WEAKREF_PENDING_GET_ATTR` Holds the current thread for an {@link org.python.modules.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `debugPrintAttributes(PyObject o, java.io.PrintStream out)` Prints the current state of the attribute-list of the given object to the given stream.
    `static void` | `delAttr(PyObject ob, byte attr_type)` Removes the attribute of given type from the given object's attribute-list (if it existed at all).
    `static java.lang.Object` | `getAttr(PyObject ob, byte attr_type)` Retrieves the attribute of the given type from the given `PyObject`.
    `static boolean` | `hasAttr(PyObject ob, byte attr_type)` Checks whether the given `PyObject` has an attribute of the given type attached.
    `static byte` | `reserveCustomAttrType()` Reserves and returns a new non-transient attr type for custom use.
    `static byte` | `reserveTransientCustomAttrType()` Reserves and returns a new transient attr type for custom use.
    `static void` | `setAttr(PyObject ob, byte attr_type, java.lang.Object value)` Sets the attribute of type `attr_type` in `ob` to `value`.

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

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### JAVA_PROXY_ATTR

          public static final byte JAVA_PROXY_ATTR

      See Also:
        Constant Field Values

    - #### WEAK_REF_ATTR

          public static final byte WEAK_REF_ATTR

      Stores list of weak references linking to this `PyObject`. This list is weakref-based, so it does not keep the weakrefs alive. This is the only way to find out which weakrefs (i.e. `AbstractReference`) linked to the object after a resurrection. A weak hash-map-based approach for this purpose would break on resurrection.
      See Also:
        Constant Field Values

    - #### JYNI_HANDLE_ATTR

          public static final byte JYNI_HANDLE_ATTR

      Reserved for use by JyNI.
      See Also:
        Constant Field Values

    - #### PY_ID_ATTR

          public static final byte PY_ID_ATTR

      Allows the id of a `PyObject` to persist resurrection of that object.
      See Also:
        Constant Field Values

    - #### WEAKREF_PENDING_GET_ATTR

          public static final byte WEAKREF_PENDING_GET_ATTR

      Holds the current thread for an `AbstractReference` while referent-retrieval is pending due to a potentially restored-by-resurrection weak reference. After the restore has happened or the clear was confirmed, the thread is interrupted and the attribute is cleared.
      See Also:
        Constant Field Values

    - #### PYCLASS_PY2JY_CACHE_ATTR

          public static final byte PYCLASS_PY2JY_CACHE_ATTR

      Only used internally by `Py.javaPyClass(PyObject, Class)`
      See Also:
        Constant Field Values

    - #### GC_CYCLE_MARK_ATTR

          public static final byte GC_CYCLE_MARK_ATTR

      Used by `gc`-module to mark cyclic trash. Searching for cyclic trash is usually not required by Jython. It is only done if gc-features are enabled that mimic CPython behavior.
      See Also:
        Constant Field Values

    - #### GC_DELAYED_FINALIZE_CRITICAL_MARK_ATTR

          public static final byte GC_DELAYED_FINALIZE_CRITICAL_MARK_ATTR

      Used by `gc`-module to mark finalizable objects that might have been resurrected during a delayed finalization process.
      See Also:
        Constant Field Values

    - #### FINALIZE_TRIGGER_ATTR

          public static final byte FINALIZE_TRIGGER_ATTR

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### reserveCustomAttrType

          public static byte reserveCustomAttrType()

      Reserves and returns a new non-transient attr type for custom use.
      Returns:
        a non-transient attr type for custom use

    - #### reserveTransientCustomAttrType

          public static byte reserveTransientCustomAttrType()

      Reserves and returns a new transient attr type for custom use.
      Returns:
        a transient attr type for custom use

    - #### hasAttr

          public static boolean hasAttr(PyObject ob,
                                        byte attr_type)

      Checks whether the given `PyObject` has an attribute of the given type attached.

    - #### getAttr

          public static java.lang.Object getAttr(PyObject ob,
                                                 byte attr_type)

      Retrieves the attribute of the given type from the given `PyObject`. If no attribute of the given type is attached, null is returned.

    - #### debugPrintAttributes

          public static void debugPrintAttributes(PyObject o,
                                                  java.io.PrintStream out)

      Prints the current state of the attribute-list of the given object to the given stream. (Intended for debugging)

    - #### setAttr

          public static void setAttr(PyObject ob,
                                     byte attr_type,
                                     java.lang.Object value)

      Sets the attribute of type `attr_type` in `ob` to `value`. If no corresponding attribute exists yet, one is created. If `value == null`, the attribute is removed (if it existed at all).

    - #### delAttr

          public static void delAttr(PyObject ob,
                                     byte attr_type)

      Removes the attribute of given type from the given object's attribute-list (if it existed at all). This is equivalent to calling `setAttr(ob, attr_type, null)`.

Jython homepage