expanded documentation of Catalyst::Plugin::Session::FastMmap

[catagits/Catalyst-Plugin-Session-State-Cookie.git] / FastMmap.pm

diff --git a/FastMmap.pm b/FastMmap.pm
index 7e48d93..6980639 100644 (file)
--- a/FastMmap.pm
+++ b/FastMmap.pm
@@ -9,7 +9,7 @@ use URI;
 use URI::Find;
 use File::Temp 'tempdir';
 
-our $VERSION = '0.11';
+our $VERSION = '0.13';
 
 __PACKAGE__->mk_classdata('_session');
 __PACKAGE__->mk_accessors('sessionid');
@@ -33,11 +33,16 @@ Catalyst::Plugin::Session::FastMmap - FastMmap sessions for Catalyst
 
 =head1 DESCRIPTION
 
-Fast sessions.
+C<Catalyst::Plugin::Session::FastMmap> is a fast session plugin for
+Catalyst that uses an mmap'ed file to act as a shared memory
+interprocess cache.  It is based on C<Cache::FastMMap>.
+
 
 =head2 EXTENDED METHODS
 
-=head3 finalize
+=over 4
+
+=item finalize
 
 =cut
 
@@ -55,8 +60,7 @@ sub finalize {
         }
         if ( $set ) {
             $c->response->cookies->{session} = { 
-                value   => $sid, 
-                expires => $c->config->{session}->{expires} . 's'
+                value => $sid
             };
         }
         if ( $c->config->{session}->{rewrite} ) {
@@ -75,7 +79,7 @@ sub finalize {
     return $c->NEXT::finalize(@_);
 }
 
-=head3 prepare_action
+=item prepare_action
 
 =cut
 
@@ -113,14 +117,16 @@ sub session {
     }
 }
 
-=head3 setup
+=item setup
+
+Sets up the session cache file.
 
 =cut
 
 sub setup {
     my $self = shift;
     $self->config->{session}->{storage} ||= '/tmp/session';
-    $self->config->{session}->{expires} ||= '1d';
+    $self->config->{session}->{expires} ||= 60 * 60 * 24;
     $self->config->{session}->{rewrite} ||= 0;
 
     $self->_session(
@@ -133,11 +139,15 @@ sub setup {
     return $self->NEXT::setup(@_);
 }
 
+=back
+
 =head2 METHODS
 
-=head3 session
+=over 4
+
+=item session
 
-=head3 uri
+=item uri
 
 Extends an uri with session id if needed.
 
@@ -157,28 +167,46 @@ sub uri {
     return $uri;
 }
 
+=back
+
 =head2 CONFIG OPTIONS
 
-=head3 rewrite
+=over 4
+
+=item rewrite
+
+If set to a true value sessions are automatically stored in the url;
+defaults to false.
+
+=item storage
+
+Specifies the file to be used for the sharing of session data;
+defaults to C</tmp/session>. 
 
-To enable automatic storing of sessions in the url set this to a true value.
+Note that the file will be created with mode 0640, which means that it
+will only be writeable by processes running with the same uid as the
+process that creates the file.  If this may be a problem, for example
+if you may try to debug the program as one user and run it as another,
+specify a filename like C<< /tmp/session-$> >>, which includes the
+UID of the process in the filename.
 
-=head3 storage
 
-File to mmap for sharing of data, defaults to /tmp/session.
+=item expires
 
-=head3 expires
+Specifies the session expiry time in seconds; defaults to 86,400,
+i.e. one day.
 
-how many seconds until the session expires. defaults to 1 day
+=back
 
 =head1 SEE ALSO
 
-L<Catalyst> L<Cache::FastMmap>.
+L<Catalyst>, L<Cache::FastMmap>.
 
 =head1 AUTHOR
 
-Sebastian Riedel, C<sri@cpan.org>
-Marcus Ramberg C<mramberg@cpan.org>
+Sebastian Riedel E<lt>C<sri@cpan.org>E<gt>,
+Marcus Ramberg E<lt>C<mramberg@cpan.org>E<gt>,
+Andrew Ford E<lt>C<andrewf@cpan.org>E<gt>
 
 =head1 COPYRIGHT