/ 
Konstrukt-0.5-beta7
River stage zero No dependents
/ Konstrukt::Cache

NAME

Konstrukt::Cache - Caching functionalities

SYNOPSIS

#read and track a file/some files. only files that have been read with the
#L<Konstrukt::File/read_and_track> method will be tracked for caching and the
#cache conditions will only be saved for this files.
$Konstrukt::File->read_and_track('/some/file'); #will be $docroot/some/file
$Konstrukt::File->read_and_track('another_file'); #will be $docroot/some/another_file

#check that this file has not been changed
$Konstrukt::Cache->add_condition_file(<filename of the file that should be cached>, <filename of the file that must not change>);

#check that this date is not reached
#format:
#YYYY-MM-DD-HH-MM-SS (absolute date)
#+1Y, 1M, 1D, 1H, 1M, 1S (relative date)
$Konstrukt::Cache->add_condition_date(<filename of the file that should be cached>, <date in format as stated above>);

#check that the sql table didn't change
#will use the sql-connection-settings from your konstrukt.config. see Konstrukt::Plugin::sql
$Konstrukt::Cache->add_condition_sql(<filename of the file that should be cached>, <table>);
#will use the specified sql-connection-settings
$Konstrukt::Cache->add_condition_sql_advanced(<filename of the file that should be cached>, <dbi-source>, <dbi-user>, <dbi-pass>, <table>);

#check that this sub returns true.
#this is the most flexible but also least comfortable way to validate the cache.
$Konstrukt::Cache->add_condition_perl(<filename of the file that should be cached>, "<perl-code here>");

#prevent caching of the file. if you don't want this file to be cached for some reason.
$Konstrukt::Cache->prevent_caching(<filename of the file that must not be cached>);

#write the cache
$Konstrukt::Cache->write_cache($Konstrukt::File->absolute_path(<filename of the file that must not be cached>), <parse tree>);

#read the cache
my $parse_tree = $Konstrukt::Cache->get_cache($Konstrukt::File->absolute_path(<filename of the file that must not be cached>));

#delete the cache. generally only used internally
$Konstrukt::Cache->delete_cache($Konstrukt::File->absolute_path(<filename of the file that must not be cached>));

DESCRIPTION

This module provides the caching functionality of this framework. It's one key element to a higher performance, so the usage is recommended.

After the prepare-run the result will be cached, so that on a second request for this file the prepare-work won't be done again.

You can add conditions to the cached results that must be fulfilled to accept the cached result as up-to-date.

For example you may specify an input file that must not change ("add_condition_file"). If the file was modified its date will change, the cache will get invalid and the source file has to be processed from the start.

For more possibilities take a look at "SYNOPSIS".

TRACKED FILES / TO WHICH FILES ARE THE CONDITIONS APPLIED?

Only files that have been read with the "read_and_track" in Konstrukt::File method will be tracked for caching and the cache conditions will only be saved for this files.

Let's say you read those three files:

$Konstrukt::File->read_and_track('/some/file');   #1) will be $docroot/some/file
$Konstrukt::File->read_and_track('another_file'); #2) will be $docroot/some/another_file
$Konstrukt::File->read('even_another_file');      #3) will be $docroot/some/even_another_file

Then you add a date condition:

$Konstrukt::Cache->add_condition_date("+5m"); #cache valid for max. 5 minutes

This condition will be added to file 1) and 2). Not to file 3) as it is not tracked (i.e. not push()'ed on Konstrukt::File's file stack).

Then you're done with file 2) and remove it from Konstrukt::File's stack:

$Konstrukt::File->pop();

Now you add another date condition:

$Konstrukt::Cache->add_condition_date("+2m"); #cache valid for max. 2 minutes

This condition will only be added to file 1), as file 2) isn't tracked anymore. Note also that only earlier dates will be added. A later date won't be added as the file already gets invalid by the earlier date condition.

Note: When a new file is read (with "read_and_track" in Konstrukt::File) a file date condition will automatically added to each tracked file as it is supposed that the file depends on the files which have been read as the file was tracked. See also "read_and_track" in Konstrukt::File.

Now you might want to write the cache:

$Konstrukt::Cache->write_cache($Konstrukt::File->absolute_path('/some/file'),        <parse tree 1>);
$Konstrukt::Cache->write_cache($Konstrukt::File->absolute_path('another_file'),      <parse tree 2>);
$Konstrukt::Cache->write_cache($Konstrukt::File->absolute_path('even_another_file'), <parse tree 3>);

A cache for all 3 files will be written.

File 1) will have a date condition (+5m) and a file date condition for every file that has been read (with read_and_track) while file 1) has been tracked. That will be "/some/file" itself and "/some/file/another_file" (and also "/konstrukt.settings" as it is supposed that a settings change will invalidate all cached results).

File 2) will have a date condition (+2m) and file conditions only for itself (and for "/konstrukt.settings").

File 3) will have no cache conditions as it has not been opened with "read_and_track".

Note that "get_cache" has a similar effect as <Konstrukt::File/read_and_track>.

CONFIGURATION

You may define those settings. Defaults:

cache/use       1          #Use cache:    0=never; 1=if exist
cache/create    1          #Create cache: 0=never; 1=auto; 2=always
cache/dir       ../cache/  #Directory to store the cached files in. Should end with a /. Relative to your document root
cache/file_ext  .cached    #File extension for cached files

METHODS

new

Constructor of this class

init

Initialization of this class

add_condition_file

Add a condition, that checks whether a file has been modified.

Parameters:

  • $watch_file - The absolute path to the file that should be checked for changes.

add_condition_date

Add a condition, that checks whether the given date has been reached yet or not.

Parameters:

  • $date - The date. Absolute and relative dates allowed. Format: YYYY-MM-DD-HH-MM-SS (absolute date), +1Y 1M 1D 1h 1m 1s (relative date).

    Note that only positive date differences are allowed.
Algebraic signs will not work. The format is B<case sensitive>!

add_condition_sql

Add a condition, that checks whether an SQL-table has been modified or not.

The sql connection settings from your konstrukt.config will be used.

Note that the specified table must have a column named "timestamp", which must be kept up to date on UPDATE and INSERT operations.

This may lead into problems as DELETE operations may not be recognized this way, because the appropriate row just disappears and the youngest timestamp may stay unmodified. You may get around this by inserting a dummy row with no content and just a timestamp that you manually keep up to date.

Note that the column type TIMESTAMP (e.g. in MySQL) will be updated on each UPDATE and INSERT operation.

Parameters:

  • $table - The table for which the youngest timestamp will be checked.

add_condition_sql_advanced

This one does the same as "add_condition_sql" but lets you define the sql connection settings yourself.

Parameters:

  • $source - The DBI-source.

  • $user - The username for the DB logon.

  • $pass - The password for the DB logon.

  • $table - The table for which the youngest timestamp will be checked.

add_condition_perl

Adds a condition, that will execute (eval) the passed perl code and will assume a valid cache on a "true" result and discard the cache otherwise.

Parameters:

  • $code - The perl code that should be executed.

prevent_caching

Prevents the caching of a file.

You may pass a reason, why the cache creation should be prevented.

Parameters:

  • $file - The absolute filename of the file that should be cached.

  • $reason - An integer which defines the reason for the cache prevention:

    • 0: No reason

    • 1: Errors during the processing of this file

    • 2: Already using a cached file. Don't cache again.

validate_cache

Takes a cache-file and validates it with the contained conditions. Returns true on a valid cache-file.

Parameters:

  • $tree - The content of the cache file (Reference to the root node).

get_cache

Returns the cached results for a given file, if existent and valid. Returns undef otherwise.

Will also add the path to the requested file to the stack of current directories, if there is a valid cached file available.

So you should call $Konstrukt::File-pop()> when you're done with the file you read from the cache.

Parameters:

  • $filename - The absolute path to the file for which we want to get the cached results.

write_cache

Writes cached results for a given file to disk

Parameters:

  • $file - The absolute path (relative will not work) to the file for which we want to save the cached results.

  • $tree - The result tree of the prepare-run of the parser.

delete_cache

Deletes the cache for a given file.

Parameters:

  • $file - The absolute path to the file for which the results have been cached

AUTHOR

Copyright 2006 Thomas Wittek (mail at gedankenkonstrukt dot de). All rights reserved.

This document is free software. It is distributed under the same terms as Perl itself.

SEE ALSO

Konstrukt::File, Konstrukt::Plugin::template, Konstrukt