NAME
    Tie::Hash::LRU - LRU hashes for Perl (XS implementation)

SYNOPSIS
        use Tie::Hash::LRU;

        $lru = tie %h, 'Tie::Hash::LRU', 100; # will hold only 100 entries

        $h{'bar'} = 'foo';
        $h{'foo'} = 'bar'; 
    
        print "foo = $h{'foo'}\n"; # puts 'foo' in front of the queue

        ...
    
        # simple LRU cache

        $foo = $h{'foo'};
        if (!defined $foo) {
            # fetch foo from somewhere 
            $foo = get('foo');
            $h{'foo'} = $foo;
        }


        # Iterating over entries without any impact on LRU queue

        (tied %h)->autohit(0); # disables LRU

        foreach (keys %h) {
            $h{$_} = ...
        }

        while (my ($k, $v) = each %h) { # this one actually won't even work
                                        # with autohit
            ...
        }

        (tied %h)->autohit(1); # enables LRU back on


        # Accessing LRU hash without tied overhead (significantly faster).
        # We are using perl's tie API to do this.

        $lru = Tie::Hash::LRU->TIEHASH(100); 

        $lru->STORE('foo', 'bar');
        $foo = $lru->FETCH('foo');

        if ($lru->EXISTS('foo')) {
            ...
        }

        $lru->DELETE('foo');


        # And the fastest way would be to also avoid looking into @ISA 
        # as with previous example: 

        Tie::Hash::LRU::STORE($lru, 'foo', 'bar');
        $foo = Tie::Hash::LRU::FETCH($lru, 'foo');

DESCRIPTION
    This module provides XS implementation of the LRU algorithm. It merely
    puts hash entry in front of the queue each time this entry accessed.

    Tied hashes have significant overhead and cannot perform as fast as a
    simple subroutine call. But the benefits of linked lists are still
    there, i.e. writes are almost as fast as reads, which is not the case
    for pure-perl implementations.

    You can use this module without any tied overhead by using perl's tie
    API. See perltie for more information.

METHODS
    $lru = tie %h, 'Tie::Hash::LRU', 100;
            Create tied LRU hash that will hold 100 entries.

    $lru->autohit(1), (tied %h)->autohit(1)
            Enables/disables LRU hits for tied hash. LRU hits are enabled by
            default.

    $lru = Tie::Hash::LRU->TIEHASH(100);
            Creating raw untied LRU hash. This is actually the same object
            as returned by "tie %h ...".

    $lru->STORE('foo', 'bar')
            Store entry into LRU hash directly.

    $foo = $lru->FETCH('foo')
            Fetch entry from LRU hash directly.

    $lru->DELETE('foo', 'bar')
            Delete key from LRU hash directly.

BENCHMARK
    Sample benchmark, generated by eg/lrubench.pl:

        cache_hit:
                                   Rate (higher is better)
        Cache::FastMmap          94.5/s
        Cache::FastMmap (raw)     107/s
        Tie::Cache::LRU (tied)    839/s
        Cache::LRU               1152/s
        Tie::Cache::LRU (direct) 1184/s
        Tie::Hash::LRU (tied)    2352/s
        Tie::Hash::LRU (direct)  7808/s

        cache_set:
                                 s/iter (lower is better)
        Tie::Cache::LRU (tied)     1.78
        Tie::Cache::LRU (direct)   1.57
        Cache::LRU                 1.06
        Tie::Hash::LRU (tied)     0.409
        Tie::Hash::LRU (direct)   0.241

    Tied here means using tied hash to get and set values. And direct--
    using the tie API ("$lru->FETCH($key)", etc.), i.e. eliminating tied
    overhead.

SEE ALSO
    Cache::LRU, Tie::Cache::LRU, Cache::FastMmap, Tie::Hash::Indexed

AUTHOR
    Alexandr Gomoliako <zzz@zzz.org.ua>

LICENSE
    This module is based on Marcus Holland-Moritz's Tie::Hash::Indexed.
    Copyright 2003 Marcus Holland-Moritz.

    Copyright 2011 Alexandr Gomoliako. All rights reserved.

    This module is free software. It may be used, redistributed and/or
    modified under the same terms as Perl itself.