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


Version 0.49


    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";

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

        print "Fingerprint added: $_\n";

    # Get rid of old records

    # Print a listing of all fingerprints

    # Finish up




    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.


Internal helper method; never called directly by users.


  $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!


Returns the backend object for this cache.


    # Be a good citizen


    # Be a good neighbor

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.


    $cache->open or die;

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



Close the cache file and untie the hash.


  $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.


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

Unlock the DB file.


    $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.


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


Internal helper method, never called directly by user.


Delegate the specified method to the backend. Internal method.


Len Budney, <lbudney at>


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, or through the web interface at I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


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

    perldoc Email::Fingerprint::Cache

You can also look for information at:


Email::Fingerprint::Cache is based on caching code in the eliminate_dups script by Peter Samuel and available at


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.