[Templates-cvs] cvs commit: TT3/lib/Template Cache.pm
cvs@template-toolkit.org
cvs@template-toolkit.org
Wed, 24 Mar 2004 13:09:02 +0000
cvs 04/03/24 13:09:02
Modified: lib/Template Cache.pm
Log:
* added documentation
Revision Changes Path
1.2 +154 -9 TT3/lib/Template/Cache.pm
Index: Cache.pm
===================================================================
RCS file: /template-toolkit/TT3/lib/Template/Cache.pm,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- Cache.pm 2004/03/24 12:25:19 1.1
+++ Cache.pm 2004/03/24 13:09:01 1.2
@@ -13,13 +13,13 @@
# COPYRIGHT
# Copyright (C) 1996-2004 Andy Wardley. All Rights Reserved.
# Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.
-# Copyright (C) 2002-2004 Fotango Ltd.
+# Copyright (C) 2004 Fotango Ltd.
#
# This module is free software; you can redistribute it and/or
# modify it under the same terms as Perl itself.
#
# REVISION
-# $Id: Cache.pm,v 1.1 2004/03/24 12:25:19 abw Exp $
+# $Id: Cache.pm,v 1.2 2004/03/24 13:09:01 abw Exp $
#
#========================================================================
@@ -31,7 +31,7 @@
use base qw( Template::Base );
use vars qw( $VERSION $DEBUG $ERROR $THROW );
-$VERSION = sprintf("%d.%02d", q$Revision: 1.1 $ =~ /(\d+)\.(\d+)/);
+$VERSION = sprintf("%d.%02d", q$Revision: 1.2 $ =~ /(\d+)\.(\d+)/);
$DEBUG = 0 unless defined $DEBUG;
$ERROR = '';
$THROW = 'cache'; # we currently don't raise any errors, but
@@ -42,16 +42,32 @@
use constant DATA => 2;
use constant NEXT => 3;
+
+#------------------------------------------------------------------------
+# init()
+#
+# Constructor method accepts 'size' and 'time' parameters.
+#------------------------------------------------------------------------
+
sub init {
my ($self, $config) = @_;
$self->{ slot } = { }; # slot lookup by name
$self->{ used } = 0; # slots used
$self->{ size } = $config->{ size }; # max slots
+
+ # TODO: this doesn't do anything currently, but maybe should...
$self->{ time } = $config->{ time }; # max time
return $self;
}
+#------------------------------------------------------------------------
+# set( $name => $data )
+#
+# Store an item in the cache, reusing the oldest slot if we've hit our
+# size limit (if any).
+#------------------------------------------------------------------------
+
sub set {
my ($self, $name, $data) = @_;
my $size = $self->{ size };
@@ -108,6 +124,15 @@
}
+
+#------------------------------------------------------------------------
+# get( $name )
+#
+# Fetch an item from the cache. If we've got a size limit set then we
+# also move its slot to the head of the slot list to indicate that it's
+# the most recently used item.
+#------------------------------------------------------------------------
+
sub get {
my ($self, $name) = @_;
@@ -142,6 +167,12 @@
}
+#------------------------------------------------------------------------
+# _remove_slot($slot)
+#
+# Private method to remove a slot from the slot list.
+#------------------------------------------------------------------------
+
sub _remove_slot {
my ($self, $slot) = @_;
my $prev;
@@ -168,6 +199,15 @@
}
+#------------------------------------------------------------------------
+# _head_slot()
+# _head_slot($slot)
+#
+# Private method to manipulate the head slot (most recently used) in the
+# slot list. Returns the current head slot when called without arguments.
+# When passed a slot as an argument, it installs it as the head slot.
+#------------------------------------------------------------------------
+
sub _head_slot {
my $self = shift;
return $self->{ head } unless @_;
@@ -186,6 +226,11 @@
}
+#------------------------------------------------------------------------
+# _slot_report()
+#
+# Debugging method which isn't really private, but not advertised either.
+#------------------------------------------------------------------------
sub _slot_report {
my $self = shift;
@@ -238,36 +283,136 @@
=head1 NAME
-Template::Cache - TODO
+Template::Cache - in-memory cache for template components
=head1 SYNOPSIS
+
+ use Template::Cache;
+
+ my $cache = Template::Cache->new( size => 32 );
+
+ $cache->set( foo => $foo );
- TODO
+ # ...later...
+ $foo = $cache->get('foo');
+
+ print "foo has expired from cache\n"
+ unless defined $foo;
+
=head1 DESCRIPTION
-TODO
+The Template::Cache module implements a simple in-memory cache for
+compiled template components.
+The most time-consuming part of processing a template is the initial
+phase in which we read in the template source, parse it, and compile
+it into Perl code. The Perl code is then evaluated and should result
+in a Template::Component object being created which implements the
+functionality of the original template. Fortunately, we only need to
+compile the template once and can then re-use the Template::Component
+generated as many times as we like.
+
+And that is where the Template::Cache comes in. It takes
+responsibility for storing the Template::Component objects and making
+them available again when they need to be re-used.
+
+It provides a simple mechanism for limiting the number of templates
+that are cached and automatically discards the least-recently-used
+component when the limit is reached.
+
+It also defines a simple API and can act as a base class for modules
+that implement different caching mechanisms. The API is deliberately
+compatible with the Cache::Cache modules, allowing you to use any of
+them as a direct replacement for Template::Cache.
+
=head1 METHODS
+
+=head2 new()
+
+Constructor method which creates a new Template::Cache object.
+
+ use Template::Cache;
+
+ my $cache = Template::Cache->new();
+
+The C<size> parameter can be provided to define a limit to the
+number of items that the cache will store at any one time.
+
+ my $cache = Template::Cache->new( size => 32 );
+
+If no C<size> is defined then the cache will grow without limit.
+
+=head2 set($name, $component)
+
+Add an item to the cache. The first argument provides a name for the
+component passed as the second argument, by which it can subsequently
+be fetched via the C<get()> method.
+
+ $cache->set( foo => $foo_component );
-TODO
+=head2 get($name)
+Fetch an item from the cache previously stored by calling C<set()>.
+If the item is not in the cache, either because it was never been
+put in the cache or because it was, but has subsequently expired,
+then the method returns C<undef>.
+
+ $foo = $cache->get( foo )
+ || die "no foo component\n";
+
+=head1 SUBCLASSING AND ERROR HANDLING
+
+The Template::Cache module doesn't raise an errors as there is really
+nothing that can go wrong (well, nothing that we can detect or do
+anything about, at least). However, if the module or a subclass were
+to raise any errors, then it should do so by throwing them as
+Template::Exception objects. All this means in practice is that you
+should set the C<$THROW> package variable to something meaningful and
+leave the C<error()> method to do the rest.
+
+For example, a (purely fictional) subclass of Template::Cache designed
+to cache template components in a atomic vector plotter suspended in a
+strong Brownian Motion producer (say a nice hot cup of tea) might do
+something like this:
+
+ package Template::Cache::TeaCup;
+ use base qw( Template::Cache );
+ use vars qw( $THROW );
+
+ # this tells the Template::Base error() method to raise
+ # errors as 'teacup' exceptions
+ $THROW = 'teacup';
+
+ sub set {
+ my ($self, $name, $component) = @_;
+
+ # down here we just call error() as usual...
+ return $self->error("no more tea bags")
+ unless $self->{ tea_bags };
+ }
+
=head1 AUTHOR
Andy Wardley E<lt>abw@wardley.orgE<gt>
=head1 VERSION
-$Revision: 1.1 $
+$Revision: 1.2 $
=head1 COPYRIGHT
Copyright (C) 1996-2004 Andy Wardley. All Rights Reserved.
Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.
- Copyright (C) 2002-2004 Fotango Ltd.
+ Copyright (C) 2004 Fotango Ltd.
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
+
+=head1 SEE ALSO
+
+See L<Cache::Cache> for various different caching modules that implement
+different caching strategies and can be used in place of Template::Cache.
=cut