NAME

       Cache::Entry - interface for a cache entry

SYNOPSIS

         my Cache::Entry $entry = $cache->entry( $key )
         my $data;
         if ($entry->exists()) {
             $data = $entry->get();
         }
         else {
             $data = get_some_data($key);
             $entry->set($data, '10 minutes');
         }

DESCRIPTION

       Objects derived from Cache::Entry represent an entry in a Cache.  Methods are provided that act upon the
       data in the entry, and allow you to set things like the expiry time.

       Users should not create instances of Cache::Entry directly, but instead use the entry($key) method of a
       Cache instance.

METHODS

       my $cache = $e->cache()
           Returns a reference to the cache object this entry is from.

       my $key = $e->key()
           Returns the cache key this entry is associated with.

       my $bool = $e->exists()
           Returns  a boolean value (1 or 0) to indicate whether there is any data present in the cache for this
           entry.

       $e->set( $data, [ $expiry ] )
           Stores the data into the cache.  The data must be a scalar (if you want to store  more  complex  data
           types, see freeze and thaw below).

           The  expiry  time  may  be  provided  as  an  optional  2nd  argument  and is in the same form as for
           'set_expiry($time)'.

       my $data = $e->get()
           Returns the data from the cache, or undef if the entry doesn't exist.

       my $size = $e->size()
           Returns the size of the entry data, or undef if the entry doesn't exist.

       $e->remove()
           Clear the data for this entry from the cache.

       my $expiry = $e->expiry()
           Returns the expiry time of the entry, in seconds since the epoch.

       $e->set_expiry( $time )
           Set the expiry time in seconds since the epoch, or alternatively using a string  like  '10  minutes'.
           Valid  units are s, second, seconds, sec, m, minute, minutes, min, h, hour, hours, w, week, weeks, M,
           month, months, y, year and years.  You can also  specify  an  absolute  time,  such  as  '16  Nov  94
           22:28:20'  or any other time that Date::Parse can understand.  Finally, the strings 'now' and 'never'
           may also be used.

       my $fh = $e->handle( [$mode, [$expiry] ] )
           Returns an IO::Handle by which data can be read, or written, to the cache.  This is useful if you are
           caching a large amount of data - although it should be noted that  only  some  cache  implementations
           (such as Cache::File) provide an efficient mechanism for implementing this.

           The  optional  mode  argument  can be any of the perl mode strings as used for the open function '<',
           '+<', '>', '+>', '>>' and '+>>'.  Alternatively it can be the corresponding fopen(3)  modes  of  'r',
           'r+', 'w', 'w+', 'a' and 'a+'.  The default mode is '+<' (or 'r+') indicating reading and writing.

           The  second argument is used to set the expiry time for the entry if it doesn't exist already and the
           handle is opened for writing.  It is also used to reset the expiry time if the entry is truncated  by
           opening in the '>' or '+>' modes.  If the expiry is not provided in these situations then the default
           expiry time for the cache is applied.

           Cache  implementations will typically provide locking around cache entries, so that writers will have
           have an exclusive lock and readers a shared one.  Thus the method get() (or obtaining another handle)
           should be avoided whilst a write handle is  held.   Using  set()  or  remove(),  however,  should  be
           supported.   These  clear  the  current  entry  and whilst they do not invalidate open handles, those
           handle will from then on refer to old data and any changes to the data will be discarded.

STORING VALIDITY OBJECTS

       There are two additional set & get methods that can be used to store a validity object that is associated
       with the data in question.  Typically this is useful in conjunction with a validate_callback, and may  be
       used  to  store  a timestamp or similar to validate against.  The validity data stored may be any complex
       data that can be serialized via Storable.

       $e->validity()
       $e->set_validity( $data )

STORING COMPLEX OBJECTS

       The set and get methods only allow for working with simple scalar types, but if you want  to  store  more
       complex  types  they  need  to be serialized first.  To assist with this, the freeze and thaw methods are
       provided.  They are simple wrappers to get & set that use  Storable  to  do  the  serialization  and  de-
       serialization of the data.

       Note,  however,  that  you  must  be  careful  to  ONLY  use 'thaw' on data that was stored via 'freeze'.
       Otherwise the stored data wont actually be in Storable format and it will complain loudly.

       $e->freeze( $data, [ $expiry ] )
           Identical to 'set', except that data may be  any  complex  data  type  that  can  be  serialized  via
           Storable.

       $e->thaw()
           Identical to 'get', except that it will return a complex data type that was set via 'freeze'.

SEE ALSO

       Cache, Cache::File

AUTHOR

        Chris Leishman <chris@leishman.org>
        Based on work by DeWitt Clinton <dewitt@unto.net>

COPYRIGHT

        Copyright (C) 2003-2006 Chris Leishman.  All Rights Reserved.

       This  module  is  distributed  on  an  "AS  IS"  basis, WITHOUT WARRANTY OF ANY KIND, either expressed or
       implied. This program is free software; you can redistribute or modify it under the same  terms  as  Perl
       itself.

       $Id: Entry.pm,v 1.8 2006/01/31 15:23:58 caleishm Exp $

perl v5.34.0                                       2022-06-09                                  Cache::Entry(3pm)