view release on metacpan or  search on metacpan

memcache.pm  view on Meta::CPAN

  if (!$memd) {die("No Connection to Memcached !");}

  my $cgi = CGI->new();
  my $sess = CGI::Session->new("driver:memcache", $cgi, {'Handle' => $memd});

  # Get and Set the standard CGI::Session way
  # Get
  my $v = $sess->param('greet_en');
  # Set
  $sess->param('greet_en', "Hi !");

=head1 DESCRIPTION

CGI::Session::Driver::memcache is a storage driver (only referred as 'driver' in
CGI::Session lingo) for persisting CGI Sessions into a fast memcached server.

It requires you to instantiate memcached connection using any
of the available Perl memcache client libraries and pass it to CGI::Session constructor
along with "DSN" "driver:memcache" (see SYNOPSIS).

You do not need to learn any of CGI::Session::Driver::memcache, but only use
it as a driver. All your learning efforts should go to CGI::Session (see also
CGI::Session::Tutorial). Only learning related to this driver is how to create
a connection (see $memd above) using one of the Perl Memcached client modules and
passing it to CGI::Session constructor.

=head1 METHODS

Not applicable to CGI::Session API user. CGI::Session::Driver::memcache implements
methods required by CGI::Session::Driver (interface).
Note that CGI::Session::Driver method 'traverse' (accessible via CGI::Session->find())
is not supported currently (partially because Perl APIs do not support iterating the keys of cache).

=head1 Why CGI::Session::Driver::memcache ?

While it is possible to use memcache client directly to store sessions into
memcache server, the CGI::Session provides a nice modular abstraction with
a lot  of thought put into it.
Developing session management directly against memcached makes setting up a memcache server a hard
dependency for the app.
By using CGI::Session in between the app and session storage backend it is easy to "right-size"
storage backend according to requirements of current project.

=cut

#CGI::Session modularity also allows your application to be configured with the wealth of storage
#backends (ASCII file, DBM, DBI, ..) and serialization methods to be used
#(for example flat files in absence of database or memcache servers).

=head1 Setting up Memcached Server

See F<README> in the package for short tutorials on setting up the memcached
server and testing the installation from command line.

=head1 BUGS

This driver requires Memcached connection handle to be passed to CGI::Session constructor as "raw" connection handle ({'Handle' => $memd}), making
caller responsible for passing a valid connection. This is actually good for relieving CGI::Session from the intricacies of suppporting various Memcached client
modules with differences in constructions (the rest of the main API on these module is generally very similar).

This driver and CGI::Session underpinnings do very little to ensure the server is actually alive.
The situation is even worse for Memcached client modules that return valid client instance
without server running (This is very different from lot of other DB Modules like DBI/DBD* or Net::LDAP,
where any problems with server raises exceptions or returns undefined handles).
Make sure your server is alive by either Calling stats() on Memcached client:

   my $stats = $memd->stats(); # Allows: [$keys]
   if (ref($stats) || !$stats->{'total'}) {die("No stats from Memcached - Memcached not running ?");}

... or by doing a set/get test sequence:

   my $testval = "it_is_".time();
   my $ok = $memd->set("whatstime", $testval);
   if (!$ok) {die("Setting k-v in memcached failed - Memcached not running ?");}
   # Optional get to double verify reading back
   my $itis_t = $memd->get("whatstime") || '';
   if (!$itis_t) {die("Value stored to Memcached earlier could not be read back !");}

=head1 SEE ALSO

L<CGI::Session>, L<CGI::Session::Tutorial>, L<Cache::Memcached::libmemcached>
for excellent list of Perl memcache client APIs (links to the module can be
found there).

See memcached website (L<http://memcached.org/>) for more information on
memcache deamon.

=head1 CREDITS

Creators of CGI::Session for a great modular web session API.

=head1 AUTHOR and COPYRIGHT

Copyright (c) 2010-2013 Olli Hollmen <olli.hollmen@gmail.com>. All rights reserved.
This library is free software. You can modify and or distribute it under the
same terms as Perl itself.