Config::Watch(3)					User Contributed Perl Documentation					  Config::Watch(3)

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!
";
	       }
	       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

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

       o   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!
";
	       }
	       sleep(1);
	   }

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

COPYRIGHT AND LICENSE

       Copyright 2002-2009 by Mike Schilli <m@perlmeister.com> and Kevin Goess <cpan@goess.org>.

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

perl v5.12.1							    2010-02-07							  Config::Watch(3)