[ZODB-Dev] cache gc api

[Jeremy Hylton]

There's been some discussion on the list over the last few days about
how calls like cacheMinimize() and callFullSweep() work.  It seems
that the mismatch between documented behavior and implementation is
catchup quite a few people.

I'd like to clean up this corner of the implementation before the
StandaloneZODB release.  It looks like we've got the following issues
to work through:

    - People expect that passing 0, 1, or 2 to cacheFullSweep() will
      collect objects that have been touched in 0 or 1 or 2 seconds.

    - The doc strings and old UML model say the default value for
      cacheFullSweep() is cache_age, but it's actually 0.

    - There is a special case in the implementation that allows you to
      remove only unreachable objects from the cache.  (This is the
      current behavior is you pass 0 or no argument.)

I propose to make the following changes:

    - Change the implementation to treat 0 as "deactivate it
      regardless of how old it is."

    - Change the implementation to provide the documented default
      value.

    - Add documentation that says you can pass a value greater than
      196608 to achieve the effect of only removing unreachable
      objects. 

      (If that seems to weird, we could use -1 to mean this instead of
      0.)

It looks like the only part of Zope that would be affected by this
change is the management interface, which allows you to call
cacheFullSweep() and cacheMinimize() with an argument chosen by the
user.  In this case, however, the documentation suggests that 0, 1, or
2 would be valid values that would cause GC to occur.

Jeremy