Log::Log4perl::Config::Watch - phpMan

NAME
    Log::Log4perl::Config::Watch - Detect file changes

SYNOPSIS
        use Log::Log4perl::Config::Watch;

        my $watcher = Log::Log4perl::Config::Watch->new(
                              file            => "/data/my.conf",
                              check_interval  => 30,
                      );

        while(1) {
            if($watcher->change_detected()) {
                print "Change detected!\n";
            }
            sleep(1);
        }

DESCRIPTION
    This module helps detecting changes in files. Although it comes with the
    "Log::Log4perl" distribution, it can be used independently.

    The constructor defines the file to be watched and the check interval in
    seconds. Subsequent calls to "change_detected()" will

    *   return a false value immediately without doing physical file checks
        if "check_interval" hasn't elapsed.

    *   perform a physical test on the specified file if the number of
        seconds specified in "check_interval" have elapsed since the last
        physical check. If the file's modification date has changed since
        the last physical check, it will return a true value, otherwise a
        false value is returned.

    Bottom line: "check_interval" allows you to call the function
    "change_detected()" as often as you like, without paying the performing
    a significant performance penalty because file system operations are
    being performed (however, you pay the price of not knowing about file
    changes until "check_interval" seconds have elapsed).

    The module clearly distinguishes system time from file system time. If
    your (e.g. NFS mounted) file system is off by a constant amount of time
    compared to the executing computer's clock, it'll just work fine.

    To disable the resource-saving delay feature, just set "check_interval"
    to 0 and "change_detected()" will run a physical file test on every
    call.

    If you already have the current time available, you can pass it on to
    "change_detected()" as an optional parameter, like in

        change_detected($time)

    which then won't trigger a call to "time()", but use the value provided.

  SIGNAL MODE
    Instead of polling time and file changes, "new()" can be instructed to
    set up a signal handler. If you call the constructor like

        my $watcher = Log::Log4perl::Config::Watch->new(
                              file    => "/data/my.conf",
                              signal  => 'HUP'
                      );

    then a signal handler will be installed, setting the object's variable
    "$self->{signal_caught}" to a true value when the signal arrives. Comes
    with all the problems that signal handlers go along with.

  TRIGGER CHECKS
    To trigger a physical file check on the next call to "change_detected()"
    regardless if "check_interval" has expired or not, call

        $watcher->force_next_check();

    on the watcher object.

  DETECT MOVED FILES
    The watcher can also be used to detect files that have moved. It will
    not only detect if a watched file has disappeared, but also if it has
    been replaced by a new file in the meantime.

        my $watcher = Log::Log4perl::Config::Watch->new(
            file           => "/data/my.conf",
            check_interval => 30,
        );

        while(1) {
            if($watcher->file_has_moved()) {
                print "File has moved!\n";
            }
            sleep(1);
        }

    The parameters "check_interval" and "signal" limit the number of
    physical file system checks, similarly as with "change_detected()".

LICENSE
    Copyright 2002-2013 by Mike Schilli <m AT perlmeister.com> and Kevin Goess
    <cpan AT goess.org>.

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

AUTHOR
    Please contribute patches to the project on Github:

        http://github.com/mschilli/log4perl

    Send bug reports or requests for enhancements to the authors via our

    MAILING LIST (questions, bug reports, suggestions/patches):
    log4perl-devel AT lists.net

    Authors (please contact them via the list above, not directly): Mike
    Schilli <m AT perlmeister.com>, Kevin Goess <cpan AT goess.org>

    Contributors (in alphabetical order): Ateeq Altaf, Cory Bennett, Jens
    Berthold, Jeremy Bopp, Hutton Davidson, Chris R. Donnelly, Matisse
    Enzer, Hugh Esco, Anthony Foiani, James FitzGibbon, Carl Franks, Dennis
    Gregorovic, Andy Grundman, Paul Harrington, Alexander Hartmaier David
    Hull, Robert Jacobson, Jason Kohles, Jeff Macdonald, Markus Peter, Brett
    Rann, Peter Rabbitson, Erik Selberg, Aaron Straup Cope, Lars Thegler,
    David Viner, Mac Yang.