instead of listcomps.  Added new examples.  Corrected minor mistakes.
Removed the byValue() example and claimed that function is deprecated
(it's almost never used, and it's hard to explain exactly what it does).

Windows will have fsync() starting with 2.2.3.

If asyncore is not running in a separate thread, the client needs to
call poll() to perform the IO necessary for cache verification to
finish.

This allows us to eliminate several calls to sync() in the test suite.

XXX I've got no idea what this is actually supposed to do.  It may be
that clearing the old cache isn't safe, but only if it never was.  If
a non-ghost object is in the cache, it seems that attempts to use it
will go through the wrong cache.

Problem reported by Ulla Theiss and diagnosed by Shane Hathaway.  The
long and short of it is that persistent objects refer to their
connection which refers to its cache which refers to the persistent
objects.  We can't let GC find the cycle because persistent objects
are extension class objects, and, thus, don't participate in GC.

Add an explicit clear() method that removes non-ghost objects from the
ring without going to all the trouble of ghosting them.  At some
point, they'll just get deallocated (which will ghostify them).

A cleared cache has non-ghost objects in the dict that are not in the
ring, so we need to add some checks for whether the object is actually
in the ring.

the 'name' attr is '#PCDATA' not '#NMTOKEN', because name fields need to
allow the '*' or '+' sign in the content.

recursively to avoid blowing up when a tuple contains a really long
string (e.g. 100 MB in size).

states when the value passed in was of the wrong type (for example,
doing
    b[obj] = 3.7
when b is an OIBTree).  This manifested as a refcount leak in the test
suite, but could have been much worse (most likely in real life is that
a seemingly arbitrary existing key would "go missing").

bucket when deleting the first child of a BTree node with more than one
child.  This caused >600 int objects to leak in the OI and OO flavors
of testRemoveSucceeds.

BTree_lastBucket().  In unusual cases, this could cause a chain of buckets
to leak (the DegenerateBTree tests appeared to be the only ones that
provoked this, and there it leaked 285 IISet buckets).  Other uses of
BTree_lastBucket() appear to be refcount-correct.

Don't know what happened, but the tests started running very slowly
with Python2.3.  Fixed by checking _ready at the start of the loop in
_wait() instead of at the bottom.  Most of the time _ready is set by
the time we start, and no more I/O is going to occur until the client
connects; as a result, the tests always sat in pending() until it
timed out at 30 seconds.

There's a race between closing the storage and shutting down the
ConnectThread.  If we return here, the ConnectThread does no harm.