view release on metacpan or  search on metacpan

lib/CHI.pm  view on Meta::CPAN

If this is a string, a L<Data::Serializer|Data::Serializer> object will be
created, with the string passed as the 'serializer' option and raw=1. Common
options include 'Storable', 'Data::Dumper', and 'YAML'. If this is a hashref,
L<Data::Serializer-E<gt>new|Data::Serializer> will be called with the hash. You
will need to ensure Data::Serializer is installed to use these options.

Otherwise, this must be a L<Data::Serializer|Data::Serializer> object or
another object that implements I<serialize()> and I<deserialize()>.

e.g.

    # Serialize using raw Data::Dumper
    my $cache = CHI->new(serializer => 'Data::Dumper');

    # Serialize using Data::Dumper, compressed and (per Data::Serializer defaults) hex-encoded
    my $cache = CHI->new(serializer => { serializer => 'Data::Dumper', compress => 1 });

    # Serialize using custom object
    my $cache = CHI->new(serializer => My::Custom::Serializer->new())

The default is to use raw Storable.

=item traits [LISTREF]

List of one or more roles to apply to the C<CHI::Driver> class that is
constructed. The roles will automatically be prefixed with
C<CHI::Driver::Role::> unless preceded with a '+'. e.g.

    traits => ['StoresAccessedAt', '+My::CHI::Driver::Role']

=back

=head1 INSTANCE METHODS

The following methods can be called on any cache handle returned from
CHI-E<gt>new(). They are implemented in the L<CHI::Driver|CHI::Driver> package.

=head2 Getting and setting

=over

=item get( $key, [option =E<gt> value, ...] )

Returns the data associated with I<$key>. If I<$key> does not exist or has
expired, returns undef. Expired items are not automatically removed and may be
examined with L</get_object> or L</get_expires_at>.

I<$key> may be followed by one or more name/value parameters:

=over

=item expire_if [CODEREF]

If I<$key> exists and has not expired, call code reference with the
L<CHI::CacheObject|CHI::CacheObject> and L<CHI::Driver|CHI::Driver> as the
parameters. If code returns a true value, C<get> returns undef as if the item
were expired. For example, to treat the cache as expired if I<$file> has
changed since the value was computed:

    $cache->get('foo', expire_if => sub { $_[0]->created_at < (stat($file))[9] });

=item busy_lock [DURATION]

If the value has expired, the get will still return undef, but the expiration
time of the cache entry will be set to the current time plus the specified
L<duration|/DURATION EXPRESSIONS>.  This is used to prevent multiple processes
from recomputing the same expensive value simultaneously. The problem with this
technique is that it doubles the number of writes performed - see
L</expires_variance> for another technique.

=item obj_ref [SCALARREF]

If the item exists in cache (even if expired), place the
L<CHI::CacheObject|CHI::CacheObject> object in the provided SCALARREF.

=back

=item set( $key, $data, [$expires_in | "now" | "never" | options] )

Associates I<$data> with I<$key> in the cache, overwriting any existing entry.
Returns I<$data>.

The third argument to C<set> is optional, and may be either a scalar or a hash
reference. If it is a scalar, it may be the string "now", the string "never",
or else a duration treated as an I<expires_in> value described below. If it is
a hash reference, it may contain one or more of the following options. Most of
these options can be provided with defaults in the cache constructor.

=over

=item expires_in [DURATION]

Amount of time from now until this data expires. I<DURATION> may be an integer
number of seconds or a L<duration expression|/DURATION EXPRESSIONS>.

=item expires_at [INT]

The epoch time at which the data expires.

=item expires_variance [FLOAT]

Controls the variable expiration feature, which allows items to expire a little
earlier than the stated expiration time to help prevent cache miss stampedes.

Value is between 0.0 and 1.0, with 0.0 meaning that items expire exactly when
specified (feature is disabled), and 1.0 meaning that items might expire
anytime from now until the stated expiration time. The default is 0.0. A
setting of 0.10 to 0.25 would introduce a small amount of variation without
interfering too much with intended expiration times.

The probability of expiration increases as a function of how far along we are
in the potential expiration window, with the probability being near 0 at the
beginning of the window and approaching 1 at the end.

For example, in all of the following cases, an item might be considered expired
any time between 15 and 20 minutes, with about a 20% chance at 16 minutes, a
40% chance at 17 minutes, and a 100% chance at 20 minutes.

    my $cache = CHI->new ( ..., expires_variance => 0.25, ... );
    $cache->set($key, $value, '20 min');