The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Email-Fingerprint-0.49
River stage zero No dependents
++
/ Email::Fingerprint::Cache

NAME

Email::Fingerprint::Cache - Cache observed email fingerprints

VERSION

Version 0.49

SYNOPSIS

    use Email::Fingerprint::Cache;

    my %fingerprints;           # To access cache contents

    # Create a cache
    my $cache     =  new Email::Fingerprint::Cache(
        backend   => "AnyDBM",
        hash      => \%fingerprints,
        file      => $file,             # Created if doesn't exist
        ttl       => 3600 * 24 * 7,     # Purge records after one week
    );

    # Prepare it for use
    $cache->lock or die "Couldn't lock: $!";    # Waits for lock
    $cache->open or die "Couldn't open: $!";

    # Work with fingerprints
    for my (@message_fingerprints) {

        if ($fingerprints{$_}) {
            print "Fingerprint found: $_\n";
            next;
        }

        my $now = time;
        $fingerprints{$_} = $now;

        print "Fingerprint added: $_\n";
    }

    # Get rid of old records
    $cache->purge;

    # Print a listing of all fingerprints
    $cache->dump;

    # Finish up
    $cache->close;
    $cache->unlock;

ATTRIBUTES

METHODS

new

    my $fingerprint =  new Email::Fingerprint::Cache(
        file        => $file,   # Default: .maildups
        backend     => "AnyDBM",  # Default: "AnyDBM"
        ttl         => $sec,    # Default: 3600*24*7
        hash        => $ref,    # Optional
    );

Returns a new Email::Fingerprint::Cache. The cache must still be opened before it can be used.

BUILD

Internal helper method; never called directly by users.

set_file

  $file = $cache->set_file( 'foo' ) or die "Failed to set filename";
  # now $file eq 'foo.db' or 'foo.dir', etc., depending on the backend;
  # it is almost certainly NOT 'foo'.

Sets the file to be used for the cache. Returns the actual filename on success; false on failure.

The actual filename will probably differ from the 'foo', because the backend will usually add an extension or otherwise munge it.

set_file has no effect while the cache file is locked or open!

get_backend

Returns the backend object for this cache.

dump

    # Be a good citizen
    $cache->lock;
    $cache->open;

    $cache->dump;

    # Be a good neighbor
    $cache->close;
    $cache->unlock;

Dump a human-readable version of the contents of the cache. Data is printed in timestamp order.

The cache must first be opened, and should first be locked.

open

    $cache->open or die;

Open the cache file, and tie it to a hash. This is delegated to the backend.

close

  $cache->close;

Close the cache file and untie the hash.

lock

  $cache->lock or die;                  # returns immediately
  $cache->lock( block => 1 ) or die;    # Waits for a lock
  $cache->lock( %opts ) or die;         # Backend-specific options

Lock the DB file to guarantee exclusive access.

unlock

  $cache->unlock or warn "Unlock failed";

Unlock the DB file.

purge

    $cache->purge;                  # Use default TTL
    $cache->purge( ttl => 3600 );   # Everything older than 1 hour

Purge the cache of old entries. This reduces the risk of false positives from things like reused message IDs, but increases the risk of false negatives.

The ttl option specifies the "time to live": cache entries older than that will be purged. The default is one week. If the TTL is zero, then (just as you'd expect) items one second or older will be purged. If you specify a negative TTL, then the cache will be emptied completely.

DESTROY

Clean up the module. If the hash is still tied, we warn the user and call close() on $self.

DEMOLISH

Internal helper method, never called directly by user.

_delegate

Delegate the specified method to the backend. Internal method.

AUTHOR

Len Budney, <lbudney at pobox.com>

BUGS

The dump() method assumes that Perl's time() function returns seconds since the UNIX epoch, 00:00:00 UTC, January 1, 1970. The module will work on architectures with non-standard epochs, but the automated tests will fail.

Please report any bugs or feature requests to bug-email-fingerprint at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Email-Fingerprint. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Email::Fingerprint::Cache

You can also look for information at:

ACKNOWLEDGEMENTS

Email::Fingerprint::Cache is based on caching code in the eliminate_dups script by Peter Samuel and available at http://www.qmail.org/.

COPYRIGHT & LICENSE

Copyright 2006-2011 Len Budney, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.