[Checkins] SVN: zope.session/trunk/src/zope/session/ Change the default session resolution to something sane, before sessions could

[Benji York]

Log message for revision 84585:
  Change the default session resolution to something sane, before sessions could
  last from 10 to 60 minutes, depending on how lucky a user was, now they can
  range from 50 to 60 minutes; also added tests that nail down the default values
  as well as an explanation of what resolution means and why it should be small
  relative to the timeout.
  

Changed:
  U   zope.session/trunk/src/zope/session/api.txt
  U   zope.session/trunk/src/zope/session/session.py

-=-
Modified: zope.session/trunk/src/zope/session/api.txt
===================================================================
--- zope.session/trunk/src/zope/session/api.txt	2008-03-11 19:46:06 UTC (rev 84584)
+++ zope.session/trunk/src/zope/session/api.txt	2008-03-11 19:48:38 UTC (rev 84585)
@@ -128,3 +128,26 @@
             <span tal:content="session/count" />
         </div>
 
+
+Session Timeout
+---------------
+
+Sessions have a timeout (defaulting to an hour, in seconds).
+
+    >>> import zope.session.session
+    >>> data_container = zope.session.session.PersistentSessionDataContainer()
+    >>> data_container.timeout
+    3600
+
+We need to keep up with when the session was last used (to know when it needs
+to be expired), but it would be too resource-intensive to write the last access
+time every, single time the session data is touched.  The session machinery
+compromises by only recording the last access time periodically.  That period
+is called the "resolution".  That also means that if the last-access-time +
+the-resolution < now, then the session is considered to have timed out.
+
+The default resolution is 10 minutes (600 seconds), meaning that a users
+session will actually time out sometime between 50 and 60 minutes.
+
+    >>> data_container.resolution
+    600

Modified: zope.session/trunk/src/zope/session/session.py
===================================================================
--- zope.session/trunk/src/zope/session/session.py	2008-03-11 19:46:06 UTC (rev 84584)
+++ zope.session/trunk/src/zope/session/session.py	2008-03-11 19:48:38 UTC (rev 84585)
@@ -81,7 +81,8 @@
     def __init__(self):
         self.data = OOBTree()
         self.timeout = 1 * 60 * 60
-        self.resolution = 50*60
+        # The "resolution" should be a small fraction of the timeout.
+        self.resolution = 10 * 60
 
     def __getitem__(self, pkg_id):
         """Retrieve an ISessionData