/ 
File-StatCache-0.01
River stage zero No dependents
/ File::StatCache

Name

File::StatCache - a caching wrapper around the stat() function

Overview

This module implements a cache of information returned by the stat() function. It stores the result of a stat() syscall, to avoid putting excess load on the host's filesystem in case many calls would be generated.

Timeout

By default the cache for any given filename will time out after 10 seconds; so any request for information on the same name after this time will result in another stat() syscall, ensuring fresh information. This timeout is stored in the package variable $File::StatCache::STATTIMEOUT, and can be modified by other modules if required.

Functions

sub get_stat( $path; $now )

    $path

    The path to the filesystem item to stat()

    $now

    Optional. The time to consider as the current time

    Returns

    An object reference to a File::stat object or undef

    This function wraps a call to File::stat::stat(), and caches the result. If the requested file was stat()ed within $STATTIMEOUT seconds, it will not be requested again, but the previous result (i.e. an object reference or undef) will be returned.

    The $now parameter allows some other time than the current time to be used, rather than re-request it from the kernel using the time() function. This allows a succession of tests to be performed in a consistent way, to avoid a race condition.

sub stat( $path )

    $path

    The path to the filesystem item to stat()

    Returns in scalar context

    An object reference to a File::stat object or undef

    Returns in list context

    A 13-element list with fields as the core stat() function would, or an empty list

    This is a drop-in replacement for either the perl core stat() function or the File::stat::stat function, depending whether it is called in list or scalar context. It behaves identically to either of these functions, except that it returns cached results if the cached value is recent enough.

    Note that in the case of failure (i.e. undef in scalar context, empty in list context), the value of $! is not reliable as the reason for error. Error results are not currently cached.

sub get_item_mtime( $path; $now )

    $path

    The path to the filesystem item to stat()

    $now

    Optional. The time to consider as the current time

    Returns

    A scalar containing the item's last modification time, or undef

    This function is equivalent to

    (scalar get_stat( $path, $now ))->mtime

Limitations

  • The shortcut tests (e.g. -f, -r, etc..) will not work with this module.

  • The "last results" filename _ cannot be used; the following code will not work with this module:

    my @stats = stat( _ );

Bugs

  • The value of $! is not preserved for per-file failures. When undef or the empty list are returned, the $! value may not indicate the reason for this particular failure.

Author

Paul Evans <leonerd@leonerd.org.uk>