File Coverage

blib/lib/Catalyst/Plugin/Session/Store/FastMmap.pm
Criterion Covered Total %
statement 36 38 94.7
branch 1 2 50.0
condition 2 6 33.3
subroutine 11 12 91.7
pod 5 5 100.0
total 55 63 87.3


line stmt bran cond sub pod time code
1             package Catalyst::Plugin::Session::Store::FastMmap;
2              
3 2     2   33 use strict;
  2         30  
  2         33  
4             use base
5 2     2   32   qw/Class::Data::Inheritable Class::Accessor::Fast Catalyst::Plugin::Session::Store/;
  2         19  
  2         33  
6 2     2   83 use NEXT;
  2         18  
  2         41  
7 2     2   87 use Cache::FastMmap;
  2         21  
  2         50  
8 2     2   63 use Path::Class ();
  2         329  
  2         142  
9 2     2   41 use File::Spec ();
  2         20  
  2         20  
10 2     2   50 use Catalyst::Utils ();
  2         27  
  2         22  
11              
12             our $VERSION = '0.02';
13              
14             __PACKAGE__->mk_classdata(qw/_session_fastmmap_storage/);
15              
16             =head1 NAME
17            
18             Catalyst::Plugin::Session::Store::FastMmap - FastMmap session storage backend.
19            
20             =head1 SYNOPSIS
21            
22             use Catalyst qw/Session Session::Store::FastMmap Session::State::Foo/;
23            
24             MyApp->config->{session} = {
25             expires => 3600,
26             storage => '/tmp/session'
27             };
28            
29             # ... in an action:
30             $c->session->{foo} = 'bar'; # will be saved
31            
32             =head1 DESCRIPTION
33            
34             C<Catalyst::Plugin::Session::Store::FastMmap> is a fast session storage plugin
35             for Catalyst that uses an mmap'ed file to act as a shared memory interprocess
36             cache. It is based on L<Cache::FastMmap>.
37            
38             =head2 METHODS
39            
40             =over 4
41            
42             =item get_session_data
43            
44             =item store_session_data
45            
46             =item delete_session_data
47            
48             =item delete_expired_sessions
49            
50             These are implementations of the required methods for a store. See
51             L<Catalyst::Plugin::Session::Store>.
52            
53             =cut
54              
55             # The reference business is because Cache::FastMmap delegates to Storable with
56             # no intervention, meaning that non reference data cannot be stored.
57             # see L<https://rt.cpan.org/NoAuth/Bug.html?id=16762>
58             # FIXME remember to remove this hack when the new version of Cache::FastMmap is
59             # out, and to rely on it
60             sub get_session_data {
61 3     3 1 32     my ( $c, $sid ) = @_;
62 3 50       25     ${ $c->_session_fastmmap_storage->get($sid) || return };
  3         40  
63             }
64              
65             sub store_session_data {
66 8     8 1 79     my ( $c, $sid, $data ) = @_;
67 8         206     $c->_session_fastmmap_storage->set( $sid, \$data );
68             }
69              
70             sub delete_session_data {
71 6     6 1 57     my ( $c, $sid ) = @_;
72 6         62     $c->_session_fastmmap_storage->remove($sid);
73             }
74              
75 0     0 1 0 sub delete_expired_sessions { } # unsupported
76              
77             =item setup_session
78            
79             Sets up the session cache file.
80            
81             =cut
82              
83             sub setup_session {
84 2     2 1 20     my $c = shift;
85              
86 2         76     $c->NEXT::setup_session(@_);
87              
88 2   33     26     my $tmpdir = Catalyst::Utils::class2tempdir($c)
89                   || Catalyst::Exception->throw("Can't determine tempdir for $c");
90              
91 2   33     38     my $file = $c->config->{session}{storage} ||=
92                   File::Spec->catfile( # Cache::FastMmap doesn't like Path::Class objects
93                     $tmpdir,
94                     "session_data",
95                   );
96              
97 2         25     Path::Class::dir($tmpdir)->mkpath;
98              
99 2         46     my $cfg = $c->config->{session};
100              
101 0         0     $c->_session_fastmmap_storage(
102                     Cache::FastMmap->new(
103                         share_file => $cfg->{storage},
104                         (
105 4         109                 map { $_ => $cfg->{$_} }
106 2         23                   grep { exists $cfg->{$_} } qw/init_file cache_size/
107                         ),
108                     )
109                 );
110             }
111              
112             =back
113            
114             =head1 CAVEATS
115            
116             Very loaded sites with lots of data in the session hash may have old sessions
117             expired prematurely, due to the LRU caching policy employed by
118             L<Cache::FastMmap>. To get around this you can increase the C<cache_size>
119             parameter, or switch session storage backends.
120            
121             This is particularly inappropriate for use as a backend for e.g.
122             L<Catalyst::Plugin::Session::PerUser>, for example.
123            
124             L<Cache::FastMmap> defaults to around 5mb (89 * 64k).
125            
126             =head1 CONFIGURATION
127            
128             These parameters are placed in the hash under the C<session> key in the
129             configuration hash.
130            
131             =over 4
132            
133             =item storage
134            
135             Specifies the file to be used for the sharing of session data. The default
136             value will use L<File::Spec> to find the default tempdir, and use a file named
137             C<MyApp_session_data>, where C<MyApp> is replaced with the appname.
138            
139             Note that the file will be created with mode 0640, which means that it
140             will only be writeable by processes running with the same uid as the
141             process that creates the file. If this may be a problem, for example
142             if you may try to debug the program as one user and run it as another,
143             specify a filename like C<< /tmp/session-$> >>, which includes the
144             UID of the process in the filename.
145            
146             =item init_file
147            
148             =item cache_size
149            
150             See the L<Cache::FastMmap> documentation for the meaning of these keys. If
151             these keys are not present L<Cache::FastMmap>'s defaults will be used.
152            
153             =back
154            
155             =head1 SEE ALSO
156            
157             L<Catalyst>, L<Catalyst::Plugin::Session>, L<Cache::FastMmap>.
158            
159             =head1 AUTHORS
160            
161             This module is derived from L<Catalyst::Plugin::Session::FastMmap> code, and
162             has been heavily modified since.
163            
164             Andrew Ford
165             Andy Grundman
166             Christian Hansen
167             Yuval Kogman, C<nothingmuch@woobling.org>
168             Marcus Ramberg
169             Sebastian Riedel
170            
171             =head1 COPYRIGHT
172            
173             This program is free software, you can redistribute it and/or modify it
174             under the same terms as Perl itself.
175            
176             =cut
177              
178             1;
179