4.5. py4j.finalizer — Py4J Finalizer API — Py4J

Py4J - A Bridge between Python and Java

### Navigation

- index
- modules |
- next |
- previous |
- Home |
- Download |
- Doc |
- Blog |
- github |
- About »

# 4.5. `py4j.finalizer` — Py4J Finalizer API

The `py4j.finalizer` module contains global classes that enables the registration of finalizers, i.e., weak reference callbacks. This module is used by Py4J to register a finalizer for each JavaObject instance: once there is no more reference to a JavaObject instance on the Python side, the finalizer sends a message to the JVM to remove the reference from the Gateway to prevent memory leak.

The `py4j.finalizer` module is necessary because JavaObject instances have circular references with JavaMethods and hence, they cannot keep their own finalizer.

## 4.5.1. ThreadSafeFinalizer

class py4j.finalizer.ThreadSafeFinalizer

  A ThreadSafeFinalizer is a global class used to register weak reference finalizers (i.e., a weak reference with a callback).

  This class is useful when one wants to register a finalizer of an object with circular references. The finalizer of an object with circular references might never be called if the object’s finalizer is kept by the same object.

  For example, if object A refers to B and B refers to A, A should not keep a weak reference to itself.

  ThreadSafeFinalizer is thread-safe and uses reentrant lock on each operation.

  classmethod add_finalizer(id, weak_ref)

    Registers a finalizer with an id.

    Parameters

      - id – The id of the object referenced by the weak reference.

      - weak_ref – The weak reference to register.

  classmethod clear_finalizers(clear_all=False)

    Removes all registered finalizers.

    Parameters

      clear_all – If True, all finalizers are deleted. Otherwise, only the finalizers from an empty weak reference are deleted (i.e., weak references pointing to inexistent objects).

  finalizers = {}
  lock = <unlocked _thread.RLock object owner=0 count=0>
  classmethod remove_finalizer(id)

    Removes a finalizer associated with this id.

    Parameters

      id – The id of the object for which the finalizer will be deleted.

## 4.5.2. Finalizer

class py4j.finalizer.Finalizer

  A Finalizer is a global class used to register weak reference finalizers (i.e., a weak reference with a callback).

  This class is useful when one wants to register a finalizer of an object with circular references. The finalizer of an object with circular references might never be called if the object’s finalizer is kept by the same object.

  For example, if object A refers to B and B refers to A, A should not keep a weak reference to itself.

  Finalizer is not thread-safe and should only be used by single-threaded programs.

  classmethod add_finalizer(id, weak_ref)

    Registers a finalizer with an id.

    Parameters

      - id – The id of the object referenced by the weak reference.

      - weak_ref – The weak reference to register.

  classmethod clear_finalizers(clear_all=False)

    Removes all registered finalizers.

    Parameters

      clear_all – If True, all finalizers are deleted. Otherwise, only the finalizers from an empty weak reference are deleted (i.e., weak references pointing to inexistent objects).

  finalizers = {}
  classmethod remove_finalizer(id)

    Removes a finalizer associated with this id.

    Parameters

      id – The id of the object for which the finalizer will be deleted.

## 4.5.3. Py4J Finalizer Functions

py4j.finalizer.clear_finalizers(clear_all=False)

  Removes all registered finalizers in `ThreadSafeFinalizer` and `Finalizer`.

  Parameters

    clear_all – If True, all finalizers are deleted. Otherwise, only the finalizers from an empty weak reference are deleted (i.e., weak references pointing to inexistent objects).

### Questions/Feedback?

- Try the FAQ -- It answers many questions.
- Search for information in the archives of the py4j-users mailing list, or post a question.
- If you notice errors with this documentation, open a ticket and let us know. Please, only open a ticket for feedback or improvements on the docs. To get help, use the links above!

### Navigation

- index
- modules |
- next |
- previous |
- Home |
- Download |
- Doc |
- Blog |
- github |
- About »