NAME

PSA::Heap - a per-session dump for data

SYNOPSIS

 my $heap = PSA::Heap->new($psa);

 $psa->heap->{foo} = "bar";

 $heap->flush();    # automatically called on destruction

DESCRIPTION

The PSA::Heap module encapsulates a `Heap' concept - analagous to a session. This is distinct from the PSA::Session class, in that that class is actually a real object in a Tangram store - the PSA::Heap class assumes that you are storing the sessions locally on the application servers (and hence, that session affinity is working correctly).

Apache::Session::File is used for the serialisation. This could be changed to other techniques, especially since Apache::Session is so crap, like Apache::Session::DB. But trust me, you are better off using PSA::Session.

There are drawbacks to this approach, as compared to PSA::Session;

• Application code needs to know whether it's better to store stuff in the heap or in the PSA::Session.
• Business objects mistakenly placed in the heap may end up trying to serialise the entire database. This is automatically avoided with PSA::Session.

However, both of these problems can be worked around; by serialising the session with Data::Dumper, but replacing any business objects (ie, those found with a storage ID) with a blessed scalar ref to the object ID or something like that. This serialisation can be stored as part of the PSA::Session if using DB-only sessions.

Session State and lock directories

The following directories are checked for writability in order at program startup:

  var/lib/session
  /var/lib/psa
  /var/tmp

The first one that is found, and writable, is used to store session information.

For session locking information, the following paths are used:

  var/lock
  /var/lock/psa
  /tmp

METHODS

PSA::Heap->new($psa)

Creates or loads a new session. The PSA object will supply the SID to use if a session is to be resumed; otherwise (or if the session cannot be resumed), a new session is created and the SID set in the PSA object.

$heap->flush()

Flushes a session; ie, explicitly commits the session to disk. This is automatically called on destruction of the object (but note that a circular reference prevents this from happening normally; c'est la vie).

$heap->flatten($storage)

Removes any references in the heap to objects in the provided storage. Note that after this happens, the data won't be very useful, so it should happen after the page is generated (d'oh!).

FIXME - doesn't work for Set::Object containers

$heap->unflatten($storage)

Goes through the heap and un-does the effects of a flatten. Objects are not loaded immediately; Defer is used to avoid that.

$heap->hits()

Returns the number of times that this session has been loaded

$heap->rollback()

Forgets all of the changes to the heap and restores it to the way it was the last time it was read.

$heap->commit($storage)

Saves a session, but keeps it available.

TO-DO

   * A PSA::Pixie equivalent of storage / heap / etc

AUTHOR

Sam Vilain, <sam@vilain.net>