Make weak references somewhat leaner, and (I think) make it possible to

implement with reasonable effort in Jython.

pep-0205.txt

@@ -75,7 +75,7 @@ Proposed Solution
     files, etc.).
 
     A new module, weakref, will contain new functions used to create
-    weak references.  weakref.new() will create a "weak reference
+    weak references.  weakref.ref() will create a "weak reference
     object" and optionally attach a callback which will be called when
     the object is about to be finalized.  weakref.mapping() will
     create a "weak dictionary".  A third function, weakref.proxy(),
@@ -84,22 +84,15 @@ Proposed Solution
 
     A weak reference object will allow access to the referenced object
     if it hasn't been collected and to determine if the object still
-    exists in memory.  These operations are accessed via the .get()
+    exists in memory.  Retrieving the referent is done by calling the
-    and .islive() methods.  If the object has been collected, .get()
+    reference object.  If the referent is no longer alive, this will
-    will return None and islive() will return false.  Weak references
+    return None instead.
-    are not hashable.
 
     A weak dictionary maps arbitrary keys to values, but does not own
     a reference to the values.  When the values are finalized, the
     (key, value) pairs for which it is a value are removed from all
-    the mappings containing such pairs.  These mapping objects provide
+    the mappings containing such pairs.  Like dictionaries, weak
-    an additional method, .setitem(), which accepts a key, value, and
+    dictionaries are not hashable.
-    optional callback which will be called when the object is removed
-    from the mapping.  If the object is removed from the mapping by
-    deleting the entry by key or calling the mapping's .clear()
-    method, the callback is not called (since the object is not about
-    to be finalized), and will be unregistered from the object.  Like
-    dictionaries, weak dictionaries are not hashable.
 
     Proxy objects are weak references that attempt to behave like the
     object they proxy, as much as they can.  Regardless of the
@@ -115,11 +108,8 @@ Proposed Solution
     work, but always refer to the proxy and not the referent.
 
     The callbacks registered with weak references must accept a single
-    parameter, which will be the weak-ly referenced object itself.
+    parameter, which will be the weakly referenced object itself.  The
-    The object can be resurrected by creating some other reference to
+    object cannot be resurrected in the callback.
-    the object in the callback, in which case the weak reference
-    generating the callback will still be cleared but no remaining
-    weak references to the object will be cleared.
 
 
 Implementation Strategy
@@ -128,19 +118,17 @@ Implementation Strategy
     reference containers that must be cleared for each weakly-
     referencable object.  If the reference is from a weak dictionary,
     the dictionary entry is cleared first.  Then, any associated
-    callback is called with the object passed as a parameter.  If the
+    callback is called with the object passed as a parameter.  Once
-    callback generates additional references, no further callbacks are
+    all callbacks have been called, the object is finalized and
-    called and the object is resurrected.  Once all callbacks have
+    deallocated.
-    been called and the object has not been resurrected, it is
-    finalized and deallocated.
 
     Many built-in types will participate in the weak-reference
     management, and any extension type can elect to do so.  The type
     structure will contain an additional field which provides an
     offset into the instance structure which contains a list of weak
     reference structures.  If the value of the field is <= 0, the
-    object does not participate.  In this case, weakref.new(),
+    object does not participate.  In this case, weakref.ref(),
-    <weakdict>.setitem(), .setdefault(), and item assignment will
+    <weakdict>.__setitem__() and .setdefault(), and item assignment will
     raise TypeError.  If the value of the field is > 0, a new weak
     reference can be generated and added to the list.
 
@@ -242,7 +230,12 @@ Weak References in Java
     equivalent, or if soft references are only cleared when malloc()
     returns NULL.
 
-    XXX -- Need to figure out what phantom references are all about.
+    "Phantom" references are a little different; unlike weak and soft
+    references, the referent is not cleared when the reference is
+    added to it's queue.  When all phantom references for an object
+    are dequeued, the object is cleared.  This can be used to keep an
+    object alive until some additional cleanup is performed which
+    needs to happen before the objects .finalize() method is called.
 
     Unlike the other two reference types, "phantom" references must be
     associated with an invalidation queue.