cson  Artifact Content

Artifact 1702485c2b08666568d58e672ca3caa407a7294f:

Wiki page [cson_sessmgr_whio_ht] by stephan 2011-05-09 17:58:45.
D 2011-05-09T17:58:45.334
L cson_sessmgr_whio_ht
P 4360da15d9e19b4fa8669e62a2497ff07f57300f
U stephan
W 3018
<strong>ACHTUNG: THIS PAGE IS NOW MAINTAINED IN THE NEW WIKI:</strong> [http://whiki.wanderinghorse.net/wikis/cson/?page=cson_sessmgr_whio_ht]

See also: [cson_session], [cson_sessmgr_cpdo], [cson_sessmgr_file], [cson_sessmgr_whio_epfs]

<h1>File-based Hashtable [cson_session] Storage</h1>

(Added 20110418.)

The "whio_ht" session manager is not compiled in by default, but if the library is built with it then this session manager provides session persistence via a hashtable file. Multiple processes may use the hashtable - it uses <tt>fcntl()</tt>-style locking, if enabled when the library is built and the underlying storage seems to support it. The hashtable keys are session IDs and the JSON session data are the hashtable values.

The configuration JSON object for the <tt>cson_sessmgr</tt> factory looks like:

   "file": "/path/to/file.whio_ht"

The hashtable file must already exist and be writable by the session-using process. The hashtables can be created programmatically, using the [http://fossil.wanderinghorse.net/repos/whio/index.cgi/wiki/whio_ht|whio_ht API] or using [http://fossil.wanderinghorse.net/repos/whio/index.cgi/wiki/whio_ht_tool|whio-ht-tool] (which is also included in the <tt>session</tt> subdirectory of this source tree). For example:

~> whio-ht-tool sessions.whio_ht create

That will create <tt>sessions.whio_ht</tt> with an unspecified hashtable size (large enough for mid-sized uses). You can specify a specific hashtable size by passing <tt>hashSize NUMBER</tt> (ideally [http://en.wikipedia.org/wiki/List_of_prime_numbers|a prime number]) as the last arguments.

<strong>Achtung:</strong> the hashtable has no way of recording the lifetimes of individual sessions. While <tt>whio-ht-tool</tt> can be used to remove individual sessions, or they can be removed programmatically, it is not generically possible to know which sessions have expired and should be removed. Thus this session manager implementation should not be used in high-traffic apps which might accumulate tons of old/stale sessions from various users/site visitors. We <em>could</em> wrap each session object in another object which records the timestamp, but then cleaning them up would require writing an app which loads and analyzes each session. Maybe someday i'll add that option (and the tool to clean up). On a related note, the hashtable can never shrink. Removed entries are marked as free and potentially recycled, but the storage itself is never shrunk.

<strong>Achtung #2:</strong> an untimely C signal while the hashtable is writing or flushing might leave it in a corrupted state. That could happen, e.g., from another thread or via a <tt>SIGPIPE</tt> in a [cson_cgi|CGI application]. This client is responsible for ignoring/handling signals, if needed for his application.

We have all the pieces we need, in libwhio, to be able to compress the session data with zlib. Maybe someday i'll get bored and add that.

Z 17601d099e39684bcc56c772ba4750c2