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
protected boolean	cleared This boolean is set true when the callback is processed.
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

Modifier and Type	Method and Description
void	add(AbstractReference ref)
int	count()
boolean	equals(java.lang.Object o) Allow GlobalRefs 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 AbstractReference wrapper.
PyList	refs()
void	restore(PyObject formerReferent) Restores this weak reference to its former referent.
protected ReferenceBackend	retryFactory() Returns null if nothing is changed.

Methods inherited from class java.lang.ref.Reference

clear, enqueue, get, isEnqueued

Methods inherited from class java.lang.Object

clone, finalize, 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.

cleared

protected boolean cleared

This boolean is set true when the callback is processed. If the reference is cleared it might potentially be restored until this boolean is set true. If weak reference restoring is activated (c.f. gc.PRESERVE_WEAKREFS_ON_RESURRECTION), AbstractReference.get() would block until a consistent state is reached (i.e. referent is non-null or cleared == true).

See Also:

gc.PRESERVE_WEAKREFS_ON_RESURRECTION, AbstractReference.get()

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

retryFactory

protected ReferenceBackend retryFactory()

Returns null if nothing is changed. If a factory exists and produces a result different from this, this result is returned. Also, this result is then installed in all weak-references, in the referent's JyAttribute and in the objects-map to act as a proxy for this GlobalRef, which will still serve as a backend for the proxy. This method is most likely used exclusively by JyNI.

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 AbstractReferences. 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 GlobalRefs 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