[Jython-checkins] jython: Various doc- and style-improvements.
stefan.richthofer
jython-checkins at python.org
Fri Feb 13 05:10:07 CET 2015
https://hg.python.org/jython/rev/17d18c6dde96
changeset: 7583:17d18c6dde96
user: Stefan Richthofer <stefan.richthofer at gmx.de>
date: Fri Feb 13 05:09:50 2015 +0100
summary:
Various doc- and style-improvements.
files:
src/org/python/core/PyBytecode.java | 15 +-
src/org/python/core/PyObject.java | 23 +-
src/org/python/core/Traverseproc.java | 18 +-
src/org/python/core/TraverseprocDerived.java | 2 +-
src/org/python/core/finalization/FinalizeTrigger.java | 38 +-
src/org/python/modules/_weakref/AbstractReference.java | 10 +-
src/org/python/modules/_weakref/GlobalRef.java | 33 +-
src/org/python/modules/_weakref/ReferenceType.java | 6 +-
src/org/python/modules/gc.java | 425 +++++++++-
9 files changed, 483 insertions(+), 87 deletions(-)
diff --git a/src/org/python/core/PyBytecode.java b/src/org/python/core/PyBytecode.java
--- a/src/org/python/core/PyBytecode.java
+++ b/src/org/python/core/PyBytecode.java
@@ -164,13 +164,13 @@
enum Why {
- NOT, /* No error */
+ NOT, /* No error */
EXCEPTION, /* Exception occurred */
- RERAISE, /* Exception re-raised by 'finally' */
- RETURN, /* 'return' statement */
- BREAK, /* 'break' statement */
- CONTINUE, /* 'continue' statement */
- YIELD /* 'yield' operator */
+ RERAISE, /* Exception re-raised by 'finally' */
+ RETURN, /* 'return' statement */
+ BREAK, /* 'break' statement */
+ CONTINUE, /* 'continue' statement */
+ YIELD /* 'yield' operator */
};
@@ -1054,7 +1054,8 @@
break;
case Opcode.WITH_CLEANUP: {
- /* TOP is the context.__exit__ bound method.
+ /*
+ TOP is the context.__exit__ bound method.
Below that are 1-3 values indicating how/why
we entered the finally clause:
- SECOND = None
diff --git a/src/org/python/core/PyObject.java b/src/org/python/core/PyObject.java
--- a/src/org/python/core/PyObject.java
+++ b/src/org/python/core/PyObject.java
@@ -20,7 +20,7 @@
/**
* All objects known to the Jython runtime system are represented by an instance
- * of the class <code>PyObject</code> or one of its subclasses.
+ * of the class {@code PyObject} or one of its subclasses.
*/
@ExposedType(name = "object", doc = BuiltinDocs.object_doc)
public class PyObject implements Serializable {
@@ -28,10 +28,14 @@
public static final PyType TYPE = PyType.fromClass(PyObject.class);
/**
- * This should have been suited at org.python.modules.gc, but that would cause
- * a dependency cycle in the init-phases of gc.class and PyObject.class.
- * Now this boolean mirrors the presence of the MONITOR_GLOBAL-flag of
- * Jython's gc module.
+ * This should have been suited at {@link org.python.modules.gc},
+ * but that would cause a dependency cycle in the init-phases of
+ * {@code gc.class} and {@code PyObject.class}. Now this boolean
+ * mirrors the presence of the
+ * {@link org.python.modules.gc#MONITOR_GLOBAL}-flag in Jython's
+ * gc module.<br>
+ * <br>
+ * <b>Do not change manually.</b>
*/
public static boolean gcMonitorGlobal = false;
@@ -45,12 +49,15 @@
* objects can be accessed by the methods and keys in
* {@link org.python.core.JyAttribute}.
* A notable attribute is the javaProxy (accessible via
- * {@code JyAttribute.getAttr(this, JAVA_PROXY_ATTR)}),
+ * {@code JyAttribute.getAttr(this, JyAttribute.JAVA_PROXY_ATTR)}),
* an underlying Java instance that this object is wrapping or is a
* subclass of. Anything attempting to use the proxy should go through
* {@link #getJavaProxy()} which ensures that it's initialized.
+ *
+ * @see org.python.core.JyAttribute
+ * @see org.python.core.JyAttribute#JAVA_PROXY_ATTR
+ * @see #getJavaProxy()
*/
- //protected Object javaProxy;
protected Object attributes;
/** Primitives classes their wrapper classes. */
@@ -1708,7 +1715,6 @@
public PyObject _is(PyObject o) {
// Access javaProxy directly here as is is for object identity, and at best getJavaProxy
// will initialize a new object with a different identity
- //return this == o || (javaProxy != null && javaProxy == o.javaProxy) ? Py.True : Py.False;
return this == o || (JyAttribute.hasAttr(this, JyAttribute.JAVA_PROXY_ATTR) &&
JyAttribute.getAttr(this, JyAttribute.JAVA_PROXY_ATTR) ==
JyAttribute.getAttr(o, JyAttribute.JAVA_PROXY_ATTR)) ? Py.True : Py.False;
@@ -1723,7 +1729,6 @@
public PyObject _isnot(PyObject o) {
// Access javaProxy directly here as is is for object identity, and at best getJavaProxy
// will initialize a new object with a different identity
- //return this != o && (javaProxy == null || javaProxy != o.javaProxy) ? Py.True : Py.False;
return this != o && (!JyAttribute.hasAttr(this, JyAttribute.JAVA_PROXY_ATTR) ||
JyAttribute.getAttr(this, JyAttribute.JAVA_PROXY_ATTR) !=
JyAttribute.getAttr(o, JyAttribute.JAVA_PROXY_ATTR)) ? Py.True : Py.False;
diff --git a/src/org/python/core/Traverseproc.java b/src/org/python/core/Traverseproc.java
--- a/src/org/python/core/Traverseproc.java
+++ b/src/org/python/core/Traverseproc.java
@@ -20,8 +20,7 @@
* tracefunc in {@link org.python.core.PyFrame}).
* PyObjects that don't own references to other PyObjects under any condition
* and neither inherit such references from a superclass are strictly recommended
- * to be annotated {@code {@literal @}Untraversable}
- * (see {@link org.python.core.Untraversable} for details).
+ * to be annotated {@link org.python.core.Untraversable}.
* </p>
* <p>
* Jython's traverse mechanism serves debugging purposes to ease finding memory
@@ -42,14 +41,16 @@
* Note that the slots-array and - if existent - the user-dict of fooDerived classes
* is traversed by {@link org.python.core.TraverseProcDerived}.
* The gc module takes care of exploiting both traverse methods in its static traverse
- * method. So for manual traversion one should always use {@code gc.traverse} rather
+ * method. So for manual traversion one should always use
+ * {@link org.python.modules.gc#traverse(PyObject, Visitproc, Object)} rather
* than directly calling methods in this interface.
* </p>
* <p>
- * Also note that {@code objtype} is not subject to {@code Traverseproc}s
- * by default. In CPython only objects with heap-types traverse their
- * ob_type field. In Jython, {@code fooDerived}-classes are the
- * equivalents of heapTypes. For such classes, objtype is actually
+ * Also note that {@link org.python.core.PyObject#objtype} is not subject to
+ * {@code Traverseproc}s by default. In CPython only objects with heap-types
+ * traverse their {@code ob_type}-field. In Jython, {@code fooDerived}-classes
+ * are the equivalents of heapTypes. For such classes
+ * {@link org.python.core.PyObject#objtype} is actually
* traversed (along with the user dict).
* </p>
* <p>
@@ -439,6 +440,9 @@
* UAdd - no refs, extends PythonTree<br>
* USub - no refs, extends PythonTree<br>
* </p>
+ * @see org.python.core.Untraversable
+ * @see org.python.core.Visitproc
+ * @see org.python.modules.gc#traverse(PyObject, Visitproc, Object)
*/
public interface Traverseproc {
diff --git a/src/org/python/core/TraverseprocDerived.java b/src/org/python/core/TraverseprocDerived.java
--- a/src/org/python/core/TraverseprocDerived.java
+++ b/src/org/python/core/TraverseprocDerived.java
@@ -6,7 +6,7 @@
* {@code fooDerived}-classes. This way we avoid that the traverse
* method of a traversable {@link org.python.core.PyObject} is
* overwritten by the derived version.
- * The {@link org.python.modules.gc}-module takes care of
+ * {@link org.python.modules.gc#traverse(PyObject, Visitproc, Object)} takes care of
* exploiting both traverse methods.
*/
public interface TraverseprocDerived {
diff --git a/src/org/python/core/finalization/FinalizeTrigger.java b/src/org/python/core/finalization/FinalizeTrigger.java
--- a/src/org/python/core/finalization/FinalizeTrigger.java
+++ b/src/org/python/core/finalization/FinalizeTrigger.java
@@ -12,35 +12,15 @@
public class FinalizeTrigger {
/**
* This flag tells the finalize trigger to call
- * gc.notifyFinalize after it called the finalizer.
+ * {@link gc#notifyFinalize(PyObject)} after it called the finalizer.
*/
public static final byte NOTIFY_GC_FLAG = (1<<0);
-
- /**
- * This flag tells the finalize trigger to refrain from actually
- * running the PyObject's {@code __del__} method (or variants for
- * derived or builtins).
- * It can be used to have finalize triggers for debugging and
- * monitoring purposes. The actual purpose is for Jython gc's
- * {@code DONT_FINALIZE_CYCLIC_GARBAGE} flag that tells the gc to emulate
- * CPython's <3.4 policy never to finalize cyclic garbage.
- */
- //public static final byte INHIBIT_FINALIZER_FLAG = (1<<1);
-
- /**
- * Tells the finalizer to add the finalized PyObject to the gc's
- * garbage list. This allows gc to mimic CPython's way to deal
- * with cyclic finalizable objects prior 3.4
- * (c.f. CPython's gc's DEBUG_SAVEALL flag).
- */
- //public static final byte ADD_TO_GARBAGE_LIST_FLAG = (1<<2);
/**
- * Similar to {@code INHIBIT_FINALIZER_FLAG}, but indicates that the
- * underlying PyObject was never intended to be finalized, while
- * {@code INHIBIT_FINALIZER_FLAG} indicates that there actually *is* a
- * finalizer that is just not processed due to special
- * circumstances (i.e. inactive {@code DONT_FINALIZE_CYCLIC_GARBAGE} flag).
+ * Indicates that the underlying PyObject was never intended to be finalized.
+ * It is actually not finalizable and the trigger only exists to notify
+ * {@link org.python.modules.gc} that the underlying object was finalized.
+ * This is needed for some advanced gc-functionality.
*/
public static final byte NOT_FINALIZABLE_FLAG = (1<<3);
@@ -186,7 +166,7 @@
}
}
if ((gc.getJythonGCFlags() & gc.VERBOSE_FINALIZE) != 0) {
- Py.writeDebug("gc", "finalization of "+toFinalize);
+ gc.writeDebug("gc", "finalization of "+toFinalize);
}
if (saveGarbage == 1 || (saveGarbage == 0 &&
(gc.get_debug() & gc.DEBUG_SAVEALL) != 0 && isCyclic())) {
@@ -199,13 +179,13 @@
}
gc.garbage.add(toFinalize);
if ((gc.getJythonGCFlags() & gc.VERBOSE_FINALIZE) != 0) {
- Py.writeDebug("gc", toFinalize+" added to garbage.");
+ gc.writeDebug("gc", toFinalize+" added to garbage.");
}
}
}
if ((flags & NOTIFY_GC_FLAG) != 0) {
if ((gc.getJythonGCFlags() & gc.VERBOSE_FINALIZE) != 0) {
- Py.writeDebug("gc", "notify finalization of "+toFinalize);
+ gc.writeDebug("gc", "notify finalization of "+toFinalize);
}
gc.notifyFinalize(toFinalize);
flags &= ~NOTIFY_GC_FLAG;
@@ -217,7 +197,7 @@
gc.notifyPreFinalization();
if (gc.delayedFinalizationEnabled() && toFinalize != null) {
if ((gc.getJythonGCFlags() & gc.VERBOSE_FINALIZE) != 0) {
- Py.writeDebug("gc", "delayed finalization for "+toFinalize);
+ gc.writeDebug("gc", "delayed finalization for "+toFinalize);
}
gc.registerForDelayedFinalization(toFinalize);
} else {
diff --git a/src/org/python/modules/_weakref/AbstractReference.java b/src/org/python/modules/_weakref/AbstractReference.java
--- a/src/org/python/modules/_weakref/AbstractReference.java
+++ b/src/org/python/modules/_weakref/AbstractReference.java
@@ -84,7 +84,7 @@
return null;
}
if ((gc.getJythonGCFlags() & gc.VERBOSE_WEAKREF) != 0) {
- Py.writeDebug("gc", "pending in get of abstract ref "+this+": "+
+ gc.writeDebug("gc", "pending in get of abstract ref "+this+": "+
Thread.currentThread().getId());
}
JyAttribute.setAttr(this, JyAttribute.WEAKREF_PENDING_GET_ATTR, Thread.currentThread());
@@ -96,14 +96,14 @@
}
JyAttribute.delAttr(this, JyAttribute.WEAKREF_PENDING_GET_ATTR);
if ((gc.getJythonGCFlags() & gc.VERBOSE_WEAKREF) != 0) {
- Py.writeDebug("gc", "pending of "+this+" resolved: "+
+ gc.writeDebug("gc", "pending of "+this+" resolved: "+
Thread.currentThread().getId());
if (gref.cleared) {
- Py.writeDebug("gc", "reference was cleared.");
+ gc.writeDebug("gc", "reference was cleared.");
} else if (result != null){
- Py.writeDebug("gc", "reference was restored.");
+ gc.writeDebug("gc", "reference was restored.");
} else {
- Py.writeDebug("gc", "something went very wrong.");
+ gc.writeDebug("gc", "something went very wrong.");
}
}
return result;
diff --git a/src/org/python/modules/_weakref/GlobalRef.java b/src/org/python/modules/_weakref/GlobalRef.java
--- a/src/org/python/modules/_weakref/GlobalRef.java
+++ b/src/org/python/modules/_weakref/GlobalRef.java
@@ -20,8 +20,8 @@
public class GlobalRef extends WeakReference<PyObject> {
/**
- * This reference's hashCode: the System.identityHashCode of the referent. Only used
- * internally.
+ * This reference's hashCode: The {@code System.identityHashCode} of the referent.
+ * Only used internally.
*/
private int hashCode;
@@ -31,16 +31,19 @@
*/
private int pythonHashCode;
- /** Whether pythonHashCode was already determined. */
+ /** Whether {@link #pythonHashCode} was already determined. */
private boolean havePythonHashCode;
/**
- * 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.
- * {@code gc.PRESERVE_WEAKREFS_ON_RESURRECTION}), {@code AbstractReference.get}
+ * This boolean is set {@code 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.
+ * {@link gc#PRESERVE_WEAKREFS_ON_RESURRECTION}), {@link AbstractReference#get()}
* would block until a consistent state is reached (i.e. referent is
* non-{@code null} or {@code cleared == true}).
+ *
+ * @see gc#PRESERVE_WEAKREFS_ON_RESURRECTION
+ * @see AbstractReference#get()
*/
protected boolean cleared = false;
@@ -108,7 +111,10 @@
}
/**
- * Call all callbacks that were enqueued via delayedCallback method.
+ * Call all callbacks that were enqueued via
+ * {@link #delayedCallback(GlobalRef)} method.
+ *
+ * @see #delayedCallback(GlobalRef)
*/
public static void processDelayedCallbacks() {
if (delayedCallbacks != null) {
@@ -124,9 +130,11 @@
/**
* Stores the callback for later processing. This is needed if
* weak reference restoration (c.f.
- * {@code gc.PRESERVE_WEAKREFS_ON_RESURRECTION})
+ * {@link gc#PRESERVE_WEAKREFS_ON_RESURRECTION})
* is active. In this case the callback is delayed until it was
* determined whether a resurrection restored the reference.
+ *
+ * @see gc#PRESERVE_WEAKREFS_ON_RESURRECTION
*/
private static void delayedCallback(GlobalRef cl) {
if (delayedCallbacks == null) {
@@ -196,6 +204,9 @@
* If the given {@link org.python.core.PyObject} is not the former
* referent of this weak reference, an
* {@link java.lang.IllegalArgumentException} is thrown.
+ *
+ * @throws java.lang.IllegalArgumentException if {@code formerReferent} is not
+ * the actual former referent.
*/
public void restore(PyObject formerReferent) {
if (JyAttribute.getAttr(formerReferent, JyAttribute.WEAK_REF_ATTR) != this) {
@@ -265,8 +276,8 @@
* Return a list of references to the specified
* {@link org.python.core.PyObject}.
*
- * @param object a PyObject
- * @return a PyList of references. may be empty
+ * @param object a {@link org.python.core.PyObject}
+ * @return a {@link org.python.core.PyList} of references. May be empty.
*/
public static PyList getRefs(PyObject object) {
GlobalRef ref = objects.get(new GlobalRef(object));
diff --git a/src/org/python/modules/_weakref/ReferenceType.java b/src/org/python/modules/_weakref/ReferenceType.java
--- a/src/org/python/modules/_weakref/ReferenceType.java
+++ b/src/org/python/modules/_weakref/ReferenceType.java
@@ -68,9 +68,9 @@
* to passthru).
*
* @param funcName the name of the caller
- * @param args PyObject array of args
- * @param keywords String array of keywords
- * @return an ArgParser instance
+ * @param args {@link or.python.core.PyObject} array of args
+ * @param keywords {@code String}-array of keywords
+ * @return an {@link or.python.core.ArgParser} instance
*/
private static ArgParser parseInitArgs(String funcName, PyObject[] args, String[] keywords) {
if (keywords.length > 0) {
diff --git a/src/org/python/modules/gc.java b/src/org/python/modules/gc.java
--- a/src/org/python/modules/gc.java
+++ b/src/org/python/modules/gc.java
@@ -18,6 +18,7 @@
import org.python.core.PyList;
import org.python.core.PyObject;
import org.python.core.PyInstance;
+import org.python.core.PyString;
import org.python.core.Traverseproc;
import org.python.core.TraverseprocDerived;
import org.python.core.Visitproc;
@@ -25,9 +26,11 @@
import org.python.core.finalization.FinalizeTrigger;
import org.python.modules._weakref.GlobalRef;
+import com.sun.management.GarbageCollectionNotificationInfo;
+
public class gc {
/**
- * A constant that can occur as result of {@code gc.collect} and
+ * A constant that can occur as result of {@link #collect()} and
* indicates an unknown number of collected cyclic trash.
* It is intentionally not valued -1 as that value is
* reserved to indicate an error.
@@ -36,9 +39,14 @@
/* Jython-specific gc-flags: */
/**
- * Tells every newly created PyObject to register for
- * gc-monitoring. This allows {@code gc.collect} to report the
+ * This flag tells every newly created PyObject to register for
+ * gc-monitoring. This allows {@link #collect()} to report the
* number of collected objects.
+ *
+ * @see #setJythonGCFlags(short)
+ * @see #getJythonGCFlags()
+ * @see #addJythonGCFlags(short)
+ * @see #removeJythonGCFlags(short)
*/
public static final short MONITOR_GLOBAL = (1<<0);
@@ -47,6 +55,11 @@
* PyObjects, while Jython does this by default. This flag
* tells Jython's gc to mimic CPython <3.4 behavior (i.e.
* add such objects to {@code gc.garbage} list instead).
+ *
+ * @see #setJythonGCFlags(short)
+ * @see #getJythonGCFlags()
+ * @see #addJythonGCFlags(short)
+ * @see #removeJythonGCFlags(short)
*/
public static final short DONT_FINALIZE_CYCLIC_GARBAGE = (1<<1);
@@ -65,6 +78,11 @@
* delay garbage collection of some weak referenced objects
* for several gc cycles if activated. So we recommend to
* use it only for debugging.
+ *
+ * @see #setJythonGCFlags(short)
+ * @see #getJythonGCFlags()
+ * @see #addJythonGCFlags(short)
+ * @see #removeJythonGCFlags(short)
*/
public static final short PRESERVE_WEAKREFS_ON_RESURRECTION = (1<<2);
@@ -80,6 +98,11 @@
* significant cost as it can delay collection of many objects
* for several gc-cycles. Its main intention is for debugging
* resurrection-sensitive code.
+ *
+ * @see #setJythonGCFlags(short)
+ * @see #getJythonGCFlags()
+ * @see #addJythonGCFlags(short)
+ * @see #removeJythonGCFlags(short)
*/
public static final short DONT_FINALIZE_RESURRECTED_OBJECTS = (1<<3);
@@ -88,6 +111,11 @@
* is deactivated by default for now. This means that
* {@code DONT_TRAVERSE_BY_REFLECTION} is set by default.
* Once it is stable, reflection-based traversion will be active by default.
+ *
+ * @see #setJythonGCFlags(short)
+ * @see #getJythonGCFlags()
+ * @see #addJythonGCFlags(short)
+ * @see #removeJythonGCFlags(short)
*/
public static final short DONT_TRAVERSE_BY_REFLECTION = (1<<4);
@@ -109,6 +137,11 @@
* This is because in an ideal implementation reflection-based traversion never
* occurs; it is only an inefficient fallback.
* </p>
+ *
+ * @see #setJythonGCFlags(short)
+ * @see #getJythonGCFlags()
+ * @see #addJythonGCFlags(short)
+ * @see #removeJythonGCFlags(short)
*/
public static final short SUPPRESS_TRAVERSE_BY_REFLECTION_WARNING = (1<<5);
@@ -119,14 +152,65 @@
* gc-messages, no matter what overall verbose level is selected.
* This flag tells Jython to use {@code Py.writeDebug} for debugging output.
* If it is not set (default-case), gc-debugging output (if gc-{@code VERBOSE}
- * or -{@code DEBUG} flags are set) is directly written to {@code System.err}.
+ * or -{@code DEBUG} flags are set) is directly written to {@code System.err}.
+ *
+ * @see #setJythonGCFlags(short)
+ * @see #getJythonGCFlags()
+ * @see #addJythonGCFlags(short)
+ * @see #removeJythonGCFlags(short)
*/
public static final short USE_PY_WRITE_DEBUG = (1<<6);
+ /**
+ * Enables collection-related verbose-output.
+ *
+ * @see #setJythonGCFlags(short)
+ * @see #getJythonGCFlags()
+ * @see #addJythonGCFlags(short)
+ * @see #removeJythonGCFlags(short)
+ */
public static final short VERBOSE_COLLECT = (1<<7);
+
+ /**
+ * Enables weakref-related verbose-output.
+ *
+ * @see #setJythonGCFlags(short)
+ * @see #getJythonGCFlags()
+ * @see #addJythonGCFlags(short)
+ * @see #removeJythonGCFlags(short)
+ */
public static final short VERBOSE_WEAKREF = (1<<8);
+
+ /**
+ * Enables delayed finalization related verbose-output.
+ *
+ * @see #setJythonGCFlags(short)
+ * @see #getJythonGCFlags()
+ * @see #addJythonGCFlags(short)
+ * @see #removeJythonGCFlags(short)
+ */
public static final short VERBOSE_DELAYED = (1<<9);
+
+ /**
+ * Enables finalization-related verbose-output.
+ *
+ * @see #setJythonGCFlags(short)
+ * @see #getJythonGCFlags()
+ * @see #addJythonGCFlags(short)
+ * @see #removeJythonGCFlags(short)
+ */
public static final short VERBOSE_FINALIZE = (1<<10);
+
+ /**
+ * Bit-combination of the flags {@link #VERBOSE_COLLECT},
+ * {@link #VERBOSE_WEAKREF}, {@link #VERBOSE_DELAYED},
+ * {@link #VERBOSE_FINALIZE}.
+ *
+ * @see #setJythonGCFlags(short)
+ * @see #getJythonGCFlags()
+ * @see #addJythonGCFlags(short)
+ * @see #removeJythonGCFlags(short)
+ */
public static final short VERBOSE =
VERBOSE_COLLECT | VERBOSE_WEAKREF | VERBOSE_DELAYED | VERBOSE_FINALIZE;
@@ -134,38 +218,65 @@
/**
* print collection statistics
* (in Jython scoped on monitored objects)
+ *
+ * @see #set_debug(int)
+ * @see #get_debug()
*/
public static final int DEBUG_STATS = (1<<0);
/**
* print collectable objects
* (in Jython scoped on monitored objects)
+ *
+ * @see #set_debug(int)
+ * @see #get_debug()
*/
public static final int DEBUG_COLLECTABLE = (1<<1);
/**
* print uncollectable objects
* (in Jython scoped on monitored objects)
+ *
+ * @see #set_debug(int)
+ * @see #get_debug()
*/
public static final int DEBUG_UNCOLLECTABLE = (1<<2);
/**
* print instances
* (in Jython scoped on monitored objects)
+ *
+ * @see #set_debug(int)
+ * @see #get_debug()
*/
public static final int DEBUG_INSTANCES = (1<<3);
/**
* print other objects
* (in Jython scoped on monitored objects)
+ *
+ * @see #set_debug(int)
+ * @see #get_debug()
*/
public static final int DEBUG_OBJECTS = (1<<4);
/**
* save all garbage in gc.garbage
* (in Jython scoped on monitored objects)
+ *
+ * @see #set_debug(int)
+ * @see #get_debug()
*/
public static final int DEBUG_SAVEALL = (1<<5);
+
+ /**
+ * Bit-combination of the flags {@link #DEBUG_COLLECTABLE},
+ * {@link #DEBUG_UNCOLLECTABLE}, {@link #DEBUG_INSTANCES},
+ * {@link #DEBUG_OBJECTS}, {@link #DEBUG_SAVEALL}.
+ *
+ * @see #set_debug(int)
+ * @see #get_debug()
+ */
public static final int DEBUG_LEAK = DEBUG_COLLECTABLE |
DEBUG_UNCOLLECTABLE |
DEBUG_INSTANCES |
@@ -184,6 +295,10 @@
private static long lastRemoveTimeStamp = -1, maxWaitTime = initWaitTime;
private static int gcMonitoredRunCount = 0;
public static long gcRecallTime = 4000;
+
+ /**
+ * list of uncollectable objects
+ */
public static PyList garbage = new PyList();
//Finalization preprocess/postprocess-related declarations:
@@ -207,17 +322,113 @@
private static boolean notifyRerun = false;
public static final String __doc__ =
- "This module provides access to the garbage collector.\n" +
+ "This module provides access to the garbage collector for reference cycles.\n" +
"\n" +
- "enable() -- Enable automatic garbage collection (does nothing).\n" +
+ "enable() -- Enable automatic garbage collection (does nothing in Jython).\n" +
+ "disable() -- Disable automatic garbage collection (raises NotImplementedError in Jython).\n" +
"isenabled() -- Returns True because Java garbage collection cannot be disabled.\n" +
- "collect() -- Trigger a Java garbage collection (potentially expensive).\n" +
- "get_debug() -- Get debugging flags (returns 0).\n" +
- "\n" +
- "Other functions raise NotImplementedError because they do not apply to Java.\n";
+ "collect() -- Do a full collection right now (potentially expensive).\n" +
+ "get_count() -- Return the current collection counts (raises NotImplementedError in Jython).\n" +
+ "set_debug() -- Set debugging flags.\n" +
+ "get_debug() -- Get debugging flags.\n" +
+ "set_threshold() -- Set the collection thresholds (raise NotImplementedError in Jython).\n" +
+ "get_threshold() -- Return the current the collection thresholds (raise NotImplementedError in Jython).\n" +
+ "get_objects() -- Return a list of all objects tracked by the collector (raises NotImplementedError in Jython).\n" +
+ "is_tracked() -- Returns true if a given object is tracked (i.e. monitored in Jython).\n" +
+ "get_referrers() -- Return the list of objects that refer to an object (only finds monitored referrers in Jython).\n" +
+ "get_referents() -- Return the list of objects that an object refers to.\n";
public static final String __name__ = "gc";
+ public static final PyString __doc__enable = new PyString(
+ "enable() -> None\n" +
+ "\n" +
+ "Enable automatic garbage collection.\n" +
+ "(does nothing in Jython)\n");
+
+ public static final PyString __doc__disable = new PyString(
+ "disable() -> None\n" +
+ "\n" +
+ "Disable automatic garbage collection.\n" +
+ "(raises NotImplementedError in Jython)\n");
+
+ public static final PyString __doc__isenabled = new PyString(
+ "isenabled() -> status\n" +
+ "\n" +
+ "Returns true if automatic garbage collection is enabled.\n");
+
+ public static final PyString __doc__collect = new PyString(
+ "collect([generation]) -> n\n" +
+ "\n" +
+ "With no arguments, run a full collection. The optional argument\n" +
+ "may be an integer specifying which generation to collect. A ValueError\n" +
+ "is raised if the generation number is invalid.\n\n" +
+ "The number of unreachable objects is returned.\n" +
+ "(Jython emulates CPython cyclic trash counting if objects are monitored.\n" +
+ "If no objects are monitored, returns -2\n");
+
+ public static final PyString __doc__get_count = new PyString(
+ "get_count() -> (count0, count1, count2)\n" +
+ "\n" +
+ "Return the current collection counts\n" +
+ "(raises NotImplementedError in Jython)\n");
+
+ public static final PyString __doc__set_debug = new PyString(
+ "set_debug(flags) -> None\n" +
+ "\n" +
+ "Set the garbage collection debugging flags. Debugging information is\n" +
+ "written to sys.stderr.\n" +
+ "\n" +
+ "flags is an integer and can have the following bits turned on:\n" +
+ "\n" +
+ " DEBUG_STATS - Print statistics during collection.\n" +
+ " DEBUG_COLLECTABLE - Print collectable objects found.\n" +
+ " DEBUG_UNCOLLECTABLE - Print unreachable but uncollectable objects found.\n" +
+ " DEBUG_INSTANCES - Print instance objects.\n" +
+ " DEBUG_OBJECTS - Print objects other than instances.\n" +
+ " DEBUG_SAVEALL - Save objects to gc.garbage rather than freeing them.\n" +
+ " DEBUG_LEAK - Debug leaking programs (everything but STATS).\n");
+
+ public static final PyString __doc__get_debug = new PyString(
+ "get_debug() -> flags\n" +
+ "\n" +
+ "Get the garbage collection debugging flags.\n");
+
+ public static final PyString __doc__set_thresh = new PyString(
+ "set_threshold(threshold0, [threshold1, threshold2]) -> None\n" +
+ "\n" +
+ "Sets the collection thresholds. Setting threshold0 to zero disables\n" +
+ "collection.\n" +
+ "(raises NotImplementedError in Jython)\n");
+
+ public static final PyString __doc__get_thresh = new PyString(
+ "get_threshold() -> (threshold0, threshold1, threshold2)\n" +
+ "\n" +
+ "Return the current collection thresholds\n" +
+ "(raises NotImplementedError in Jython)\n");
+
+ public static final PyString __doc__get_objects = new PyString(
+ "get_objects() -> [...]\n" +
+ "\n" +
+ "Return a list of objects tracked by the collector (excluding the list\n" +
+ "returned).\n" +
+ "(raises NotImplementedError in Jython)\n");
+
+ public static final PyString __doc__is_tracked = new PyString(
+ "is_tracked(obj) -> bool\n" +
+ "\n" +
+ "Returns true if the object is tracked by the garbage collector.\n" +
+ "(i.e. monitored in Jython)\n");
+
+ public static final PyString __doc__get_referrers = new PyString(
+ "get_referrers(*objs) -> list\n" +
+ "Return the list of objects that directly refer to any of objs.\n" +
+ "(only finds monitored referrers in Jython)");
+
+ public static final PyString __doc__get_referents = new PyString(
+ "get_referents(*objs) -> list\n" +
+ "Return the list of objects that are directly referred to by objs.");
+
public static class CycleMarkAttr {
private boolean cyclic = false;
@@ -382,7 +593,17 @@
}
}
- private static void writeDebug(String type, String msg) {
+ /**
+ * Works like {@link org.python.core.Py#writeDebug(String, String)},
+ * but prints to {@link org.python.core.Py#writeDebug(String, String)}
+ * (i.e. subject to Jython's verbose level)
+ * or directly to {@code System.err}, according to
+ * {@link #USE_PY_WRITE_DEBUG}.
+ *
+ * @see #USE_PY_WRITE_DEBUG
+ * @see org.python.core.Py#writeDebug(String, String)
+ */
+ public static void writeDebug(String type, String msg) {
if ((gcFlags & USE_PY_WRITE_DEBUG) != 0) {
Py.writeDebug(type, msg);
} else {
@@ -1102,6 +1323,25 @@
//----------end of Monitoring section--------------------------------------
+ /**
+ * Gets the current Jython-specific gc-flags.
+ *
+ * @see #MONITOR_GLOBAL
+ * @see #DONT_FINALIZE_CYCLIC_GARBAGE
+ * @see #PRESERVE_WEAKREFS_ON_RESURRECTION
+ * @see #DONT_FINALIZE_RESURRECTED_OBJECTS
+ * @see #DONT_TRAVERSE_BY_REFLECTION
+ * @see #SUPPRESS_TRAVERSE_BY_REFLECTION_WARNING
+ * @see #USE_PY_WRITE_DEBUG
+ * @see #VERBOSE_COLLECT
+ * @see #VERBOSE_WEAKREF
+ * @see #VERBOSE_DELAYED
+ * @see #VERBOSE_FINALIZE
+ * @see #VERBOSE
+ * @see #setJythonGCFlags(short)
+ * @see #addJythonGCFlags(short)
+ * @see #removeJythonGCFlags(short)
+ */
public static short getJythonGCFlags() {
if (((gcFlags & MONITOR_GLOBAL) != 0) != PyObject.gcMonitorGlobal) {
if (PyObject.gcMonitorGlobal) {
@@ -1113,6 +1353,44 @@
return gcFlags;
}
+ /**
+ * Sets the current Jython-specific gc-flags.
+ * <br>
+ * {@code flags} is a {@code short} and can have the following bits turned on:<br>
+ * <br>
+ * {@link #MONITOR_GLOBAL} - Automatically monitors all PyObjects created from now on.<br>
+ * {@link #DONT_FINALIZE_CYCLIC_GARBAGE} - Adds cyclic finalizable PyObjects to {@link #garbage}.<br>
+ * {@link #PRESERVE_WEAKREFS_ON_RESURRECTION} - Keeps weak references alive if the referent is resurrected.<br>
+ * {@link #DONT_FINALIZE_RESURRECTED_OBJECTS} -
+ * Emulates CPython behavior regarding resurrected objects and finalization.<br>
+ * {@link #DONT_TRAVERSE_BY_REFLECTION} - Inhibits reflection-based traversion.<br>
+ * {@link #SUPPRESS_TRAVERSE_BY_REFLECTION_WARNING} -
+ * Suppress warnings for PyObjects that neither implement {@link org.python.core.Traverseproc} nor
+ * are marked as {@link org.python.core.Untraversable}.<br>
+ * {@link #USE_PY_WRITE_DEBUG} - uses {@link org.python.core.Py#writeDebug(String, String)} for
+ * debugging output instead of directly writing to {@link java.lang.System#err}.<br>
+ * {@link #VERBOSE_COLLECT} - Enable collection-related verbose output.<br>
+ * {@link #VERBOSE_WEAKREF} - Enable weakref-related verbose output.<br>
+ * {@link #VERBOSE_DELAYED} - Enable delayed finalization-related verbose output.<br>
+ * {@link #VERBOSE_FINALIZE} - Enable finalization-related verbose output.<br>
+ * {@link #VERBOSE} - All previous verbose-flags combined.
+ *
+ * @see #MONITOR_GLOBAL
+ * @see #DONT_FINALIZE_CYCLIC_GARBAGE
+ * @see #PRESERVE_WEAKREFS_ON_RESURRECTION
+ * @see #DONT_FINALIZE_RESURRECTED_OBJECTS
+ * @see #DONT_TRAVERSE_BY_REFLECTION
+ * @see #SUPPRESS_TRAVERSE_BY_REFLECTION_WARNING
+ * @see #USE_PY_WRITE_DEBUG
+ * @see #VERBOSE_COLLECT
+ * @see #VERBOSE_WEAKREF
+ * @see #VERBOSE_DELAYED
+ * @see #VERBOSE_FINALIZE
+ * @see #VERBOSE
+ * @see #getJythonGCFlags()
+ * @see #addJythonGCFlags(short)
+ * @see #removeJythonGCFlags(short)
+ */
public static void setJythonGCFlags(short flags) {
gcFlags = flags;
PyObject.gcMonitorGlobal = (gcFlags & MONITOR_GLOBAL) != 0;
@@ -1121,6 +1399,22 @@
/**
* This is a convenience method to add flags via bitwise or.
+ *
+ * @see #MONITOR_GLOBAL
+ * @see #DONT_FINALIZE_CYCLIC_GARBAGE
+ * @see #PRESERVE_WEAKREFS_ON_RESURRECTION
+ * @see #DONT_FINALIZE_RESURRECTED_OBJECTS
+ * @see #DONT_TRAVERSE_BY_REFLECTION
+ * @see #SUPPRESS_TRAVERSE_BY_REFLECTION_WARNING
+ * @see #USE_PY_WRITE_DEBUG
+ * @see #VERBOSE_COLLECT
+ * @see #VERBOSE_WEAKREF
+ * @see #VERBOSE_DELAYED
+ * @see #VERBOSE_FINALIZE
+ * @see #VERBOSE
+ * @see #getJythonGCFlags()
+ * @see #setJythonGCFlags(short)
+ * @see #removeJythonGCFlags(short)
*/
public static void addJythonGCFlags(short flags) {
gcFlags |= flags;
@@ -1130,6 +1424,22 @@
/**
* This is a convenience method to remove flags via bitwise and-not.
+ *
+ * @see #MONITOR_GLOBAL
+ * @see #DONT_FINALIZE_CYCLIC_GARBAGE
+ * @see #PRESERVE_WEAKREFS_ON_RESURRECTION
+ * @see #DONT_FINALIZE_RESURRECTED_OBJECTS
+ * @see #DONT_TRAVERSE_BY_REFLECTION
+ * @see #SUPPRESS_TRAVERSE_BY_REFLECTION_WARNING
+ * @see #USE_PY_WRITE_DEBUG
+ * @see #VERBOSE_COLLECT
+ * @see #VERBOSE_WEAKREF
+ * @see #VERBOSE_DELAYED
+ * @see #VERBOSE_FINALIZE
+ * @see #VERBOSE
+ * @see #getJythonGCFlags()
+ * @see #setJythonGCFlags(short)
+ * @see #addJythonGCFlags(short)
*/
public static void removeJythonGCFlags(short flags) {
gcFlags &= ~flags;
@@ -1161,21 +1471,34 @@
notifyFinalize(abort);
}
+ /**
+ * Does nothing in Jython as Java-gc is always enabled.
+ */
public static void enable() {}
+ /**
+ * Not supported by Jython.
+ * Throws {@link org.python.core.Py#NotImplementedError}.
+ *
+ * @throws org.python.core.Py#NotImplementedError
+ */
public static void disable() {
throw Py.NotImplementedError("can't disable Java GC");
}
+ /**
+ * Always returns {@code true} in Jython.
+ */
public static boolean isenabled() { return true; }
/**
* The generation parameter is only for compatibility with
- * CPython {@code gc.collect} and is ignored.
+ * CPython {@link gc.collect()} and is ignored.
* @param generation (ignored)
* @return Collected monitored cyclic trash-objects or
* {@code gc.UNKNOWN_COUNT} if nothing is monitored or -1 if
* an error occurred and collection did not complete.
+ * @see #collect()
*/
public static int collect(int generation) {
return collect();
@@ -1194,14 +1517,16 @@
/**
* If no objects are monitored, this just delegates to
- * {@code System.gc} and returns {@code gc.UNKNOWN_COUNT} as a
+ * {@code System.gc()} and returns {@link #UNKNOWN_COUNT} as a
* non-erroneous default value. If objects are monitored,
- * it emulates a synchronous gc run in the sense that it waits
+ * it emulates a synchronous gc-run in the sense that it waits
* until all collected monitored objects were finalized.
*
* @return Number of collected monitored cyclic trash-objects
- * or {@code gc.UNKNOWN_COUNT} if nothing is monitored or -1
+ * or {@link #UNKNOWN_COUNT} if nothing is monitored or -1
* if an error occurred and collection did not complete.
+ * @see #UNKNOWN_COUNT
+ * @see #collect(int)
*/
public static int collect() {
try {
@@ -1619,26 +1944,79 @@
stat[1] -= abortedCyclicFinalizers;
}
+ /**
+ * Not supported by Jython.
+ * Throws {@link org.python.core.Py#NotImplementedError}.
+ *
+ * @throws org.python.core.Py#NotImplementedError
+ */
public static PyObject get_count() {
throw Py.NotImplementedError("not applicable to Java GC");
}
+ /**
+ * Copied from CPython-doc:<br>
+ * <br>
+ * Set the garbage collection debugging flags. Debugging information is
+ * written to {@code System.err}.<br>
+ * <br>
+ * {@flags} flags is an {@code int}eger and can have the following bits turned on:<br>
+ * <br>
+ * {@link #DEBUG_STATS} - Print statistics during collection.<br>
+ * {@link #DEBUG_COLLECTABLE} - Print collectable objects found.<br>
+ * {@link #DEBUG_UNCOLLECTABLE} - Print unreachable but uncollectable objects found.<br>
+ * {@link #DEBUG_INSTANCES} - Print instance objects.<br>
+ * {@link #DEBUG_OBJECTS} - Print objects other than instances.<br>
+ * {@link #DEBUG_SAVEALL} - Save objects to gc.garbage rather than freeing them.<br>
+ * {@link #DEBUG_LEAK} - Debug leaking programs (everything but STATS).
+ *
+ * @see #DEBUG_STATS
+ * @see #DEBUG_COLLECTABLE
+ * @see #DEBUG_UNCOLLECTABLE
+ * @see #DEBUG_INSTANCES
+ * @see #DEBUG_OBJECTS
+ * @see #DEBUG_SAVEALL
+ * @see #DEBUG_LEAK
+ */
public static void set_debug(int flags) {
debugFlags = flags;
}
+ /**
+ * Copied from CPython-doc:<br>
+ * <br>
+ * Get the garbage collection debugging flags.
+ */
public static int get_debug() {
return debugFlags;
}
+ /**
+ * Not supported by Jython.
+ * Throws {@link org.python.core.Py#NotImplementedError}.
+ *
+ * @throws org.python.core.Py#NotImplementedError
+ */
public static void set_threshold(PyObject[] args, String[] kwargs) {
throw Py.NotImplementedError("not applicable to Java GC");
}
+ /**
+ * Not supported by Jython.
+ * Throws {@link org.python.core.Py#NotImplementedError}.
+ *
+ * @throws org.python.core.Py#NotImplementedError
+ */
public static PyObject get_threshold() {
throw Py.NotImplementedError("not applicable to Java GC");
}
+ /**
+ * Not supported by Jython.
+ * Throws {@link org.python.core.Py#NotImplementedError}.
+ *
+ * @throws org.python.core.Py#NotImplementedError
+ */
public static PyObject get_objects() {
throw Py.NotImplementedError("not applicable to Java GC");
}
@@ -2007,6 +2385,23 @@
return search;
}
+ /**
+ * Does its best to traverse the given {@link org.python.core.PyObject}
+ * {@code ob}. It exploits both
+ * {@link org.python.core.Traverseproc#traverse(Visitproc, Object)} and
+ * {@link org.python.core.TraverseprocDerived#traverseDerived(Visitproc, Object)}.
+ * If {@code ob} neither implements {@link org.python.core.Traverseproc} nor
+ * {@link org.python.core.Traverseproc} and is not annotated with
+ * {@link org.python.core.Untraversable}, reflection-based traversion via
+ * {@link #traverseByReflection(Object, Visitproc, Object)} may be attempted
+ * according to {@link #DONT_TRAVERSE_BY_REFLECTION}.
+ *
+ * @see org.python.core.Traverseproc#traverse(Visitproc, Object)
+ * @see org.python.core.TraverseprocDerived#traverseDerived(Visitproc, Object)
+ * @see #DONT_TRAVERSE_BY_REFLECTION
+ * @see org.python.core.Untraversable
+ * @see #traverseByReflection(Object, Visitproc, Object)
+ */
public static int traverse(PyObject ob, Visitproc visit, Object arg) {
int retVal;
boolean traversed = false;
--
Repository URL: https://hg.python.org/jython
More information about the Jython-checkins
mailing list